> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API de Geração de Vídeo
> A AiHubMix oferece uma API unificada de geração de vídeo, compatível com o formato da interface OpenAI Sora, com suporte de back-end para modelos de diversos fornecedores
## Início Rápido
A geração de vídeo é uma operação assíncrona, e todo o fluxo é dividido em três etapas:
```text theme={null}
1. Enviar tarefa → obter video_id
2. Consultar status → aguardar status mudar para completed
3. Baixar vídeo → obter o arquivo MP4
```
**Exemplo mais simples**
```shellscript theme={null}
# Etapa 1: Enviar a tarefa de geração de vídeo
curl -X POST https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.6-t2v",
"prompt": "A cat playing jazz on a piano, warm lighting, cinematic shot",
"seconds": "5",
"size": "1280x720"
}'
# Exemplo de resposta:
# {
# "id": "eyJtb2RlbCI6IndhbjI...",
# "object": "video",
# "status": "in_progress",
# "model": "wan2.6-t2v",
# "duration": 5,
# "width": 1280,
# "height": 720,
# ...
# }
# Etapa 2: Consultar o status (consulte a cada 15 segundos, até que status seja completed)
curl https://aihubmix.com/v1/videos/{video_id} \
-H "Authorization: Bearer $AIHUBMIX_API_KEY"
# Etapa 3: Baixar o vídeo
curl https://aihubmix.com/v1/videos/{video_id}/content \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
--output video.mp4
```
## Visão Geral das Interfaces
| Interface | Método | Caminho | Descrição |
| :--------------- | :----- | :------------------------------ | :------------------------------------- |
| Criar vídeo | POST | `/v1/videos` | Enviar tarefa de geração de vídeo |
| Consultar status | GET | `/v1/videos/{video_id}` | Consultar status e progresso da tarefa |
| Baixar vídeo | GET | `/v1/videos/{video_id}/content` | Baixar o vídeo MP4 gerado |
| Excluir tarefa | DELETE | `/v1/videos/{video_id}` | Excluir a tarefa de vídeo |
Base URL: `https://aihubmix.com`
Método de autenticação: Bearer Token
```shellscript theme={null}
Authorization: Bearer $AIHUBMIX_API_KEY
```
## Modelos Suportados
### Texto para Vídeo (Text-to-Video)
| Fornecedor | Nome do modelo | Características |
| ---------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| OpenAI | `sora-2` | Geração de vídeo padrão, com sincronização de áudio e imagem |
| OpenAI | `sora-2-pro` | Versão de alta qualidade, com imagens mais refinadas e estáveis |
| Google | `veo-3.1-generate-preview` | Veo 3.1 mais recente, áudio nativo, suporte a 4K |
| Google | `veo-3.1-fast-generate-preview` | Versão rápida do Veo 3.1, geração mais veloz |
| Google | `veo-3.0-generate-preview` | Veo 3.0, vídeo de alta fidelidade |
| Google | `veo-2.0-generate-001` | Veo 2.0, versão estável |
| Alibaba | `wan2.6-t2v` | Tongyi Wanxiang versão mais recente, sincronização de áudio e imagem |
| Alibaba | `wan2.5-t2v-preview` | Tongyi Wanxiang 2.5, otimizado para chinês |
| Alibaba | `wan2.2-t2v-plus` | Tongyi Wanxiang 2.2 |
| ByteDance | `jimeng-3.0-pro` | Jimeng 3.0 Pro, alta definição 1080P |
| ByteDance | `jimeng-3.0-1080p` | Jimeng 3.0 1080P |
| ByteDance | `doubao-seedance-2-0-260128` | Modelo de criação de vídeo multimodal de nível profissional Seedance 2.0 |
| ByteDance | `doubao-seedance-2-0-fast-260128` | Versão rápida do Seedance 2.0 |
| Kuaishou | `kling-v3`、`kling-v2-6`、`kling-v2-5-turbo`、`kling-v2-1` | Kling texto/imagem para vídeo, a nova versão suporta de 3 a 15 segundos |
| Kuaishou | `kling-v3-omni`、`kling-video-o1` | Kling OmniVideo multimodal, suporta vídeo de referência, áudio nativo e múltiplos planos |
### Imagem para Vídeo (Image-to-Video)
| Fornecedor | Nome do modelo | Características |
| ---------- | --------------------------------- | --------------------------------------------------------------------------------------- |
| Alibaba | `wan2.6-i2v` | Tongyi Wanxiang versão mais recente, imagem para vídeo |
| Alibaba | `wan2.5-i2v-preview` | Tongyi Wanxiang 2.5, imagem para vídeo |
| Alibaba | `wan2.2-i2v-plus` | Tongyi Wanxiang 2.2, imagem para vídeo |
| ByteDance | `doubao-seedance-2-0-260128` | Entrada de referência multimodal, suporta imagem/vídeo/áudio |
| ByteDance | `doubao-seedance-2-0-fast-260128` | Versão rápida do Seedance 2.0 |
| Kuaishou | `kling-v1-6` etc. | Kling imagem para vídeo, suporta quadro final e referência de múltiplas imagens (até 4) |
A geração de imagem para vídeo requer o envio da imagem de referência pelo parâmetro `input_reference` (Tongyi Wanxiang da Alibaba); o Doubao Seedance envia pelo array `extra_body.content`, com suporte a vários tipos de referência: imagem, vídeo e áudio; o Kling usa `image` / `image_tail` / `image_list` para enviar imagens, veja detalhes na seção [Kling](#kling) abaixo.
## Detalhes da API
### Cabeçalhos da requisição
```shellscript theme={null}
Authorization: Bearer $AIHUBMIX_API_KEY
Content-Type: application/json
```
### Criar tarefa de geração de vídeo
```shellscript theme={null}
POST /v1/videos
```
#### **Corpo da requisição**
| Parâmetro | Tipo | Obrigatório | Descrição |
| :---------------- | :------------ | :---------- | :------------------------------------------------------------------------------------------------------- |
| `model` | string | Sim | Nome do modelo, como `wan2.6-t2v`、`sora-2` |
| `prompt` | string | Sim | Texto de descrição do vídeo |
| `seconds` | string | Não | Duração do vídeo (segundos), sempre como tipo string, como `"5"`、`"8"` (veja os detalhes de cada modelo) |
| `size` | string | Não | Resolução, no formato `larguraxaltura`, como `1920x1080` (os valores suportados variam por modelo) |
| `input_reference` | string/object | Não | Imagem de referência (imagem para vídeo), suporta URL ou base64 |
> O formato de resposta varia ligeiramente entre os modelos, mas todos incluem os campos `id` (video\_id) e `status`. Basta usar `status` para avaliar o progresso da tarefa.
#### Exemplo de resposta (**Tongyi Wanxiang/Veo/Jimeng**)
```json theme={null}
{
"id": "eyJtb2RlbCI6IndhbjI...",
"object": "video",
"created": 1772460274,
"model": "wan2.6-t2v",
"status": "in_progress",
"prompt": "A cat watching the rain on a windowsill",
"duration": 5,
"width": 1920,
"height": 1080,
"url": null,
"error": null
}
```
**Exemplo de resposta (Sora)**
```json theme={null}
{
"id": "eyJtb2RlbCI6InNvcmEtMi...",
"object": "video",
"created_at": 1772451930,
"status": "queued",
"model": "sora-2",
"progress": 0,
"prompt": "A cinematic drone shot over mountains",
"seconds": "8",
"size": "1280x720"
}
```
#### Descrição dos valores de status comuns
| Status | Descrição |
| :------------ | :------------------------------------ |
| `queued` | Na fila (exclusivo do Sora) |
| `in_progress` | Em geração |
| `completed` | Geração concluída, pronto para baixar |
| `failed` | Falha na geração |
### Consultar status do vídeo
```shellscript theme={null}
GET /v1/videos/{video_id}
```
Consulte esta interface para verificar se a tarefa foi concluída. Recomenda-se consultar a cada **15 segundos**.
#### **Exemplo de resposta (geração concluída - Tongyi Wanxiang)**
```json theme={null}
{
"id": "eyJtb2RlbCI6IndhbjI...",
"object": "video",
"status": "completed",
"model": "wan2.5-t2v-preview",
"duration": 5,
"width": 1920,
"height": 1080,
"url": "https://aihubmix.com/v1/videos/eyJtb2RlbCI6IndhbjI.../content",
"error": null
}
```
#### **Exemplo de resposta (geração concluída - Sora)**
```json theme={null}
{
"id": "eyJtb2RlbCI6InNvcmEtMi...",
"object": "video",
"created_at": 1772451930,
"status": "completed",
"completed_at": 1772452114,
"expires_at": 1772538330,
"model": "sora-2",
"progress": 100,
"prompt": "A cinematic drone shot over mountains",
"seconds": "8",
"size": "1280x720"
}
```
> Todos os modelos usam `status == "completed"` para avaliar o estado de conclusão e, em seguida, chamam a interface `/content` para baixar.
### Baixar o conteúdo do vídeo
```shellscript theme={null}
GET /v1/videos/{video_id}/content
```
Quando o status for `completed`, chame esta interface para baixar o arquivo de vídeo MP4.
**Resposta**: retorna diretamente o stream binário do vídeo (`Content-Type: video/mp4`).
```shellscript theme={null}
curl https://aihubmix.com/v1/videos/{video_id}/content \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
--output my_video.mp4
```
> **Atenção**: o link de download do vídeo normalmente tem validade de 24 horas, baixe e salve o quanto antes.
### Excluir tarefa de vídeo
Esta interface é usada para excluir tarefas de vídeo já criadas.
```shellscript theme={null}
DELETE /v1/videos/{video_id}
```
## Detalhes dos Parâmetros de Cada Modelo
### **OpenAI Sora**
| Parâmetro | Valores suportados |
| ----------------- | ------------------------------------------------------ |
| Modelo | `sora-2`、`sora-2-pro` |
| Duração (seconds) | `"4"` (padrão)、`"8"`、`"12"` |
| Resolução (size) | `720x1280` (padrão)、`1280x720`、`1024x1792`、`1792x1024` |
| Imagem para vídeo | Suportado, envie a imagem por `input_reference` |
> Dica: o parâmetro `seconds` de todos os modelos é sempre passado como tipo string (como `"8"`).
**Exemplo**
```shellscript Sora theme={null}
curl -X POST https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "sora-2",
"prompt": "A cinematic drone shot soaring over a misty mountain range at sunrise, golden light filtering through the clouds",
"seconds": "8",
"size": "1280x720"
}'
```
```shellscript Sora Pro vídeo vertical theme={null}
curl -X POST https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "sora-2-pro",
"prompt": "A person walking through a neon-lit city street at night, rain reflecting on the pavement, cinematic lighting",
"seconds": "12",
"size": "720x1280"
}'
```
### Google Veo
| Parâmetro | Valores suportados |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Modelo | `veo-3.1-generate-preview` (recomendado)、`veo-3.1-fast-generate-preview` (rápido)、`veo-3.0-generate-preview`、`veo-2.0-generate-001` |
| Duração (seconds) | Veo 3/3.1: `"4"`、`"6"`、`"8"`; Veo 2: `"5"`\~`"8"` (padrão `"8"`) |
| Resolução (size) | `720p` (padrão)、`1080p`、`4k` (4K apenas Veo 3+), ou formato de pixels como `1280x720`、`1920x1080` |
| Proporção | 16:9 (padrão)、9:16 |
| Imagem para vídeo (Veo 3.1) | **Quadro inicial**: `first_frame` (ou o campo compatível `input_reference`); **Quadro final**: `last_frame`; **Imagens de referência**: `reference_images` (array, até 3). As imagens aceitam uma URL pública, um data URL base64 ou um objeto `{"mime_type": "...", "data": "..."}`. **Duração**: quadro inicial / quadro inicial e final suportam `"4"`/`"6"`/`"8"`; ao usar imagens de referência, o Google fixa a saída em 8 segundos |
**Exemplo**
```shellscript Veo 3.1 theme={null}
curl -X POST https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "veo-3.1-generate-preview",
"prompt": "A tranquil Japanese garden, cherry blossom petals slowly drifting down, koi swimming in the pond, with the melodious sound of wind chimes in the background",
"seconds": "8",
"size": "1280x720"
}'
```
```shellscript Veo 3.1 Fast theme={null}
curl -X POST https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "veo-3.1-fast-generate-preview",
"prompt": "Ocean waves crashing on rocky cliffs at sunset, seagulls flying overhead",
"seconds": "8",
"size": "1280x720"
}'
```
```shellscript Primeiro e Último Quadro theme={null}
curl -X POST https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "veo-3.1-generate-preview",
"prompt": "The camera slowly pushes in from a valley at dawn, transitioning naturally into sunset",
"seconds": "8",
"size": "1280x720",
"first_frame": "https://example.com/first.jpg",
"last_frame": "https://example.com/last.jpg"
}'
```
```shellscript Imagens de Referência (até 3) theme={null}
curl -X POST https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "veo-3.1-generate-preview",
"prompt": "The character from the reference images walks through a forest, cinematic shot",
"seconds": "8",
"size": "1280x720",
"reference_images": [
"https://example.com/ref1.jpg",
"https://example.com/ref2.jpg"
]
}'
```
**Notas sobre os campos de imagem**:
* Precedência do quadro inicial: `first_frame` > `input_reference` (quadro único compatível com OpenAI).
* Cada elemento de `first_frame` / `last_frame` / `reference_images` aceita: uma URL pública, um data URL base64 (`data:image/png;base64,...`) ou um objeto `{"mime_type":"image/png","data":""}`.
* Os aliases no estilo OpenRouter `frame_images` (elementos com `frame_type: first_frame | last_frame`) e `input_references` também são aceitos.
* Até 3 imagens de referência; exceder esse limite retorna 400.
> Dica: o Veo suporta geração de áudio nativo; você pode descrever efeitos sonoros no prompt, como "o som de pássaros cantando ao fundo" ou "uma melodia de piano".
### Tongyi Wanxiang
| Parâmetro | Valores suportados |
| --------------------------- | -------------------------------------------------------------------------------------------------- |
| Modelo de texto para vídeo | `wan2.6-t2v` (recomendado)、`wan2.5-t2v-preview`、`wan2.2-t2v-plus` |
| Modelo de imagem para vídeo | `wan2.6-i2v` (recomendado)、`wan2.5-i2v-preview`、`wan2.2-i2v-plus` |
| Duração (seconds) | Varia por modelo (veja a descrição abaixo), padrão `"5"` |
| Resolução (size) | Veja a tabela abaixo, os separadores `x` e `*` são ambos válidos (como `1920x1080` ou `1920*1080`) |
| Imagem para vídeo | Envie a URL da imagem ou base64 por `input_reference` |
**Durações suportadas por cada modelo**
| Modelo | Valores possíveis de seconds | Valor padrão |
| :------------------------------------------ | :------------------------------------- | :----------- |
| `wan2.6-t2v` / `wan2.6-i2v` | `"2"`\~`"15"` (qualquer valor inteiro) | `"5"` |
| `wan2.5-t2v-preview` / `wan2.5-i2v-preview` | `"5"` ou `"10"` | `"5"` |
| `wan2.2-t2v-plus` / `wan2.2-i2v-plus` | `"5"` (fixo) | `"5"` |
**Resoluções suportadas (largura\*altura)**
| Definição | Resoluções possíveis |
| :-------- | :------------------------------------------------------------------------- |
| 480P | `832x480`、`480x832`、`624x624` |
| 720P | `1280x720` (padrão)、`720x1280`、`960x960`、`1088x832` (4:3)、`832x1088` (3:4) |
| 1080P | `1920x1080`、`1080x1920`、`1440x1440`、`1632x1248` (4:3)、`1248x1632` (3:4) |
> **Atenção**: wan2.6 suporta apenas 720P e 1080P; wan2.5 suporta 480P, 720P e 1080P; wan2.2 suporta apenas 480P e 1080P.
**Exemplo**
```shellscript Texto para vídeo theme={null}
curl -X POST https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.6-t2v",
"prompt": "A winding stream flows through an autumn forest, golden fallen leaves drifting on the water surface, sunlight casting dappled light and shadow through the leaves",
"seconds": "5",
"size": "1920x1080"
}'
```
```shellscript Imagem para vídeo theme={null}
curl -X POST https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "wan2.6-i2v",
"prompt": "The character in the frame slowly turns their head and smiles, the camera slowly pushes in",
"seconds": "5",
"size": "1280x720",
"input_reference": "https://example.com/my-image.jpg"
}'
```
> Dica: as versões wan2.5 e superiores geram, por padrão, vídeos com som (dublagem automática), e o efeito é melhor com prompts em chinês.
### Jimeng
| Parâmetro | Valores suportados |
| ----------------- | ---------------------------------------------------------------- |
| Modelo | `jimeng-3.0-pro` (recomendado)、`jimeng-3.0-1080p` |
| Duração (seconds) | `"5"` ou `"10"` (padrão `"5"`) |
| Resolução (size) | Suporta formato de proporção ou formato de pixels |
| Imagem para vídeo | Suportado, envie a URL da imagem ou base64 por `input_reference` |
**Proporções suportadas e resoluções correspondentes**
| Proporção (size) | Resolução real |
| :-------------------- | :------------- |
| `16:9` ou `1920x1080` | 1920×1088 |
| `9:16` ou `1080x1920` | 1088×1920 |
| `4:3` ou `1664x1248` | 1664×1248 |
| `3:4` ou `1248x1664` | 1248×1664 |
| `1:1` ou `1440x1440` | 1440×1440 |
| `21:9` ou `2176x928` | 2176×928 |
**Exemplo**
```shellscript Jimeng theme={null}
curl -X POST https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "jimeng-3.0-pro",
"prompt": "A young woman in Hanfu dances gracefully amid a bamboo forest, her long dress flowing in the wind, with a faint morning mist in the background",
"seconds": "5",
"size": "16:9"
}'
```
```Jimeng versão vertical theme={null}
curl -X POST https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "jimeng-3.0-1080p",
"prompt": "A sunset over the ocean, waves gently rolling, warm golden light",
"seconds": "5",
"size": "9:16"
}'
```
### Doubao Seedance
| Parâmetro | Valores suportados |
| ------------------------------- | ---------------------------------------------------------------------------------------------- |
| Modelo | `doubao-seedance-2-0-260128`、`doubao-seedance-2-0-fast-260128` |
| Resolução (resolution) | `"480p"`、`"720p"` (padrão) |
| Duração (duration) | Inteiro, intervalo `4`\~`15`, ou `-1` (o modelo decide automaticamente) |
| Proporção (ratio) | `"adaptive"` (padrão, adaptação automática)、`"16:9"`、`"9:16"`、`"1:1"`、`"4:3"`、`"3:4"`、`"21:9"` |
| Vídeo com som (generate\_audio) | Padrão `true`; defina como `false` para gerar vídeo sem som |
| Marca d'água (watermark) | Padrão `false` |
| Referência multimodal | Suporta imagem, vídeo e áudio |
**Tipos de referência suportados em `extra_body.content`**
| Tipo | Valor de `type` | Valor de `role` | Descrição |
| -------------------- | --------------- | ----------------- | ----------------------------------------------------- |
| Imagem de referência | `image_url` | `reference_image` | Imagem de referência de cena/estilo |
| Vídeo de referência | `video_url` | `reference_video` | Vídeo de referência de movimento de câmera/composição |
| Áudio de referência | `audio_url` | `reference_audio` | Arquivo de áudio de música de fundo |
**Exemplo**
```shellscript Seedance 2.0 / 2.0 Fast theme={null}
curl -X POST "https://aihubmix.com/v1/videos" \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "doubao-seedance-2-0-260128",
"prompt": "Use the first-person POV framing from Video 1 throughout, and use Audio 1 as the background music for the entire clip. Create a first-person fruit tea commercial featuring the Seedance brand limited-edition apple fruit tea, "Ping Ping An An."
Opening frame: Image 1. From a first-person perspective, your hand picks a dew-covered Aksu red apple, accompanied by a crisp, satisfying bite-like tapping sound.
Seconds 2–4: Fast-paced cuts. Your hand drops freshly cut apple chunks into a shaker, adds ice and tea base, then shakes vigorously. The sound of ice clinking and shaking syncs with upbeat percussion. Background voiceover: "Freshly cut, freshly shaken."
Seconds 4–6: First-person close-up of the finished drink. The layered fruit tea is poured into a clear cup. Your hand gently squeezes a creamy topping across the surface. A pink label is placed on the cup. The camera pushes in to highlight the rich texture and layering.
Seconds 6–8: First-person hand holding the drink. You raise the fruit tea from Image 2 toward the camera, as if offering it directly to the viewer. The label is clearly visible. Background voiceover: "Take a refreshing sip."
Final frame: Freeze on Image 2.
All background voiceovers should be in a female voice.",
"extra_body": {
"content": [
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"
},
"role": "reference_image"
},
{
"type": "image_url",
"image_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
},
"role": "reference_image"
},
{
"type": "video_url",
"video_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"
},
"role": "reference_video"
},
{
"type": "audio_url",
"audio_url": {
"url": "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"
},
"role": "reference_audio"
}
],
"ratio": "16:9",
"duration": 11,
"watermark": false
}
}'
```
### Kling
O Kling suporta quatro tipos de capacidades — **texto para vídeo, imagem para vídeo, vídeo a partir de referência de múltiplas imagens e OmniVideo multimodal** — todos chamados de forma unificada pela interface `/v1/videos`. O gateway roteia automaticamente para o endpoint correspondente do Kling com base em "nome do modelo + forma de entrada", sem que o chamador precise distinguir.
| Capacidade | Modelo |
| ------------------------------- | -------------------------------------------------------------------------------------------- |
| Texto / imagem | `kling-v1`、`kling-v1-5`、`kling-v1-6`、`kling-v2-1`、`kling-v2-5-turbo`、`kling-v2-6`、`kling-v3` |
| Referência de múltiplas imagens | `kling-v1-6` |
| OmniVideo multimodal | `kling-video-o1`、`kling-v3-omni` |
**Parâmetros**
| Parâmetro | Tipo | Descrição |
| ---------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model` | string | **Obrigatório**, `kling-*`, determina a capacidade e a versão |
| `prompt` | string | Prompt de texto |
| `negative_prompt` | string | Prompt negativo |
| `mode` | string | Modo de geração: `std` (720P) / `pro` (1080P) / `4k`, padrão `std` |
| `duration` / `seconds` | string | Duração (segundos), modelos antigos `5`/`10`, modelos novos `3`\~`15`, padrão `5` |
| `aspect_ratio` | string | Formato de tela: `16:9` / `9:16` / `1:1` (obrigatório no omni para texto puro e referência de vídeo; se ausente, preenchido automaticamente com `16:9`) |
| `cfg_scale` | float | Relevância do prompt `[0, 1]`, padrão `0.5` (`kling-v2.x` não suporta) |
| `image` | string | **Imagem para vídeo**: imagem única, URL da imagem ou Base64 (Base64 sem o prefixo `data:image/...;base64,`) |
| `image_tail` | string | **Imagem para vídeo**: imagem de quadro final (opcional) |
| `image_list` | array | **Referência de múltiplas imagens**: array de URLs de imagens, até 4 |
| `sound` | string | **omni**: `on`/`off`, se gera áudio nativo, padrão `off` |
| `video_list` | array | **omni**: vídeo de referência `[{ "video_url": "...", "refer_type": "feature" }]`, `refer_type` aceita `feature` (referência de vídeo) / `base` (edição de vídeo) |
Parâmetros-chave não suportados ou não mapeados geram erro explícito, sem serem descartados silenciosamente. Os demais parâmetros nativos do Kling podem ser colocados em `extra_body` para serem repassados ao upstream.
**Exemplo**
```shellscript Texto para vídeo theme={null}
curl https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v1-6",
"prompt": "An orange cat running on a sunlit grassy meadow",
"mode": "std",
"duration": "5"
}'
```
```shellscript Imagem para vídeo theme={null}
curl https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v1-6",
"image": "https://example.com/first.png",
"prompt": "The camera pulls back, the character smiles",
"mode": "std",
"duration": "5"
}'
```
```shellscript Referência de múltiplas imagens theme={null}
curl https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v1-6",
"image_list": ["https://example.com/a.png", "https://example.com/b.png"],
"prompt": "Two characters meet on the street",
"mode": "std",
"duration": "5"
}'
```
```shellscript OmniVideo vídeo de referência theme={null}
curl https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3-omni",
"prompt": "Generate the next shot based on the reference video",
"video_list": [{ "video_url": "https://example.com/in.mp4", "refer_type": "feature" }],
"mode": "std",
"duration": "5"
}'
```
```shellscript OmniVideo áudio nativo theme={null}
curl https://aihubmix.com/v1/videos \
-H "Authorization: Bearer $AIHUBMIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3-omni",
"prompt": "A man smiles and says hello",
"sound": "on",
"aspect_ratio": "16:9",
"duration": "5"
}'
```
**Observações**
* **Três etapas assíncronas**: enviar para obter `video_id` → consultar `GET /v1/videos/{video_id}` até `status` ser `completed` → `GET /v1/videos/{video_id}/content` para baixar o MP4. Valores de status: `in_progress` / `completed` / `failed`.
* A produção do vídeo costuma levar de 1 a 3 minutos; a URL do vídeo resultante é **removida após 30 dias**, transfira-o o quanto antes.
* **Excluir tarefa**: o Kling não possui interface de exclusão; `DELETE /v1/videos/{video_id}` retorna `501 not_supported`.
* **Cobrança**: cobrado por modelo × `mode` × duração × capacidade (com ou sem vídeo de referência / com som); **falhas na geração não são cobradas**, e consultas e downloads não são tarifados.
## **Exemplos Completos de Chamada**
```python Tongyi Wanxiang theme={null}
import requests
import time
API_KEY = "AIHUBMIX_API_KEY"
BASE_URL = "https://aihubmix.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
# Etapa 1: Criar a tarefa de geração de vídeo
response = requests.post(
f"{BASE_URL}/v1/videos",
headers=HEADERS,
json={
"model": "wan2.6-t2v",
"prompt": "A desert under a starry sky, a meteor streaking across the night sky, the glow of a distant campfire flickering in the breeze",
"seconds": "5",
"size": "1920x1080"
}
)
result = response.json()
video_id = result["id"]
print(f"Tarefa criada, video_id: {video_id}")
# Etapa 2: Consultar o status
while True:
status_response = requests.get(
f"{BASE_URL}/v1/videos/{video_id}",
headers=HEADERS
)
status_data = status_response.json()
current_status = status_data["status"]
print(f"Status atual: {current_status}")
if current_status == "completed":
print("Geração de vídeo concluída!")
break
elif current_status == "failed":
error_msg = status_data.get("error", {})
if isinstance(error_msg, dict):
error_msg = error_msg.get("message", "Erro desconhecido")
print(f"Falha na geração: {error_msg}")
break
time.sleep(15) # Consulta a cada 15 segundos
# Etapa 3: Baixar o vídeo
video_response = requests.get(
f"{BASE_URL}/v1/videos/{video_id}/content",
headers=HEADERS
)
with open("output.mp4", "wb") as f:
f.write(video_response.content)
print(f"Vídeo salvo como output.mp4 ({len(video_response.content) / 1024 / 1024:.1f} MB)")
```
```python Sora theme={null}
import requests
import time
API_KEY = "AIHUBMIX_API_KEY"
BASE_URL = "https://aihubmix.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
# Criar a tarefa de geração de vídeo
response = requests.post(
f"{BASE_URL}/v1/videos",
headers=HEADERS,
json={
"model": "sora-2",
"prompt": "A cinematic shot of a futuristic city at sunset, flying cars in the background",
"seconds": "8", # Opções "4"/"8"/"12"
"size": "1280x720" # Suporta 1280x720, 720x1280, 1024x1792, 1792x1024
}
)
result = response.json()
video_id = result["id"]
print(f"Tarefa criada, video_id: {video_id}")
# Consulta de status do Sora (pode passar por queued -> in_progress -> completed)
while True:
status_response = requests.get(
f"{BASE_URL}/v1/videos/{video_id}",
headers=HEADERS
)
status_data = status_response.json()
current_status = status_data["status"]
progress = status_data.get("progress", "")
print(f"Status: {current_status}, Progresso: {progress}%")
if current_status == "completed":
print("Geração de vídeo concluída!")
break
elif current_status == "failed":
print(f"Falha na geração: {status_data.get('error')}")
break
time.sleep(15)
# Baixar o vídeo
video_response = requests.get(
f"{BASE_URL}/v1/videos/{video_id}/content",
headers=HEADERS
)
with open("sora_output.mp4", "wb") as f:
f.write(video_response.content)
print("Vídeo salvo como sora_output.mp4")
```
```javascript Node.js theme={null}
const API_KEY = "your_aihubmix_api_key";
const BASE_URL = "https://aihubmix.com";
async function generateVideo() {
// Etapa 1: Criar a tarefa (exemplo com Veo 3.1)
const createResponse = await fetch(`${BASE_URL}/v1/videos`, {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "veo-3.1-generate-preview",
prompt: "A desert under a starry sky, a meteor streaking across the night sky",
seconds: "8",
size: "1280x720"
})
});
const { id: videoId } = await createResponse.json();
console.log(`Tarefa criada: ${videoId}`);
// Etapa 2: Consultar o status
let status = "in_progress";
while (status !== "completed" && status !== "failed") {
await new Promise(resolve => setTimeout(resolve, 15000));
const statusResponse = await fetch(`${BASE_URL}/v1/videos/${videoId}`, {
headers: { "Authorization": `Bearer ${API_KEY}` }
});
const result = await statusResponse.json();
status = result.status;
console.log(`Status atual: ${status}`);
}
if (status === "completed") {
// Etapa 3: Baixar o vídeo
const videoResponse = await fetch(`${BASE_URL}/v1/videos/${videoId}/content`, {
headers: { "Authorization": `Bearer ${API_KEY}` }
});
const fs = require("fs");
const buffer = Buffer.from(await videoResponse.arrayBuffer());
fs.writeFileSync("output.mp4", buffer);
console.log("Vídeo salvo como output.mp4");
}
}
generateVideo();
```
## **FAQ**
### **Quanto tempo leva a geração de vídeo?**
A geração de vídeo normalmente leva de 1 a 5 minutos, e o tempo exato depende do modelo, da resolução e da duração. Recomenda-se definir um intervalo de consulta de 15 segundos.
### Como usar o parâmetro `input_reference`?
`input_reference` é usado em cenários de imagem para vídeo e suporta três formas de envio:
```json theme={null}
// Forma 1: Enviar diretamente a URL da imagem
"input_reference": "https://example.com/image.jpg"
// Forma 2: Enviar a imagem codificada em base64 (formato de objeto)
"input_reference": {
"mime_type": "image/jpeg",
"data": ""
}
// Forma 3: Enviar uma data URL
"input_reference": "data:image/jpeg;base64,"
```
### **Qual é a validade do link de download do vídeo?**
O link de download do vídeo gerado normalmente tem validade de **24 horas**, baixe e salve o quanto antes.
### **Qual é a diferença do parâmetro `seconds` entre os modelos?**
| Modelo | Valores possíveis | Valor padrão |
| -------------------------------------------------------------- | ------------------------------------ | ------------ |
| Sora (`sora-2` / `sora-2-pro`) | `"4"`, `"8"`, `"12"` | `"4"` |
| Veo 3/3.1 (`veo-3.1-generate-preview` etc.) | `"4"`, `"6"`, `"8"` | `"8"` |
| Veo 2 (`veo-2.0-generate-001`) | `"5"`\~`"8"` | `"8"` |
| Tongyi Wanxiang `wan2.6` | `"2"`\~`"15"` | `"5"` |
| Tongyi Wanxiang `wan2.5` | `"5"`, `"10"` | `"5"` |
| Tongyi Wanxiang `wan2.2` | `"5"` (fixo) | `"5"` |
| Jimeng (`jimeng-3.0-pro` etc.) | `"5"`, `"10"` | `"5"` |
| Doubao Seedance (`doubao-seedance-2-0-*`) | inteiro `duration` `4`\~`15` ou `-1` | `5` |
| Kling nova versão (`kling-v2-x` / `kling-v3` etc.) | `"3"`\~`"15"` | `"5"` |
| Kling versão antiga (`kling-v1` / `kling-v1-5` / `kling-v1-6`) | `"5"`, `"10"` | `"5"` |
\> **Dica**: o parâmetro `seconds` de todos os modelos é sempre passado como tipo string (como `"8"`), e a API o processa automaticamente.
### Qual é a diferença no formato do parâmetro `size` entre os modelos?
| Modelo | Valores de size suportados |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Sora | `1280x720`、`720x1280`、`1024x1792`、`1792x1024` |
| Veo | formato de pixels (`1280x720` etc.) ou rótulo de resolução (`720p`、`1080p`、`4k`) |
| Tongyi Wanxiang | formato de pixels, `x` e `*` ambos válidos (como `1920x1080` ou `1920*1080`) |
| Jimeng | formato de proporção (`16:9`、`9:16` etc.) ou formato de pixels |
| Doubao Seedance | formato de proporção (`"adaptive"`、`"16:9"`、`"9:16"` etc.) |
| Kling | não usa `size`, usa `mode` (`std`/`pro`/`4k` controla a definição) + `aspect_ratio` (`16:9`/`9:16`/`1:1` controla o formato de tela) |
### Qual é a diferença entre `seconds` e `duration`?
Os dois têm o mesmo significado, ambos representam a duração do vídeo. A API suporta os dois nomes de parâmetro (exceto o Sora, que aceita apenas `seconds`). Recomenda-se usar sempre `seconds`.
### Como escrever um prompt melhor?
* **Descreva cenas concretas**: inclua o sujeito, a ação, o ambiente, a iluminação e a atmosfera
* **Especifique a linguagem de câmera**: como "close-up", "tomada aérea", "câmera avançando", "câmera lenta"
* **Descreva o estilo**: como "cinematográfico", "estilo documentário", "estilo de animação"
* **Modelos focados em chinês têm melhor resultado com prompts em chinês**: o Tongyi Wanxiang é otimizado para chinês
* **O Veo suporta descrição de áudio**: você pode descrever sons no prompt, como "canto de pássaros" ou "melodia de piano"
### O que fazer quando a tarefa falha?
Quando o `status` for `failed`, o campo `error` na resposta conterá a informação do erro:
```json theme={null}
{
"status": "failed",
"error": {
"message": "Video generation failed due to content policy violation",
"type": "video_generation_error"
}
}
```
## As causas comuns de falha incluem: violação de conteúdo, prompt longo demais, formato de imagem não suportado, entre outros. Ajuste de acordo com a informação do erro e tente novamente.
Última atualização: 2026-06-01