Centrum nápovědy / API a webhooks

API a webhooks

Vytvářejte reklamy z vlastní aplikace a dostávejte upozornění, až budou hotové, pomocí podepsaných webhooků.

Úplný přehled všech polí najdeš v dokumentaci API. API dokumentace

API keys

Vlastníci a administrátoři vytvářejí klíče v sekci Vývojáři. Klíč se zobrazí jen jednou: ulož si ho do tajného nastavení své aplikace, nikdy ne do kódu, který běží v prohlížeči. Ady vytvořené pomocí klíče se počítají do plánu vašeho pracovního prostoru stejně jako ady vytvořené v aplikaci.

Authorization: Bearer rl_live_…

Vytvořit ad

Pošlete zadání, volitelně se značkou, médii a formáty. Odpověď obsahuje ID úlohy; reklama se vytvoří na pozadí.

curl https://reelamo.com/v1/jobs \
  -H "Authorization: Bearer $REELAMO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Sourdough baked fresh every morning. 20% off this weekend.",
    "brand_id": "brd_…",
    "duration": 15,
    "formats": ["9x16", "1x1"],
    "webhook_url": "https://example.com/hooks/reelamo"
  }'

Přidej "draft": true, pokud chceš nejdřív storyboard, a "variants": 3 pro několik storyboardů s různými koncepty. Draft pak můžeš později vyrenderovat přes POST /v1/jobs/{id}/render.

Stav a stahování

GET /v1/jobs/{id} vrátí stav (ve frontě, pak kroky zpracování, pak dokončeno, draft nebo selhalo) a po dokončení podepsané odkazy ke stažení pro jednotlivé formáty a náhled. Odkazy jsou dočasné: pro nové odkazy si vyžádej job znovu.

Webhooky

Pomocí webhook_url pošleme na tvou adresu POST, když je ad hotový, selže nebo je storyboard připravený. Událost je v hlavičce X-Reelamo-Event a v těle: job.done, job.failed nebo job.draft. Tělo obsahuje stejný objekt job jako stavový endpoint, plus jedinečné delivery_id.

• Adresa musí být veřejně dostupná; interní a soukromé síťové adresy nejsou povolené. Použij https.
• Odpovězte do 15 sekund stavem 2xx. Skutečnou práci udělejte až po odpovědi.
• Když doručení selže, zkusíme to znovu po 10 sekundách, 1 minutě, 5 minutách a 30 minutách. Přesměrování se nesledují.
• Doručení se může výjimečně objevit dvakrát: použij delivery_id nebo ID úlohy, abys duplicitní položky ignoroval.

Ověřování podpisů

Každý webhook je podepsaný tajemstvím webhooku tvého workspace (v sekci Vývojáři). Hlavička X-Reelamo-Signature vypadá jako t=1760000000,v1=… kde v1 je HMAC-SHA256 z časového údaje, tečky a nezpracovaného těla. Před důvěrou v obsah podpis ověř a staré časové údaje odmítej:

import hashlib, hmac, time

def verify(body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts, sig = int(parts["t"]), parts["v1"]
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig) and abs(time.time() - ts) < tolerance

Limity a osvědčené postupy

• Tvůj plán určuje, kolik reklam lze vytvářet najednou a jak dlouhé mohou být; požadavky nad limit vrátí chybu s jasnou zprávou (například stav 402, když máš vyčerpané měsíční reklamy, nebo 429, když se vytváří příliš mnoho reklam najednou).
• Pošlete hlavičku Idempotency-Key s POST /v1/jobs, abyste mohli požadavek bezpečně zopakovat a nevytvořili druhou reklamu.
• Okamžitě otočte klíč nebo tajný klíč webhooku, pokud mohlo dojít k jeho úniku.