Help center / API and webhooks

API and webhooks

Create ads from your own app and get notified when they're ready, with signed webhooks.

The full reference with every field is in the API documentation. API docs

API keys

Owners and admins create keys under Developers. A key is shown once: store it in your app's secret settings, never in code that runs in a browser. Ads made with a key count towards your workspace's plan, just like ads made in the app.

Authorization: Bearer rl_live_…

Create an ad

Send a brief, optionally with a brand, media and formats. The answer contains a job ID; the ad is made in the background.

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

Add "draft": true to get a storyboard first, and "variants": 3 for several storyboards with different concepts. Render a draft later with POST /v1/jobs/{id}/render.

Status and downloads

GET /v1/jobs/{id} returns the status (queued, then processing steps, then done, draft or failed) and, when done, signed download links per format and a thumbnail. Links are temporary: request the job again for fresh links.

Webhooks

With a webhook_url we send a POST to your address when the ad is done, failed or a storyboard is ready. The event is in the X-Reelamo-Event header and the body: job.done, job.failed or job.draft. The body has the same job object as the status endpoint, plus a unique delivery_id.

• The address must be publicly reachable; internal and private network addresses are refused. Use https.
• Reply with a 2xx status within 15 seconds. Do the real work after replying.
• If delivery fails, we try again after 10 seconds, 1 minute, 5 minutes and 30 minutes. Redirects are not followed.
• A delivery can occasionally arrive twice: use delivery_id or the job ID to ignore duplicates.

Verifying signatures

Every webhook is signed with your workspace's webhook secret (under Developers). The X-Reelamo-Signature header looks like t=1760000000,v1=… where v1 is an HMAC-SHA256 of the timestamp, a dot and the raw body. Check it before you trust the content, and reject old timestamps:

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

Limits and good practice

• Your plan sets how many ads can be made at the same time and how long they can be; requests over a limit get an error with a clear message (for example status 402 when your monthly ads are used up, or 429 when too many ads are being made at once).
• Send an Idempotency-Key header with POST /v1/jobs to safely retry a request without creating a second ad.
• Rotate a key or the webhook secret straight away if it may have leaked.