POST/api/v1/generate/video-studio

Vídeo do Studio

Bearer tokenescopo generate:video

Gera um vídeo de produto pelo Marketing Studio (avatar/influencer promovendo um produto em vários formatos: UGC, tutorial, unboxing, provador virtual, hyper motion e mais). Responde 202 Accepted com um taskId; acompanhe por polling em GET /api/v1/tasks/:id (o resultUrl traz o mp4 quando completed).

Escopo necessário: generate:video.

Pré-requisitos

Produto — crie em POST /api/v1/studio/products e use o id como productId.
Catálogo — leia GET /api/v1/studio/catalog para os mode (slug), hookId e settingId (ids) válidos e suas políticas.
Avatar (opcional) — crie em POST /api/v1/studio/avatars se o modo permitir/exigir.

Body

Campo	Tipo	Obrigatório	Valores / restrições
`mode`	string	sim	slug de um modo do catálogo (ex.: `ugc`, `ugc_how_to`, `product_showcase`)
`productId`	string	sim	`id` de um produto criado no Studio
`resolution`	string	sim	`480p` ou `720p`
`userPrompt`	string	não	Roteiro/falas do vídeo (máx. 2000). Respeitado verbatim. Ignorado em modos com `speechPolicy: "forbidden"`.
`hookId`	string	não	id de um gancho do catálogo (abertura que prende o scroll)
`settingId`	string	não	id de um cenário do catálogo (ambiente)
`avatarId`	string	não	`id` de um avatar criado no Studio (conforme `avatarPolicy` do modo)
`aspectRatio`	string	não	`auto`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4` ou `9:16`
`durationSec`	number	não	Inteiro de 4 a 15

O custo é por resolução (veja costsByResolution no catálogo) e é debitado na criação da task. O modelo de vídeo real é resolvido pelo engine e não é exposto.

Exemplo de request

cURL

curl -X POST https://avatrix.io/api/v1/generate/video-studio \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c-studio-001" \
  -d '{
    "mode": "ugc",
    "productId": "prod_abc123",
    "resolution": "720p",
    "userPrompt": "Gente, esse produto salvou minha rotina — olha isso!",
    "hookId": "clx_hook_product_hit",
    "settingId": "clx_setting_bedroom",
    "aspectRatio": "9:16",
    "durationSec": 15
  }'

Resposta — 202

JSON

{ "success": true, "data": { "taskId": "...", "status": "queued", "variationGroup": "..." } }

Acompanhe em GET /api/v1/tasks/:id: a task evolui até completed (com resultUrl = mp4) ou failed. Ver Ciclo de vida da task.

Idempotência

Envie o header Idempotency-Key (opcional, máx. 128 chars). Requisições repetidas com a mesma chave (24h) retornam a resposta original sem novo débito. Ver Idempotência.

Erros relevantes

Código	HTTP	Quando
`VALIDATION_ERROR`	400	campos inválidos (`mode`/`productId`/`resolution`, etc)
`INSUFFICIENT_CREDITS`	402	saldo insuficiente
`FORBIDDEN`	403	Studio indisponível no plano, ou token sem `generate:video`
`RATE_LIMITED` / `MAX_CONCURRENT_TASKS`	429	rate limit ou 20 tasks simultâneas
`GENERATION_FAILED`	502	produto/avatar inexistente, modo inválido ou falha do engine
`PROVIDER_UNAVAILABLE`	503	engine do Studio indisponível
`FEATURE_DISABLED`	503	Marketing Studio indisponível

Ver Códigos de erro e Escopos.