POST/api/v1/generate/video-creative

Vídeo criativo

Bearer tokenImplementadoescopo generate:video

Contrato OpenAPI

operationId: generateCreativeVideo · Implementada

Parâmetros

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

Schema do request

JSON

{
  "additionalProperties": true,
  "allOf": [
    {
      "anyOf": [
        {
          "properties": {
            "model": {
              "const": "kling-avatar-2"
            }
          },
          "required": [
            "model"
          ]
        },
        {
          "required": [
            "prompt"
          ]
        },
        {
          "properties": {
            "creativeDetailMode": {
              "enum": [
                "start_end",
                "multi_shot",
                "audio_to_video"
              ],
              "type": "string"
            }
          },
          "required": [
            "creativeDetailMode"
          ]
        }
      ]
    },
    {
      "oneOf": [
        {
          "not": {
            "required": [
              "duration"
            ]
          },
          "properties": {
            "aspectRatio": {
              "enum": [
                "16:9",
                "9:16"
              ],
              "type": "string"
            },
            "creativeDetailMode": {
              "enum": [
                "ref_images",
                "start_end"
              ],
              "type": "string"
            },
            "model": {
              "const": "veo3.1-fast"
            },
            "quality": {
              "enum": [
                "720p",
                "1080p"
              ],
              "type": "string"
            }
          },
          "required": [
            "model"
          ]
        },
        {
          "properties": {
            "aspectRatio": {
              "enum": [
                "adaptive",
                "1:1",
                "4:3",
                "3:4",
                "16:9",
                "9:16",
                "21:9"
              ],
              "type": "string"
            },
            "creativeDetailMode": {
              "enum": [
                "text_to_video",
                "ref_images",
                "start_end",
                "reference_multi"
              ],
              "type": "string"
            },
            "duration": {
              "maximum": 15,
              "minimum": 4,
              "type": "integer"
            },
            "model": {
              "const": "seedance-2"
            },
            "quality": {
              "enum": [
                "480p",
                "720p",
                "1080p"
              ],
              "type": "string"
            }
          },
          "required": [
            "model"
          ]
        },
        {
          "properties": {
            "aspectRatio": {
              "enum": [
                "adaptive",
                "1:1",
                "4:3",
                "3:4",
                "16:9",
                "9:16",
                "21:9"
              ],
              "type": "string"
            },
            "creativeDetailMode": {
              "enum": [
                "text_to_video",
                "ref_images",
                "start_end",
                "reference_multi"
              ],
              "type": "string"
            },
            "duration": {
              "maximum": 15,
              "minimum": 4,
              "type": "integer"
            },
            "model": {
              "const": "seedance-2-fast"
            },
            "quality": {
              "enum": [
                "480p",
                "720p"
              ],
              "type": "string"
            }
          },
          "required": [
            "model"
          ]
        },
        {
          "properties": {
            "aspectRatio": {
              "enum": [
                "16:9",
                "1:1",
                "9:16"
              ],
              "type": "string"
            },
            "creativeDetailMode": {
              "enum": [
                "text_to_video",
                "ref_images",
                "start_end",
                "multi_shot"
              ],
              "type": "string"
            },
            "duration": {
              "maximum": 15,
              "minimum": 3,
              "type": "integer"
            },
            "model": {
              "const": "kling-3.0"
            },
            "quality": {
              "enum": [
                "720p",
                "1080p",
                "4K"
              ],
              "type": "string"
            }
          },
          "required": [
            "model"
          ]
        },
        {
          "properties": {
            "aspectRatio": {
              "enum": [
                "21:9",
                "16:9",
                "4:3",
                "1:1",
                "3:4",
                "9:16"
              ],
              "type": "string"
            },
            "creativeDetailMode": {
              "enum": [
                "text_to_video",
                "ref_images",
                "start_end"
              ],
              "type": "string"
            },
            "duration": {
              "maximum": 15,
              "minimum": 5,
              "type": "integer"
            },
            "model": {
              "const": "h3-max"
            },
            "quality": {
              "enum": [
                "480p",
                "768p",
                "1080p"
              ],
              "type": "string"
            }
          },
          "required": [
            "model",
            "prompt"
          ]
        },
        {
          "properties": {
            "aspectRatio": {
              "enum": [
                "adaptive",
                "1:1",
                "4:3",
                "3:4",
                "16:9",
                "9:16",
                "21:9"
              ],
              "type": "string"
            },
            "creativeDetailMode": {
              "enum": [
                "text_to_video",
                "ref_images",
                "start_end",
                "reference_multi"
              ],
              "type": "string"
            },
            "duration": {
              "maximum": 30,
              "minimum": 4,
              "type": "integer"
            },
            "model": {
              "const": "seedance-2.5"
            },
            "quality": {
              "enum": [
                "480p",
                "720p",
                "1080p"
              ],
              "type": "string"
            }
          },
          "required": [
            "model",
            "prompt"
          ]
        },
        {
          "not": {
            "required": [
              "duration"
            ]
          },
          "oneOf": [
            {
              "properties": {
                "referenceFileIds": {
                  "maxItems": 0,
                  "type": "array"
                },
                "referenceImages": {
                  "minItems": 1,
                  "type": "array"
                }
              },
              "required": [
                "referenceImages"
              ]
            },
            {
              "properties": {
                "referenceFileIds": {
                  "minItems": 1,
                  "type": "array"
                },
                "referenceImages": {
                  "maxItems": 0,
                  "type": "array"
                }
              },
              "required": [
                "referenceFileIds"
              ]
            }
          ],
          "properties": {
            "aspectRatio": {
              "enum": [
                "adaptive"
              ],
              "type": "string"
            },
            "creativeDetailMode": {
              "const": "audio_to_video"
            },
            "modeVariant": {
              "const": "standard"
            },
            "model": {
              "const": "kling-avatar-2"
            },
            "quality": {
              "enum": [
                "standard"
              ],
              "type": "string"
            },
            "referenceAudioUrls": {
              "description": "Um áudio WAV ou MP3 público de 2 a 60 segundos; o servidor detecta a duração para cobrança.",
              "items": {
                "$ref": "#/components/schemas/HttpsMediaUrl"
              },
              "maxItems": 1,
              "minItems": 1,
              "type": "array"
            },
            "referenceFileIds": {
              "maxItems": 1,
              "type": "array"
            },
            "referenceImages": {
              "maxItems": 1,
              "type": "array"
            },
            "referenceVideoUrls": {
              "maxItems": 0,
              "type": "array"
            }
          },
          "required": [
            "model",
            "referenceAudioUrls"
          ]
        },
        {
          "properties": {
            "aspectRatio": {
              "enum": [
                "9:16",
                "16:9"
              ],
              "type": "string"
            },
            "creativeDetailMode": {
              "enum": [
                "text_to_video",
                "ref_images",
                "reference_to_video"
              ],
              "type": "string"
            },
            "duration": {
              "maximum": 10,
              "minimum": 3,
              "type": "integer"
            },
            "model": {
              "const": "gemini-omni-flash"
            },
            "quality": {
              "enum": [
                "360p",
                "720p"
              ],
              "type": "string"
            }
          },
          "required": [
            "model"
          ]
        }
      ]
    }
  ],
  "properties": {
    "aspectRatio": {
      "enum": [
        "adaptive",
        "1:1",
        "4:3",
        "3:4",
        "16:9",
        "9:16",
        "21:9"
      ],
      "type": "string"
    },
    "callbackUrl": {
      "$ref": "#/components/schemas/HttpsMediaUrl"
    },
    "creativeDetailMode": {
      "enum": [
        "text_to_video",
        "ref_images",
        "start_end",
        "reference_multi",
        "multi_shot",
        "reference_to_video",
        "audio_to_video"
      ],
      "type": "string"
    },
    "duration": {
      "maximum": 30,
      "minimum": 3,
      "type": "integer"
    },
    "modeVariant": {
      "enum": [
        "standard",
        "pro",
        "4k"
      ],
      "type": "string"
    },
    "model": {
      "enum": [
        "veo3.1-fast",
        "seedance-2",
        "seedance-2-fast",
        "kling-3.0",
        "gemini-omni-flash",
        "h3-max",
        "seedance-2.5",
        "kling-avatar-2"
      ],
      "type": "string"
    },
    "multiShots": {
      "description": "A soma das durações deve ser no máximo 15 segundos.",
      "items": {
        "$ref": "#/components/schemas/CreativeVideoShotInput"
      },
      "maxItems": 5,
      "minItems": 1,
      "type": "array"
    },
    "prompt": {
      "minLength": 1,
      "type": "string"
    },
    "quality": {
      "enum": [
        "360p",
        "480p",
        "720p",
        "768p",
        "1080p",
        "4K",
        "standard"
      ],
      "type": "string"
    },
    "referenceAudioUrls": {
      "items": {
        "$ref": "#/components/schemas/HttpsMediaUrl"
      },
      "maxItems": 3,
      "type": "array"
    },
    "referenceFileIds": {
      "items": {
        "minLength": 1,
        "type": "string"
      },
      "maxItems": 4,
      "type": "array",
      "uniqueItems": true
    },
    "referenceImages": {
      "items": {
        "$ref": "#/components/schemas/HttpsMediaUrl"
      },
      "maxItems": 4,
      "type": "array"
    },
    "referenceVideoUrls": {
      "items": {
        "$ref": "#/components/schemas/HttpsMediaUrl"
      },
      "maxItems": 3,
      "type": "array"
    },
    "videoModelOptions": {
      "additionalProperties": true,
      "properties": {
        "generateAudio": {
          "type": "boolean"
        },
        "sound": {
          "type": "boolean"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "model"
  ],
  "type": "object"
}

Respostas

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

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 com áudio nativo (Google); `360p` econômico ou `720p`; text-to-video ou 1–3 fotos de referência	`text_to_video`, `ref_images`	`360p`, `720p`	`9:16`, `16:9`	3–10s (default 5)
`h3-max`	Vídeo com áudio a partir de texto ou frames	`text_to_video`, `ref_images`, `start_end`	`480p`, `768p`, `1080p`	`21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`	5–15s
`seedance-2.5`	Vídeos de até 30s com referências multimodais	iguais ao Seedance 2	`480p`, `720p`, `1080p`	iguais ao Seedance 2	4–30s
`kling-avatar-2`	Foto falando com o áudio fornecido	`audio_to_video`	`standard`	`adaptive` (segue a imagem)	duração do áudio, 2–60s

Campos do body

Campo	Tipo	Obrigatório?	Observação
`model`	string	sim	Um dos modelos da tabela acima
`creativeDetailMode`	string	não	Modo de geração; default por modelo (ver cada seção)
`prompt`	string	condicional	Obrigatório; opcional em `multi_shot`, `audio_to_video` e `start_end` (exceto H3 Max e Seedance 2.5)
`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 e Kling Avatar não aceitam
`modeVariant`	string	não	Kling 3.0: `standard` (default), `pro`, `4k`; Avatar aceita somente `standard`
`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. Avatar: exatamente 1 WAV/MP3 de 2–60s
`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 360p ou 720p com áudio nativo, de 3 a 10 segundos. Provedor principal Google AI Studio, com fallback Segmind — o fallback atende apenas 720p, então uma geração em 360p não é reenviada por ele.

Proporções: 9:16 (default), 16:9.
Resoluções (quality): 360p, 720p (default).
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.

H3 Max — `h3-max`

Aceita texto, uma imagem inicial (ref_images) ou dois frames (start_end). O prompt é obrigatório em todos os modos. A duração aceita inteiros de 5 a 15 segundos; use quality: "768p" para a resolução intermediária. Em geração com imagem, o enquadramento é determinado pela imagem inicial.

JSON

{
  "model": "h3-max",
  "creativeDetailMode": "ref_images",
  "prompt": "A personagem apresenta o produto olhando para a câmera.",
  "referenceImages": ["https://example.com/personagem.png"],
  "quality": "768p",
  "duration": 10,
  "videoModelOptions": { "generateAudio": true }
}

Seedance 2.5 — `seedance-2.5`

Usa os mesmos campos e modos do Seedance 2, com duração de 4 a 30 segundos. O prompt é obrigatório em todos os modos, inclusive start_end. No modo reference_multi, envie os vídeos e áudios em referenceVideoUrls e referenceAudioUrls. Quando há vídeo de referência, sua duração participa da cobrança; o servidor mede essa duração antes da geração e da cotação. Para cotar, envie os mesmos referenceVideoUrls e creativeDetailMode em parameters; referenceVideoDurations informado pelo cliente é ignorado para este modelo.

JSON

{
  "model": "seedance-2.5",
  "creativeDetailMode": "text_to_video",
  "prompt": "Uma personagem apresenta um produto em um take contínuo.",
  "quality": "720p",
  "duration": 30,
  "videoModelOptions": { "generateAudio": true }
}

Kling Avatar 2 — `kling-avatar-2`

O modo audio_to_video é o padrão. Envie exatamente uma imagem de referência (ou um referenceFileIds) e exatamente um áudio WAV ou MP3 acessível por HTTPS, com 2 a 60 segundos. prompt é opcional. A versão disponível é Standard: quality: "standard", aspectRatio: "adaptive"; o formato acompanha a imagem.

Não envie duration: o servidor detecta a duração do áudio e arredonda para cima para calcular os créditos. Se o áudio não puder ser medido, a geração é recusada. Para cotar com operation: "video.generate", envie o mesmo model e referenceAudioUrls em parameters; a cotação também mede o áudio e ignora uma duração informada pelo cliente. O chat não executa este modelo; use o Workflow ou este endpoint.

JSON

{
  "model": "kling-avatar-2",
  "referenceImages": ["https://example.com/personagem.png"],
  "referenceAudioUrls": ["https://example.com/fala.mp3"]
}

Contrato OpenAPI

Parâmetros

Schema do request

Respostas

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

H3 Max — h3-max

Seedance 2.5 — seedance-2.5

Kling Avatar 2 — kling-avatar-2

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`

H3 Max — `h3-max`

Seedance 2.5 — `seedance-2.5`

Kling Avatar 2 — `kling-avatar-2`