Hjelpesenter / API og webhooks

API og webhooks

Lag ad-er fra din egen app og få beskjed når de er klare, med signerte webhooks.

Den fullstendige referansen med alle felter finnes i API-dokumentasjonen. API-dokumentasjon

API-nøkler

Eiere og administratorer oppretter nøkler under Utviklere. En nøkkel vises bare én gang: lagre den i appens hemmelige innstillinger, aldri i kode som kjøres i en nettleser. Ad-er laget med en nøkkel teller med i arbeidsområdets plan, akkurat som ad-er laget i appen.

Authorization: Bearer rl_live_…

Lag en ad

Send en brief, valgfritt med et merke, medier og formater. Svaret inneholder en jobb-ID; ad-en lages i bakgrunnen.

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

Legg til "draft": true for å få et storyboard først, og "variants": 3 for flere storyboards med ulike konsepter. Render et utkast senere med POST /v1/jobs/{id}/render.

Status og nedlastinger

GET /v1/jobs/{id} returnerer statusen (i kø, deretter behandlingssteg, deretter ferdig, draft eller failed) og, når den er ferdig, signerte nedlastingslenker per format og et miniatyrbilde. Lenker er midlertidige: be om jobben på nytt for nye lenker.

Webhooker

Med en webhook_url sender vi en POST til adressen din når annonsen er ferdig, feilet eller et storyboard er klart. Hendelsen står i X-Reelamo-Event-headeren og i bodyen: job.done, job.failed eller job.draft. Bodyen har det samme job-objektet som status-endepunktet, pluss en unik delivery_id.

• Adressen må være offentlig tilgjengelig; interne og private nettverksadresser avvises. Bruk https.
• Svar med en 2xx-status innen 15 sekunder. Gjør det faktiske arbeidet etter at du har svart.
• Hvis leveringen mislykkes, prøver vi igjen etter 10 sekunder, 1 minutt, 5 minutter og 30 minutter. Omdirigeringer følges ikke.
• En levering kan av og til komme to ganger: bruk delivery_id eller job-ID-en for å ignorere duplikater.

Verifiserer signaturer

Hver webhook er signert med arbeidsområdets webhook-hemmelighet (under Utviklere). X-Reelamo-Signature-overskriften ser ut som t=1760000000,v1=… der v1 er en HMAC-SHA256 av tidsstempelet, et punktum og den rå kroppen. Sjekk den før du stoler på innholdet, og avvis gamle tidsstempler:

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

Grenser og god praksis

• Planen din bestemmer hvor mange annonser som kan lages samtidig og hvor lange de kan være; forespørsler over grensen gir en feil med en tydelig melding (for eksempel status 402 når de månedlige annonsene er brukt opp, eller 429 når for mange annonser lages samtidig).
• Send en Idempotency-Key-header med POST /v1/jobs for å kunne prøve en forespørsel på nytt trygt uten å opprette en ny ad.
• Roter en nøkkel eller webhook-hemmeligheten med en gang hvis den kan ha lekket.