Hjælpecenter / API og webhooks

API og webhooks

Lav ads fra din egen app, og få besked, når de er klar, med signerede webhooks.

Den fulde reference med alle felter findes i API-dokumentationen. API-dokumentation

API-nøgler

Ejere og administratorer opretter nøgler under Developers. En nøgle vises kun én gang: gem den i din apps hemmelige indstillinger, aldrig i kode, der kører i en browser. Ads lavet med en nøgle tæller med i dit workspaces plan, ligesom ads lavet i appen.

Authorization: Bearer rl_live_…

Opret en ad

Send et brief, valgfrit med et brand, medier og formater. Svaret indeholder et job-id; ad'en bliver lavet i baggrunden.

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

Tilføj "draft": true for at få et storyboard først, og "variants": 3 for flere storyboards med forskellige koncepter. Render et draft senere med POST /v1/jobs/{id}/render.

Status og downloads

GET /v1/jobs/{id} returnerer status (køet, derefter behandlingstrin, derefter færdig, draft eller failed) og, når det er færdigt, signerede downloadlinks pr. format samt en miniature. Links er midlertidige: anmod om jobbet igen for nye links.

Webhooks

Med en webhook_url sender vi en POST til din adresse, når annoncen er færdig, fejler, eller et storyboard er klar. Hændelsen står i X-Reelamo-Event-headeren og i body: job.done, job.failed eller job.draft. Bodyen har det samme job-objekt som status-endpointet, plus en unik delivery_id.

• Adressen skal være offentligt tilgængelig; interne og private netværksadresser afvises. Brug https.
• Svar med en 2xx-status inden for 15 sekunder. Gør det egentlige arbejde efter svaret.
• Hvis levering mislykkes, prøver vi igen efter 10 sekunder, 1 minut, 5 minutter og 30 minutter. Omdirigeringer følges ikke.
• En levering kan nogle gange komme to gange: brug delivery_id eller job-id'et til at ignorere dubletter.

Verificering af signaturer

Hver webhook er signeret med dit workspace's webhook-hemmelighed (under Udviklere). X-Reelamo-Signature-headeren ser sådan ud: t=1760000000,v1=… hvor v1 er en HMAC-SHA256 af tidsstemplet, et punktum og den rå body. Tjek den, før du stoler på indholdet, og afvis 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

Grænser og god praksis

• Din plan bestemmer, hvor mange ads der kan laves på samme tid, og hvor lange de må være; anmodninger over en grænse giver en fejl med en tydelig besked (for eksempel status 402 når dine månedlige ads er brugt op, eller 429 når der laves for mange ads på én gang).
• Send en Idempotency-Key-header med POST /v1/jobs for sikkert at prøve en anmodning igen uden at oprette en anden ad.
• Rotér en nøgle eller webhook-hemmeligheden med det samme, hvis den kan være lækket.