POST/api/v1/generate/video-studio

Vídeo do Studio

Bearer tokenImplementadoescopo generate:video

Contrato OpenAPI

operationId: generateStudioVideo · Implementada

Parâmetros

Nome	Local	Obrigatório	Tipo
`Idempotency-Key`	header	não	string

Schema do request

JSON

{
  "additionalProperties": true,
  "properties": {
    "aspectRatio": {
      "enum": [
        "auto",
        "21:9",
        "16:9",
        "4:3",
        "1:1",
        "3:4",
        "9:16"
      ],
      "type": "string"
    },
    "avatarId": {
      "maxLength": 200,
      "type": "string"
    },
    "durationSec": {
      "maximum": 15,
      "minimum": 4,
      "type": "integer"
    },
    "hookId": {
      "maxLength": 200,
      "type": "string"
    },
    "mode": {
      "maxLength": 200,
      "minLength": 1,
      "type": "string"
    },
    "productId": {
      "maxLength": 200,
      "minLength": 1,
      "type": "string"
    },
    "resolution": {
      "enum": [
        "480p",
        "720p"
      ],
      "type": "string"
    },
    "settingId": {
      "maxLength": 200,
      "type": "string"
    },
    "userPrompt": {
      "maxLength": 2000,
      "type": "string"
    }
  },
  "required": [
    "mode",
    "productId",
    "resolution"
  ],
  "type": "object"
}

Respostas

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

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. Omitido → 15 (base do débito e da geração)

O custo é por resolução e por segundo: costsByResolution no catálogo é o preço do vídeo de 15s (duração máxima); o débito escala linear com a duração — ceil(custo15s × durationSec / 15). Ex.: 720p custa 335 créditos em 15s e 90 em 4s. O débito acontece na criação da task, sempre sobre a MESMA duração enviada ao motor. 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.