Centre d’aide / API et webhooks

API et webhooks

Créez des publicités depuis votre propre application et soyez averti quand elles sont prêtes, avec des webhooks signés.

La référence complète avec chaque champ se trouve dans la documentation de l’API. Docs API

Clés API

Les propriétaires et les administrateurs créent des clés dans Développeurs. Une clé n’est affichée qu’une seule fois : enregistre-la dans les paramètres secrets de ton app, jamais dans du code exécuté dans un navigateur. Les publicités créées avec une clé sont comptées dans le plan de ton workspace, tout comme les publicités créées dans l’app.

Authorization: Bearer rl_live_…

Créer une publicité

Envoyez un brief, éventuellement avec une marque, des médias et des formats. La réponse contient un ID de tâche ; la publicité est créée en arrière-plan.

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

Ajoute "draft": true pour obtenir d’abord un storyboard, et "variants": 3 pour plusieurs storyboards avec des concepts différents. Rends ensuite un draft plus tard avec POST /v1/jobs/{id}/render.

Statut et téléchargements

GET /v1/jobs/{id} renvoie l’état (en file d’attente, puis étapes de traitement, puis terminé, brouillon ou échoué) et, une fois terminé, des liens de téléchargement signés par format ainsi qu’une miniature. Les liens sont temporaires : redemande la tâche pour obtenir de nouveaux liens.

Webhooks

Avec webhook_url, nous envoyons une requête POST à ton adresse lorsque l'ad est terminé, a échoué ou qu'un storyboard est prêt. L'événement se trouve dans l'en-tête X-Reelamo-Event et le corps : job.done, job.failed ou job.draft. Le corps contient le même objet job que le point de terminaison de statut, plus un delivery_id unique.

• L’adresse doit être accessible publiquement ; les adresses réseau internes et privées sont refusées. Utilise https.
• Répondez avec un statut 2xx dans les 15 secondes. Faites le vrai travail après avoir répondu.
• En cas d’échec de livraison, nous réessayons après 10 secondes, 1 minute, 5 minutes et 30 minutes. Les redirections ne sont pas suivies.
• Une livraison peut parfois arriver deux fois : utilise delivery_id ou l’ID du job pour ignorer les doublons.

Vérification des signatures

Chaque webhook est signé avec le secret webhook de ton workspace (dans Développeurs). L’en-tête X-Reelamo-Signature ressemble à t=1760000000,v1=… où v1 est un HMAC-SHA256 du timestamp, d’un point et du corps brut. Vérifie-le avant de faire confiance au contenu, et rejette les anciens 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

Limites et bonnes pratiques

• Votre offre définit le nombre de publicités pouvant être créées en même temps et leur durée ; les demandes dépassant une limite renvoient une erreur avec un message clair (par exemple le statut 402 lorsque vos publicités mensuelles sont épuisées, ou 429 lorsque trop de publicités sont créées en même temps).
• Envoyez un en-tête Idempotency-Key avec POST /v1/jobs pour réessayer une requête en toute sécurité sans créer une deuxième publicité.
• Faites immédiatement tourner une clé ou le secret du webhook s’il a pu être divulgué.