API Reference

Look-up rápido. Pra aprender fazendo, vai no Quickstart.

Base URL

https://video-analysis-hu5ixjipbq-rj.a.run.app

Região: South America East (São Paulo). Latência média BR ~30ms, US-East ~140ms.

Autenticação

Todos endpoints autenticados usam o header:

x-api-key: vap_xxxxxxxxxxxxxxxxxxxxxxx

Key inválida/ausente → 401. Ver Segurança.

Endpoints

Método	Path	Auth	Descrição
GET	/v1/health	Nenhuma	Healthcheck. Sempre 200 se o serviço tá vivo.
GET	/v1/ready	Nenhuma	Readiness probe. 200 se engines estão carregados, 503 se não.
GET	/v1/capabilities	Nenhuma	Lista dimensões disponíveis no servidor + features de cada.
POST	/v1/analyze	x-api-key	Cria job de análise. Retorna job_id imediatamente; processamento é assíncrono.
GET	/v1/result/{job_id}	x-api-key	Recupera status + resultado do job. Status: queued \| processing \| completed \| failed.

POST /v1/analyze — payload

{
  "video_url": "https://exemplo.com/video.mp4",
  "dimensions": ["audio", "scenes", "ocr"],
  "callback_url": "https://meusite.com/webhooks/video-analysis",
  "callback_secret": null,
  "tier": "fast",
  "metadata": {
    "user_id": "internal-user-123",
    "request_id": "req-uuid"
  }
}

video_url (obrigatório) — URL pública HTTPS do vídeo (até 500MB ou 30min, o que vier primeiro)
dimensions (obrigatório) — subset das dimensões habilitadas no produto. Validado server-side
callback_url (opcional) — sobrescreve o webhook default do produto
callback_secret (opcional) — HMAC secret pra esta request específica. Default: secret do produto
tier (opcional) — "fast" (default) ou "accurate" (~2x mais caro, mais preciso em OCR/transcript)
metadata (opcional) — qualquer JSON, devolvido no webhook/result intacto. Use pra correlacionar

Códigos de erro

HTTP	Nome	Quando dispara
400	Bad Request	Payload inválido (campos faltando, tipo errado, video_url malformada)
401	Unauthorized	x-api-key ausente, errada, ou produto deletado
402	Payment Required	Budget mensal do produto atingiu o cap. Aumentar cap ou aguardar virar mês
403	Forbidden	Dimensão pedida não está habilitada pro produto (configura em /dashboard/products/[id]/edit)
404	Not Found	job_id inexistente em /v1/result/{job_id}
429	Too Many Requests	Rate limit do produto excedido. Header Retry-After indica segundos pra retry
500	Internal Server Error	Falha não-tratada no servidor. Reporta abrindo issue + job_id
503	Service Unavailable	Engines ainda warming up. Retry com backoff exponencial

Webhook (job concluído)

Se configuraste webhook_url no produto ou na chamada, te mandamos um POST quando o job termina:

{
  "job_id": "job_abc...",
  "status": "completed",
  "tenant_id": "viralcutter-yz5Xec",
  "duration_sec": 42.3,
  "cost_brl": 0.18,
  "results": {
    "audio": { "rms_mean": 0.13, "rms_peaks": [...] },
    "scenes": [{"scene_id":1,"start_sec":0,"end_sec":3.2,"kind":"hard_cut"}, ...],
    "ocr": [{"text":"OFERTA","bbox":[120,80,200,40],"confidence":0.94}, ...]
  }
}

Assinatura: header X-Webhook-Signature: sha256=<hmac> calculado com HMAC-SHA256(webhook_secret, raw_body). Sempre verifica antes de processar.

Replay protection: header X-Webhook-Timestamp em Unix epoch. Rejeita se mais velho que 5min.

Retry policy: exponencial 0/15s/1m/5m/30m. Após 5 falhas, vai pra DLQ no nosso lado. Tu pode reprocessar via /v1/admin/dlq (em breve no portal, hoje só via API).

Rate limits & budget

Rate limit — configurado por produto (req/min). Excedeu → 429 com Retry-After: <sec> header
Budget cap — limite mensal em BRL por produto. Atingiu → 402 até virar mês ou aumentar cap
Concurrency — até 4 jobs simultâneos por tenant (default). Pedir aumento via suporte

Schema versioning

Todo response inclui schema_version. Major bumps (2.x) são breaking — anunciados com 90 dias de aviso. Minor (1.x) são aditivos.

Atual: 1.0.0.