POST/api/v1/generate/video-ugc

Vídeo UGC

Bearer tokenImplementadoescopo generate:video

Contrato OpenAPI

operationId: generateUgcVideo · Implementada

Baixar o contrato OpenAPI 3.1.

Schema do request

JSON

{
  "additionalProperties": true,
  "properties": {
    "accent": {
      "default": "auto",
      "enum": [
        "auto",
        "paulista",
        "carioca",
        "mineiro",
        "nordestino"
      ],
      "type": "string"
    },
    "action": {
      "minLength": 1,
      "type": "string"
    },
    "backgroundSound": {
      "type": "string"
    },
    "callbackUrl": {
      "format": "uri",
      "type": "string"
    },
    "combinedImages": {
      "items": {
        "format": "uri",
        "type": "string"
      },
      "maxItems": 2,
      "minItems": 1,
      "type": "array"
    },
    "emotion": {
      "default": "auto",
      "enum": [
        "auto",
        "feliz",
        "triste",
        "raiva",
        "medo",
        "surpreso",
        "nojo",
        "empolgado",
        "calmo",
        "brincalhao",
        "serio",
        "autoritario"
      ],
      "type": "string"
    },
    "gender": {
      "default": "auto",
      "enum": [
        "auto",
        "feminino",
        "masculino"
      ],
      "type": "string"
    },
    "language": {
      "default": "auto",
      "enum": [
        "auto",
        "pt-BR",
        "pt-PT",
        "en-US",
        "es-ES"
      ],
      "type": "string"
    },
    "productDescription": {
      "type": "string"
    },
    "speech": {
      "maxLength": 90,
      "minLength": 1,
      "type": "string"
    },
    "template": {
      "enum": [
        "general",
        "selfie",
        "selling",
        "asmr",
        "podcast",
        "car",
        "mirror-selfie",
        "stedicam",
        "cctv",
        "handheld"
      ],
      "type": "string"
    },
    "voiceType": {
      "default": "auto",
      "enum": [
        "auto",
        "sussurro",
        "rouca",
        "aspera",
        "suave",
        "grave",
        "aguda",
        "anasalada"
      ],
      "type": "string"
    }
  },
  "required": [
    "template",
    "combinedImages",
    "action",
    "speech"
  ],
  "type": "object"
}

Respostas

HTTP	Significado
`202`	Geração aceita para processamento assíncrono
`default`	Erro padronizado

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.