Hjälpcenter / API och webhooks

API och webhooks

Skapa ads från din egen app och få avisering när de är klara, med signerade webhooks.

Den fullständiga referensen med alla fält finns i API-dokumentationen. API-dokumentation

API-nycklar

Ägare och administratörer skapar nycklar under Utvecklare. En nyckel visas bara en gång: spara den i appens hemliga inställningar, aldrig i kod som körs i en webbläsare. Annonser som skapas med en nyckel räknas mot ditt workspaces plan, precis som annonser som skapas i appen.

Authorization: Bearer rl_live_…

Skapa en ad

Skicka en brief, valfritt med ett varumärke, media och format. Svaret innehåller ett jobb-ID; ad:en skapas i bakgrunden.

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

Lägg till "draft": true för att få en storyboard först, och "variants": 3 för flera storyboards med olika koncept. Rendera ett utkast senare med POST /v1/jobs/{id}/render.

Status och nedladdningar

GET /v1/jobs/{id} returnerar statusen (köad, sedan bearbetningssteg, sedan klar, draft eller failed) och, när den är klar, signerade nedladdningslänkar per format samt en miniatyrbild. Länkarna är tillfälliga: begär jobbet igen för nya länkar.

Webhooks

Med en webhook_url skickar vi en POST till din adress när annonsen är klar, misslyckas eller när en storyboard är klar. Händelsen finns i rubriken X-Reelamo-Event och i brödtexten: job.done, job.failed eller job.draft. Brödtexten har samma job-objekt som statusändpunkten, plus en unik delivery_id.

• Adressen måste vara publikt nåbar; interna och privata nätverksadresser avvisas. Använd https.
• Svara med en 2xx-status inom 15 sekunder. Gör det riktiga arbetet efter att du svarat.
• Om leveransen misslyckas försöker vi igen efter 10 sekunder, 1 minut, 5 minuter och 30 minuter. Omdirigeringar följs inte.
• En leverans kan ibland komma två gånger: använd delivery_id eller job ID för att ignorera dubbletter.

Verifierar signaturer

Varje webhook signeras med workspace:ns webhook-hemlighet (under Utvecklare). X-Reelamo-Signature-headern ser ut som t=1760000000,v1=… där v1 är en HMAC-SHA256 av tidsstämpeln, en punkt och råtexten i body:n. Kontrollera den innan du litar på innehållet och avvisa gamla tidsstämplar:

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

Gränser och god praxis

• Din plan anger hur många ads som kan skapas samtidigt och hur långa de får vara; begäranden över en gräns ger ett fel med ett tydligt meddelande (till exempel status 402 när dina månatliga ads är slut, eller 429 när för många ads skapas samtidigt).
• Skicka en Idempotency-Key-rubrik med POST /v1/jobs för att säkert försöka igen utan att skapa en andra ad.
• Rotera en nyckel eller webhook-hemligheten direkt om den kan ha läckt.