Centrul de ajutor / API și webhook-uri

API și webhook-uri

Creează ad-uri din propria aplicație și primește notificări când sunt gata, cu webhook-uri semnate.

Referința completă cu toate câmpurile este în documentația API. Documentație API

Chei API

Proprietarii și administratorii creează chei în secțiunea Dezvoltatori. O cheie este afișată o singură dată: salveaz-o în setările secrete ale aplicației tale, niciodată în codul care rulează într-un browser. Ads-urile făcute cu o cheie se contorizează la planul workspace-ului tău, la fel ca ads-urile făcute în aplicație.

Authorization: Bearer rl_live_…

Creează un ad

Trimite un brief, opțional cu un brand, materiale și formate. Răspunsul conține un job ID; ad-ul este creat în fundal.

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"
  }'

Adaugă "draft": true pentru a obține mai întâi un storyboard și "variants": 3 pentru mai multe storyboard-uri cu concepte diferite. Randază mai târziu un draft cu POST /v1/jobs/{id}/render.

Stare și descărcări

GET /v1/jobs/{id} returnează statusul (în coadă, apoi pașii de procesare, apoi finalizat, draft sau eșuat) și, când e finalizat, linkuri de descărcare semnate pentru fiecare format și o miniatură. Linkurile sunt temporare: cere jobul din nou pentru linkuri noi.

Webhook-uri

Cu un webhook_url, trimitem un POST la adresa ta când ad-ul este gata, a eșuat sau când un storyboard este gata. Evenimentul este în antetul X-Reelamo-Event și în corp: job.done, job.failed sau job.draft. Corpul conține același obiect job ca endpointul de status, plus un delivery_id unic.

• Adresa trebuie să fie accesibilă public; adresele din rețele interne și private sunt refuzate. Folosește https.
• Răspunde cu un status 2xx în maximum 15 secunde. Fă treaba reală după ce ai răspuns.
• Dacă livrarea eșuează, încercăm din nou după 10 secunde, 1 minut, 5 minute și 30 de minute. Redirecționările nu sunt urmate.
• O livrare poate ajunge uneori de două ori: folosește delivery_id sau ID-ul jobului pentru a ignora duplicatele.

Verificarea semnăturilor

Fiecare webhook este semnat cu secretul webhook al workspace-ului tău (în Developers). Antetul X-Reelamo-Signature arată ca t=1760000000,v1=… unde v1 este un HMAC-SHA256 al timestamp-ului, un punct și body-ul brut. Verifică-l înainte să ai încredere în conținut și respinge timestamp-urile vechi:

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

Limite și bune practici

• Planul tău stabilește câte ad-uri pot fi create în același timp și cât de lungi pot fi; solicitările care depășesc o limită primesc o eroare cu un mesaj clar (de exemplu, status 402 când ad-urile lunare sunt epuizate sau 429 când sunt create prea multe ad-uri simultan).
• Trimite un header Idempotency-Key împreună cu POST /v1/jobs pentru a reîncerca în siguranță o cerere fără a crea un al doilea ad.
• Rotește imediat o cheie sau secretul webhook dacă este posibil să fi fost compromis.