Centro de ayuda / API y webhooks

API y webhooks

Crea ads desde tu propia app y recibe una notificación cuando estén listos, con webhooks firmados.

La referencia completa con todos los campos está en la documentación de la API. Documentación de la API

Claves de API

Los propietarios y administradores crean claves en Desarrolladores. La clave solo se muestra una vez: guárdala en la configuración secreta de tu app, nunca en código que se ejecute en un navegador. Los anuncios creados con una clave cuentan para el plan de tu espacio de trabajo, igual que los anuncios creados en la app.

Authorization: Bearer rl_live_…

Crear un ad

Envía un briefing, opcionalmente con una marca, recursos y formatos. La respuesta contiene un ID de tarea; el anuncio se crea en segundo plano.

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

Añade "draft": true para obtener primero un storyboard, y "variants": 3 para varios storyboards con conceptos diferentes. Luego renderiza un draft con POST /v1/jobs/{id}/render.

Estado y descargas

GET /v1/jobs/{id} devuelve el estado (en cola, luego pasos de procesamiento, luego terminado, borrador o fallido) y, cuando termina, enlaces de descarga firmados por formato y una miniatura. Los enlaces son temporales: vuelve a solicitar el trabajo para obtener enlaces nuevos.

Webhooks

Con un webhook_url enviamos un POST a tu dirección cuando el ad termina, falla o un storyboard está listo. El evento va en el encabezado X-Reelamo-Event y en el cuerpo: job.done, job.failed o job.draft. El cuerpo tiene el mismo objeto job que el endpoint de estado, más un delivery_id único.

• La dirección debe ser accesible públicamente; se rechazan las direcciones de redes internas y privadas. Usa https.
• Responde con un estado 2xx en un plazo de 15 segundos. Haz el trabajo real después de responder.
• Si la entrega falla, lo intentamos de nuevo después de 10 segundos, 1 minuto, 5 minutos y 30 minutos. No se siguen redirecciones.
• Una entrega a veces puede llegar dos veces: usa delivery_id o el ID del job para ignorar duplicados.

Verificación de firmas

Cada webhook se firma con el secreto de webhook de tu workspace (en Developers). La cabecera X-Reelamo-Signature se ve así: t=1760000000,v1=… donde v1 es un HMAC-SHA256 de la marca de tiempo, un punto y el cuerpo en bruto. Compruébalo antes de confiar en el contenido y rechaza marcas de tiempo antiguas:

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

Límites y buenas prácticas

• Tu plan establece cuántos anuncios se pueden crear al mismo tiempo y cuánto pueden durar; las solicitudes que superen un límite devuelven un error con un mensaje claro (por ejemplo, estado 402 cuando se agotan tus anuncios mensuales, o 429 cuando se están creando demasiados anuncios a la vez).
• Envía el encabezado Idempotency-Key con POST /v1/jobs para reintentar una solicitud con seguridad sin crear un segundo anuncio.
• Gira una clave o el secreto del webhook de inmediato si puede haberse filtrado.