POST/api/v1/generate/video-ugc

Vídeo UGC

Bearer tokenescopo generate:video

Geração de vídeo UGC (avatar falando uma fala curta, com ação e voz configuráveis). Responde 202 Accepted com um taskId; acompanhe o resultado por polling em GET /api/v1/tasks/:id ou via webhook.

Escopo necessário: generate:video.

Valores fixos (não configuráveis nesta API): modelo veo3.1-fast, aspectRatio 9:16, qualidade 720p, duração 8s. As imagens de combinedImages viram os frames inicial e final: com 1 URL ela é duplicada (frame inicial = frame final); com 2 URLs, a primeira é o frame inicial e a segunda o frame final.

Body

Campo	Tipo	Obrigatório	Valores / restrições
`template`	string	sim	ID de um template UGC: `general`, `selfie`, `selling`, `asmr`, `podcast`, `car`, `mirror-selfie`, `stedicam`, `cctv` ou `handheld` (veja todos os modelos em aqui)
`combinedImages`	string[]	sim	Lista de 1 ou 2 URLs HTTPS (avatar ou avatar + produto já combinados).
`action`	string	sim	Descrição da ação/gesto do personagem
`speech`	string	sim	Roteiro falado pelo usuário — máx. 90 caracteres
`voiceType`	string	não	`auto` (default), `sussurro`, `rouca`, `aspera`, `suave`, `grave`, `aguda`, `anasalada`
`emotion`	string	não	`auto` (default), `feliz`, `triste`, `raiva`, `medo`, `surpreso`, `nojo`, `empolgado`, `calmo`, `brincalhao`, `serio`, `autoritario`
`gender`	string	não	`auto` (default), `feminino`, `masculino`
`language`	string	não	`auto` (default), `pt-BR`, `pt-PT`, `en-US`, `es-ES`
`accent`	string	não	`auto` (default), `paulista`, `carioca`, `mineiro`, `nordestino`
`backgroundSound`	string	não	Descrição de SFX/som de fundo
`productDescription`	string	não	Descrição do produto
`callbackUrl`	string	não	URL HTTPS para webhook de conclusão

Os campos enumerados (voiceType, emotion, gender, language, accent) aceitam exclusivamente os valores acima (minúsculos, sem acentos e sem espaços). Valores fora da lista retornam 400 VALIDATION_ERROR indicando os valores aceitos. Todos têm default auto.

Exemplo de request

cURL

curl -X POST https://avatrix.io/api/v1/generate/video-ugc \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c-ugc-001" \
  -d '{
    "template": "general",
    "combinedImages": [
        "https://storage.avatrix.io/generated/AMABB58D/image-9fdf12ba-ce73-499f-8437-a8d73e0cb3ea.png",
        "https://storage.avatrix.io/generated/AMABB58D/image-fab9b200-4d3b-4e87-a91f-df3209a0d66e.png"
      ],
    "action": "segura o produto e sorri para a câmera",
    "speech": "Esse produto mudou a minha rotina!",
    "voiceType": "suave",
    "emotion": "empolgado",
    "language": "pt-BR"
  }'

Resposta — 202

JSON

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

O status: "queued" é só o rótulo de criação. No polling (GET /api/v1/tasks/:id) a task evolui por pending → submitted → processing → completed (com resultUrl) 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
`INSUFFICIENT_CREDITS`	402	saldo insuficiente
`FORBIDDEN`	403	token sem `generate:video`
`RATE_LIMITED` / `MAX_CONCURRENT_TASKS`	429	rate limit ou 20 tasks simultâneas
`GENERATION_FAILED`	502	falha do provider
`PROVIDER_UNAVAILABLE`	503	provider indisponível

Ver Códigos de erro e Escopos.