Hilfe-Center / API und Webhooks

API und Webhooks

Erstelle Ads aus deiner eigenen App und lass dich benachrichtigen, wenn sie fertig sind, mit signierten Webhooks.

Die vollständige Referenz mit allen Feldern findest du in der API-Dokumentation. API-Doku

API-Schlüssel

Inhaber und Admins erstellen Schlüssel unter Entwickler. Ein Schlüssel wird nur einmal angezeigt: Speichere ihn in den geheimen Einstellungen deiner App, niemals im Code, der im Browser ausgeführt wird. Ads, die mit einem Schlüssel erstellt werden, zählen zum Plan deines Workspaces, genauso wie Ads, die in der App erstellt werden.

Authorization: Bearer rl_live_…

Ein Ad erstellen

Sende ein Briefing, optional mit einer Marke, Medien und Formaten. Die Antwort enthält eine Job-ID; das Ad wird im Hintergrund erstellt.

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

Füge "draft": true hinzu, um zuerst ein Storyboard zu erhalten, und "variants": 3 für mehrere Storyboards mit unterschiedlichen Konzepten. Rendere später einen Entwurf mit POST /v1/jobs/{id}/render.

Status und Downloads

GET /v1/jobs/{id} gibt den Status zurück (wartet in der Warteschlange, dann Verarbeitungsschritte, dann erledigt, Entwurf oder fehlgeschlagen) und, wenn erledigt, signierte Download-Links pro Format sowie eine Vorschau. Die Links sind nur vorübergehend: Fordere den Job erneut an, um neue Links zu erhalten.

Webhooks

Mit einem webhook_url senden wir einen POST an deine Adresse, wenn die Anzeige fertig, fehlgeschlagen oder ein Storyboard bereit ist. Das Ereignis steht im X-Reelamo-Event-Header und im Body: job.done, job.failed oder job.draft. Der Body enthält dasselbe Job-Objekt wie der Status-Endpunkt, plus eine eindeutige delivery_id.

• Die Adresse muss öffentlich erreichbar sein; interne und private Netzwerkadressen werden abgelehnt. Verwende https.
• Antworte innerhalb von 15 Sekunden mit einem 2xx-Status. Erledige die eigentliche Arbeit nach der Antwort.
• Wenn die Zustellung fehlschlägt, versuchen wir es nach 10 Sekunden, 1 Minute, 5 Minuten und 30 Minuten erneut. Weiterleitungen werden nicht verfolgt.
• Eine Auslieferung kann gelegentlich zweimal ankommen: Verwende delivery_id oder die Job-ID, um Duplikate zu ignorieren.

Signaturen verifizieren

Jeder Webhook wird mit dem Webhook-Geheimnis deines Workspaces signiert (unter Entwickler). Der Header X-Reelamo-Signature sieht aus wie t=1760000000,v1=… wobei v1 ein HMAC-SHA256 aus dem Zeitstempel, einem Punkt und dem Rohtextkörper ist. Prüfe ihn, bevor du dem Inhalt vertraust, und lehne alte Zeitstempel ab:

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

Grenzen und bewährte Vorgehensweisen

• Dein Plan legt fest, wie viele Ads gleichzeitig erstellt werden können und wie lang sie sein dürfen; Anfragen über dem Limit führen zu einem Fehler mit einer klaren Meldung (zum Beispiel Status 402, wenn deine monatlichen Ads aufgebraucht sind, oder 429, wenn zu viele Ads gleichzeitig erstellt werden).
• Sende einen Idempotency-Key-Header mit POST /v1/jobs, um eine Anfrage sicher erneut zu versuchen, ohne ein zweites Ad zu erstellen.
• Drehe einen Schlüssel oder das Webhook-Geheimnis sofort aus, wenn es möglicherweise geleakt ist.