Centro de ajuda / API e webhooks

API e webhooks

Cria ads a partir da tua própria app e recebe notificações quando estiverem prontos, com webhooks assinados.

A referência completa com todos os campos está na documentação da API. Documentação da API

Chaves da API

Os proprietários e administradores criam chaves em Developers. Uma chave é mostrada apenas uma vez: guarda-a nas definições secretas da tua app, nunca em código que corre no browser. Os anúncios feitos com uma chave contam para o plano da tua workspace, tal como os anúncios feitos na app.

Authorization: Bearer rl_live_…

Criar um ad

Envia um briefing, opcionalmente com uma marca, media e formatos. A resposta contém um ID de tarefa; o ad é criado em 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"
  }'

Adiciona "draft": true para obter primeiro um storyboard e "variants": 3 para vários storyboards com conceitos diferentes. Renderiza um draft mais tarde com POST /v1/jobs/{id}/render.

Estado e downloads

GET /v1/jobs/{id} devolve o estado (na fila, depois passos de processamento, depois concluído, draft ou falhado) e, quando concluído, links de download assinados por formato e uma miniatura. Os links são temporários: pede novamente a tarefa para obter novos links.

Webhooks

Com um webhook_url enviamos um POST para o teu endereço quando o ad termina, falha ou um storyboard fica pronto. O evento vem no cabeçalho X-Reelamo-Event e no corpo: job.done, job.failed ou job.draft. O corpo tem o mesmo objeto job que o endpoint de estado, mais um delivery_id único.

• O endereço tem de estar publicamente acessível; endereços de redes internas e privadas são recusados. Usa https.
• Responde com um estado 2xx no prazo de 15 segundos. Faz o trabalho real depois de responder.
• Se a entrega falhar, tentamos novamente após 10 segundos, 1 minuto, 5 minutos e 30 minutos. Não seguimos redirecionamentos.
• Uma entrega pode, ocasionalmente, chegar duas vezes: usa delivery_id ou o ID do job para ignorar duplicados.

Verificação de assinaturas

Cada webhook é assinado com o segredo de webhook do teu workspace (em Developers). O cabeçalho X-Reelamo-Signature tem o aspeto t=1760000000,v1=… em que v1 é um HMAC-SHA256 do timestamp, um ponto e o corpo bruto. Verifica-o antes de confiares no conteúdo e rejeita timestamps antigos:

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 e boas práticas

• O teu plano define quantos anúncios podem ser criados ao mesmo tempo e quanto tempo podem durar; pedidos acima do limite devolvem um erro com uma mensagem clara (por exemplo, estado 402 quando os teus anúncios mensais acabam, ou 429 quando estão a ser criados demasiados anúncios ao mesmo tempo).
• Envia um cabeçalho Idempotency-Key com POST /v1/jobs para repetir um pedido em segurança sem criar um segundo ad.
• Gira imediatamente uma chave ou o segredo do webhook se houver possibilidade de terem sido expostos.