POST/api/v1/generate/video-creative

Vídeo criativo

Bearer tokenescopo generate:video

Geração de vídeo "creative". 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.

Cada modelo (model) tem seus próprios modos (creativeDetailMode), proporções, resoluções e opções. Escolha primeiro o modelo, depois o modo — o restante do payload depende dessa combinação. As seções por modelo abaixo trazem as regras e um exemplo de payload por modo.

Visão geral dos modelos

Modelo	Quando usar	Modos	Resoluções	Proporções	Duração
`veo3.1-fast`	Padrão — alta qualidade e ótimo realismo	`ref_images`, `start_end`	`720p`, `1080p`	`16:9`, `9:16`	fixa (não aceita `duration`)
`seedance-2`	Duração flexível e até 1080p; referência multimodal	`text_to_video`, `ref_images`, `start_end`, `reference_multi`	`480p`, `720p`, `1080p`	`adaptive`, `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `21:9`	4–15s (default 5)
`seedance-2-fast`	Variante mais rápida e econômica (sem 1080p)	iguais ao Seedance 2	`480p`, `720p`	iguais ao Seedance 2	4–15s (default 5)
`kling-3.0`	Múltiplas cenas e elementos referenciados	`text_to_video`, `ref_images`, `start_end`, `multi_shot`	via `modeVariant` (`720p`/`1080p`/`4K`)	`16:9`, `1:1`, `9:16`	3–15s (default 5)
`gemini-omni-flash`	Vídeo 720p com áudio nativo (Google); text-to-video ou 1–3 fotos de referência	`text_to_video`, `ref_images`	`720p`	`9:16`, `16:9`	3–10s (default 5)

Campos do body

Campo	Tipo	Obrigatório?	Observação
`model`	string	sim	Um dos 5 modelos da tabela acima
`creativeDetailMode`	string	não	Modo de geração; default por modelo (ver cada seção)
`prompt`	string	condicional	Obrigatório, exceto em `start_end` e `multi_shot`
`aspectRatio`	string	não	Depende do modelo; default por modelo
`quality`	string	não	Depende do modelo; em Kling é derivada do `modeVariant`
`duration`	inteiro	não	Em segundos; faixa por modelo. Veo não aceita
`modeVariant`	string	não	Kling apenas: `standard` (default), `pro`, `4k`
`referenceImages`	string[]	condicional	URLs HTTPS públicas; quantidade exigida varia por modo (máx. 4 no total)
`referenceVideoUrls`	string[]	não	Seedance `reference_multi`: até 3 URLs HTTPS de vídeo (MP4 com faststart)
`referenceAudioUrls`	string[]	não	Seedance `reference_multi`: até 3 URLs HTTPS de áudio
`multiShots`	`{ prompt, duration }[]`	condicional	Kling `multi_shot`: 1–5 cenas; cada `duration` 1–12s; soma ≤ 15s
`videoModelOptions`	object	não	Opções de áudio por modelo (ver abaixo)
`callbackUrl`	string	não	URL HTTPS (host não-privado) para o webhook

Áudio (videoModelOptions): por padrão o áudio vem desligado. Para ativar, envie videoModelOptions.generateAudio: true (Seedance) ou videoModelOptions.sound: true (Kling). O modo multi_shot (Kling) sempre gera áudio.

Veo 3.1 Fast — `veo3.1-fast`

Modelo padrão, com alta qualidade e realismo. Clipes de duração fixa — não aceita o campo duration.

Proporções: 16:9 (default), 9:16.
Resoluções (quality): 720p (default), 1080p.
Modos: ref_images (default), start_end.
Áudio: não configurável neste modelo.

Modo `ref_images` (default)

Usa de 1 a 3 imagens de referência como base. prompt é obrigatório.

cURL

curl -X POST "https://avatrix.io/api/v1/generate/video-creative" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-fast",
    "creativeDetailMode": "ref_images",
    "prompt": "A woman walking through a neon-lit city at night, cinematic",
    "aspectRatio": "16:9",
    "quality": "720p",
    "referenceImages": ["https://example.com/reference.jpg"]
  }'

Modo `start_end`

Interpola entre dois frames: exige exatamente 2 imagens (inicial e final). prompt é opcional.

cURL

curl -X POST "https://avatrix.io/api/v1/generate/video-creative" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-fast",
    "creativeDetailMode": "start_end",
    "aspectRatio": "16:9",
    "quality": "1080p",
    "referenceImages": [
      "https://example.com/start-frame.jpg",
      "https://example.com/end-frame.jpg"
    ]
  }'

Seedance 2 — `seedance-2`

Duração flexível (4–15s) e suporte a 1080p. Tem o conjunto mais completo de modos, incluindo referência multimodal.

Proporções: adaptive, 1:1, 4:3, 3:4, 16:9 (default), 9:16, 21:9.
Resoluções (quality): 480p, 720p (default), 1080p.
Duração: inteiro de 4 a 15s (default 5).
Modos: text_to_video (default), ref_images, start_end, reference_multi.
Áudio: videoModelOptions.generateAudio: true para ativar (default desligado).

Modo `text_to_video` (default)

Gera só a partir do prompt (obrigatório); não aceita imagens.

cURL

curl -X POST "https://avatrix.io/api/v1/generate/video-creative" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2",
    "creativeDetailMode": "text_to_video",
    "prompt": "Aerial drone shot over a tropical coastline at sunrise",
    "aspectRatio": "16:9",
    "quality": "1080p",
    "duration": 6,
    "videoModelOptions": { "generateAudio": true }
  }'

Modo `ref_images`

De 1 a 3 imagens de referência. prompt obrigatório.

cURL

curl -X POST "https://avatrix.io/api/v1/generate/video-creative" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2",
    "creativeDetailMode": "ref_images",
    "prompt": "Cinematic shot inspired by the reference images",
    "aspectRatio": "16:9",
    "quality": "720p",
    "duration": 5,
    "referenceImages": [
      "https://example.com/ref-1.jpg",
      "https://example.com/ref-2.jpg"
    ]
  }'

Modo `start_end`

Exatamente 2 imagens (inicial e final). prompt opcional.

cURL

curl -X POST "https://avatrix.io/api/v1/generate/video-creative" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2",
    "creativeDetailMode": "start_end",
    "aspectRatio": "16:9",
    "quality": "720p",
    "duration": 5,
    "referenceImages": [
      "https://example.com/start-frame.jpg",
      "https://example.com/end-frame.jpg"
    ]
  }'

Modo `reference_multi`

Referências multimodais para guiar estilo e movimento: imagens (até 3), referenceVideoUrls (até 3) e referenceAudioUrls (até 3). prompt obrigatório. A duração dos vídeos de referência é detectada automaticamente.

cURL

curl -X POST "https://avatrix.io/api/v1/generate/video-creative" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2",
    "creativeDetailMode": "reference_multi",
    "prompt": "Match the style and motion of the reference clips",
    "aspectRatio": "16:9",
    "quality": "720p",
    "duration": 5,
    "referenceImages": ["https://example.com/style-ref.jpg"],
    "referenceVideoUrls": [
      "https://example.com/ref-clip-1.mp4",
      "https://example.com/ref-clip-2.mp4"
    ],
    "referenceAudioUrls": ["https://example.com/ref-audio.mp3"]
  }'

Seedance 2 Fast — `seedance-2-fast`

Variante mais rápida e econômica do Seedance 2. Modos, proporções, duração e opções são idênticos ao Seedance 2 — a única diferença é a resolução máxima: suporta 480p e 720p (default 720p), sem 1080p.

cURL

curl -X POST "https://avatrix.io/api/v1/generate/video-creative" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-fast",
    "creativeDetailMode": "text_to_video",
    "prompt": "A skateboarder gliding through an empty parking garage",
    "aspectRatio": "9:16",
    "quality": "720p",
    "duration": 5
  }'

Kling 3.0 — `kling-3.0`

Foco em múltiplas cenas e elementos referenciados. A resolução é derivada do modeVariant, não do campo quality:

`modeVariant`	Resolução
`standard` (default)	`720p`
`pro`	`1080p`
`4k`	`4K`

Proporções: 16:9 (default), 1:1, 9:16.
Duração: inteiro de 3 a 15s (default 5).
Modos: text_to_video (default), ref_images, start_end, multi_shot.
Áudio: videoModelOptions.sound: true para ativar; multi_shot sempre gera áudio.

Se enviar quality, ele precisa corresponder à resolução do modeVariant escolhido (ex.: pro → 1080p). O mais simples é só enviar modeVariant.

Modo `text_to_video` (default)

Gera só a partir do prompt (obrigatório); não aceita imagens.

cURL

curl -X POST "https://avatrix.io/api/v1/generate/video-creative" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "creativeDetailMode": "text_to_video",
    "prompt": "A hummingbird hovering over a flower in slow motion",
    "aspectRatio": "16:9",
    "modeVariant": "standard",
    "duration": 5
  }'

Modo `ref_images`

Exige exatamente 1 imagem (usada como primeiro frame). prompt obrigatório.

cURL

curl -X POST "https://avatrix.io/api/v1/generate/video-creative" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "creativeDetailMode": "ref_images",
    "prompt": "The character starts dancing energetically",
    "modeVariant": "pro",
    "duration": 5,
    "referenceImages": ["https://example.com/character.jpg"]
  }'

Modo `start_end`

Exatamente 2 imagens (inicial e final). prompt opcional. Exemplo em 4K:

cURL

curl -X POST "https://avatrix.io/api/v1/generate/video-creative" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "creativeDetailMode": "start_end",
    "aspectRatio": "16:9",
    "modeVariant": "4k",
    "duration": 5,
    "referenceImages": [
      "https://example.com/start-frame.jpg",
      "https://example.com/end-frame.jpg"
    ]
  }'

Modo `multi_shot`

Cria de 1 a 5 cenas, cada uma com seu próprio prompt e duration (1–12s); a soma das durações deve ser ≤ 15s. Não usa prompt de topo nem referenceImages; o áudio é sempre gerado.

cURL

curl -X POST "https://avatrix.io/api/v1/generate/video-creative" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-3.0",
    "creativeDetailMode": "multi_shot",
    "aspectRatio": "16:9",
    "modeVariant": "standard",
    "multiShots": [
      { "prompt": "Wide shot of a chef plating a dish", "duration": 4 },
      { "prompt": "Close-up of sauce being drizzled", "duration": 4 },
      { "prompt": "Final reveal of the finished plate", "duration": 4 }
    ]
  }'

Gemini Omni Flash — `gemini-omni-flash`

Modelo do Google (Interactions API). Gera vídeo 720p com áudio nativo, de 3 a 10 segundos. Provedor único (Google AI Studio), sem fallback.

Proporções: 9:16 (default), 16:9.
Resoluções (quality): 720p (único).
Modos: text_to_video (default), ref_images.
Duração: 3–10s (default 5).
Áudio: nativo, sempre presente (não configurável).

Modo `text_to_video` (default)

Gera o vídeo a partir do prompt. prompt é obrigatório.

cURL

curl -X POST "https://avatrix.io/api/v1/generate/video-creative" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash",
    "creativeDetailMode": "text_to_video",
    "prompt": "A woman walking through a neon-lit city at night, cinematic",
    "aspectRatio": "9:16",
    "duration": 5
  }'

Modo `ref_images`

Aceita de 1 a 3 imagens de referência (referenceImages). O task interno do modelo é escolhido pela quantidade: 1 imagem → image_to_video (a imagem é animada); 2 a 3 imagens → reference_to_video (as imagens guiam o personagem/ objeto numa cena nova). O prompt é obrigatório.

cURL

# 1 imagem — anima a imagem
curl -X POST "https://avatrix.io/api/v1/generate/video-creative" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash",
    "creativeDetailMode": "ref_images",
    "prompt": "subtle camera movement, cinematic",
    "aspectRatio": "9:16",
    "duration": 5,
    "referenceImages": ["https://example.com/photo.jpg"]
  }'

cURL

# 2-3 imagens — referência de personagem/objeto numa cena nova
curl -X POST "https://avatrix.io/api/v1/generate/video-creative" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash",
    "creativeDetailMode": "ref_images",
    "prompt": "the character walking through a neon-lit city at night, cinematic",
    "aspectRatio": "9:16",
    "duration": 5,
    "referenceImages": [
      "https://example.com/character.jpg",
      "https://example.com/outfit.jpg"
    ]
  }'

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, ≤128 chars, TTL 24h). Repetir a mesma chave retorna a resposta original (202 com o taskId original), sem novo débito. A concorrência é limitada a 20 tasks simultâneas por usuário. Ver Idempotência.

Custo

Cobrança por segundo de vídeo, conforme o modelo, a resolução e a duração (multi_shot soma a duração das cenas; Veo tem duração fixa). Ativar áudio pode ter acréscimo. No modo Seedance reference_multi, a duração dos vídeos de referência também entra no cálculo.

Erros relevantes

Código	HTTP	Quando
`VALIDATION_ERROR`	400	`model`/`creativeDetailMode` inválidos, `prompt` ausente quando exigido, regras de imagens/`multiShots`/`duration`/`quality`/`aspectRatio` violadas, `Idempotency-Key` > 128
`INSUFFICIENT_CREDITS`	402	saldo insuficiente
`FORBIDDEN`	403	token sem `generate:video`
`RATE_LIMITED` / `MAX_CONCURRENT_TASKS`	429	rate limit ou 20 tasks simultâneas
`INTERNAL_ERROR`	500	erro interno ao processar a cobrança
`GENERATION_FAILED`	502	falha do provider
`PROVIDER_UNAVAILABLE`	503	provider indisponível

Ver Códigos de erro e Escopos.

Visão geral dos modelos

Campos do body

Veo 3.1 Fast — veo3.1-fast

Modo ref_images (default)

Modo start_end

Seedance 2 — seedance-2

Modo text_to_video (default)

Modo ref_images

Modo start_end

Modo reference_multi

Seedance 2 Fast — seedance-2-fast

Kling 3.0 — kling-3.0

Modo text_to_video (default)

Modo ref_images

Modo start_end

Modo multi_shot

Gemini Omni Flash — gemini-omni-flash

Modo text_to_video (default)

Modo ref_images

Resposta — 202

Idempotência

Custo

Erros relevantes

Veo 3.1 Fast — `veo3.1-fast`

Modo `ref_images` (default)

Modo `start_end`

Seedance 2 — `seedance-2`

Modo `text_to_video` (default)

Modo `ref_images`

Modo `start_end`

Modo `reference_multi`

Seedance 2 Fast — `seedance-2-fast`

Kling 3.0 — `kling-3.0`

Modo `text_to_video` (default)

Modo `ref_images`

Modo `start_end`

Modo `multi_shot`

Gemini Omni Flash — `gemini-omni-flash`

Modo `text_to_video` (default)

Modo `ref_images`