> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Guia de Integração da API de Geração de Vídeos MiniMax H3
> Minimax API guide - Ace Data Cloud
Este artigo apresenta a integração e o uso da API de geração de vídeos MiniMax H3. Esta interface oferece suporte a texto para vídeo, controle de primeiro e último quadro e vídeo gerado com referência multimodal, usando a estrutura unificada de `content` multimodal V2 para criar tarefas.
## Processo de solicitação
Para usar a API de geração de vídeos MiniMax H3, primeiro acesse o [Console Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obter seu API Token e guarde-o para uso posterior.
Se você ainda não estiver conectado ou registrado, será redirecionado automaticamente para a página de login, onde será convidado a se registrar e fazer login; após concluir, retornará automaticamente para a página atual.
**Um único API Token permite chamar todos os serviços da plataforma, sem necessidade de solicitar um para cada serviço separadamente.** A primeira solicitação oferece créditos gratuitos para experimentação; quando os créditos forem insuficientes, você poderá recarregar o saldo geral no [console](https://platform.acedata.cloud/console/coin).
> 📘 Documentação completa: [API de Geração de Vídeos MiniMax H3 →](https://platform.acedata.cloud/documents/minimax-videos-integration)
Recomenda-se salvar o Token como variável de ambiente, sem incluí-lo no código-fonte ou enviá-lo ao repositório de versões:
```bash theme={null}
export ACEDATACLOUD_API_KEY="YOUR_API_KEY"
```
## Visão geral da interface
* **Base URL**: `https://api.acedata.cloud`
* **Endpoint**: `POST /minimax/videos`
* **Método de autenticação**: incluir `authorization: Bearer {token}` no HTTP Header
* **Cabeçalhos de solicitação**:
* `accept: application/json`
* `content-type: application/json`
* **Modelo (`model`)**: `MiniMax-H3`
* **Estrutura de entrada**: texto, imagens, vídeos e áudio são transmitidos de forma unificada por meio de `content`
* **Modo de saída**: por padrão, aguarda sincronamente a conclusão da geração e retorna o `task` completo; ao transmitir `async: true` ou `callback_url`, retorna imediatamente `task_id` e `trace_id`
* **Consulta de resultados**: obtenha o status e o vídeo final por meio da [API de Consulta de Tarefas MiniMax H3](https://platform.acedata.cloud/documents/minimax-tasks-integration)
* **Callback assíncrono**: opcional, receba o resultado final da tarefa por meio de `callback_url`
Você não precisa transmitir `action` para selecionar o modo de geração; a interface determinará automaticamente o uso com base no tipo de material e no `role` em `content`.
## Para quais cenários é adequado
| Cenário | Combinação de entrada | Usos comuns |
| - | - | - |
| Texto para vídeo | Texto | Criatividade publicitária, pré-visualização de storyboard, vídeos curtos, tomadas de atmosfera |
| Imagem de primeiro quadro para vídeo | Texto + imagem de primeiro quadro | Fazer com que imagens de produtos, pôsteres, fotos de pessoas ou ilustrações ganhem movimento naturalmente |
| Vídeo de último quadro / primeiro e último quadro | Texto + último quadro, ou texto + primeiro quadro + último quadro | Controlar abertura e encerramento, transições, mudanças de crescimento e comparação antes e depois |
| Vídeo gerado com referência multimodal | Texto + imagens / vídeos / áudios de referência | Manter a consistência de personagens e produtos, reproduzir movimentos, movimentos de câmera, timbre ou ritmo de edição |
## Fluxo de chamada
Quando `async` não é transmitido por padrão, `/minimax/videos` aguardará a conclusão da geração e retornará diretamente o `task` completo. Quando precisar liberar a conexão imediatamente, transmita `async: true` ou `callback_url`:
1. Salve o `task_id` e o `trace_id` na resposta imediata.
2. Quando nenhum callback estiver configurado, chame `/minimax/tasks` aproximadamente a cada 10 segundos para consultar.
3. Quando `task.status` se tornar `succeeded`, obtenha o vídeo em `task.content.url`.
4. Quando o status for `failed` ou `cancelled`, interrompa a consulta e leia `task.error`.
## Parâmetros de solicitação de nível superior
| Parâmetro | Tipo | Obrigatório | Valor padrão | Descrição |
| - | - | - | - | - |
| `model` | string | Sim | - | Fixo como `MiniMax-H3` |
| `content` | object\[] | Sim | - | Array de conteúdo multimodal, deve conter um item `text` não vazio |
| `resolution` | string | Sim | - | `768P` ou `2K` |
| `duration` | integer | Sim | - | Duração gerada, inteiro de 4 a 15 segundos |
| `ratio` | string | Obrigatório condicionalmente | `adaptive` | `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` |
| `async` | boolean | Não | `false` | Quando for `true`, retorna imediatamente o identificador da tarefa; obtenha o resultado por meio da interface de tarefas |
| `callback_url` | string | Não | - | URL de callback pública que recebe o resultado final da tarefa; ao fornecê-la, o modo assíncrono é ativado automaticamente |
As regras de `ratio` dependem do fluxo de trabalho:
* **Texto para vídeo**: obrigatório e não pode ser `adaptive`.
* **Vídeo de primeiro quadro, último quadro ou primeiro e último quadro**: a proporção é determinada pela imagem de entrada; recomenda-se omitir ou transmitir `adaptive`.
* **Vídeo gerado com referência multimodal**: pode ser omitido, com padrão `adaptive`; também é possível especificar explicitamente uma proporção fixa.
A interface não aceita campos legados ou de compatibilidade, como `prompt`, `image_urls`, `audio_urls`, `messages` e `first_frame_image`. Ao receber erros relacionados a esses parâmetros, remova os campos antigos e migre para `content`; por exemplo, altere `"prompt": "一只猫挥手"` para `"content": [{"type": "text", "text": "一只猫挥手"}]`. Não envie os formatos novo e antigo simultaneamente.
## Parâmetros de itens de conteúdo `content`
Cada item de conteúdo deve ter `type`; os demais campos são determinados pelo tipo:
| `type` | Campo de dados | `role` | Descrição |
| - | - | - | - |
| `text` | `text` | não transmitir | Cada solicitação deve incluir um item de texto não vazio, com no máximo 7000 caracteres |
| `image_url` | `image_url.url` | `first_frame` | Imagem de primeiro quadro; quando houver apenas uma imagem e `role` for omitido, ela também será tratada como primeiro quadro |
| `image_url` | `image_url.url` | `last_frame` | Imagem de último quadro; pode ser usada sozinha ou combinada com `first_frame` para controlar o início e o fim |
| `image_url` | `image_url.url` | `reference_image` | Referência de sujeito, personagem, produto, roupa, cenário ou estilo |
| `video_url` | `video_url.url` | `reference_video` | Referência de movimento, movimento de câmera, atuação ou estrutura de edição |
| `audio_url` | `audio_url.url` | `reference_audio` | Referência de timbre, diálogo, música ou ritmo |
Os endereços de mídia aceitam três formatos:
* URL HTTPS acessível publicamente, recomendada para arquivos grandes.
* `mm_file://{file_id}`, referenciando arquivos já enviados ou resultados existentes.
* Data URI Base64 do tipo de mídia correspondente. Base64 aumenta o tamanho em aproximadamente um terço; certifique-se de que todo o corpo da solicitação não exceda 64 MB.
## Especificações de materiais e limites de quantidade
| Material | Format | Single File Limit | Dimensions / Duration | Quantity Limit |
| - | - | - | - | - |
| Image | JPG, JPEG, PNG, WEBP, HEIC, HEIF | No more than 30 MB | Width and height both 256-5760 px; aspect ratio 0.4-2.5 | Up to 1 first frame, up to 1 last frame, up to 9 reference images |
| Video | MP4, MOV; H.264/AVC or H.265/HEVC; audio track AAC or MP3 | No more than 50 MB | Each segment 2-15 seconds, total no more than 15 seconds; width and height both 256-5760 px; aspect ratio 0.4-2.5; 23.976-60 fps | Up to 3 reference videos |
| Audio | WAV, MP3 | No more than 15 MB | Each segment 2-15 seconds, total no more than 15 seconds | Up to 3 reference audios |
Images, videos, and audios in multimodal reference scenarios total up to 12 files. First and last frame scenarios and reference material scenarios are mutually exclusive: once `reference_image`, `reference_video`, or `reference_audio` is used, `first_frame` or `last_frame` can no longer be used, and vice versa.
## Production-Level Capability Showcase
The following are not concept images or placeholder materials, but real reference inputs and actual video outputs from official production-level capability samples of MiniMax H3. The three groups of cases respectively cover brand short films, live-action narratives, and fashion e-commerce, suitable for evaluating the model's most critical capabilities in commercial production.
| Capability | Key Observations |
| - | - |
| Character and face consistency | Whether facial features, hairstyle, makeup, and character temperament remain stable after multi-shot switching |
| Facial performance | Gaze, micro-expressions, emotional tension, and natural head movement in close-ups |
| Product structure preservation | Contours, materials, wearing relationships, and mirror reflections of products such as glasses and handbags |
| Brand visual execution | Whether scene atmosphere, film grain, colors, Logo, and editing rhythm are unified |
| Cinematic narrative | Whether shot scale changes, character blocking, camera movement, rhythm, and sound can form a complete segment |
Here, “face capability” refers to character appearance consistency, facial details, and performance control in video generation, not identity recognition, face comparison, or face-swapping interfaces.
### Premium Brand Short Film: Unified Characters, Products, and Brand Assets
**Production Goal:** 16:9 premium fashion brand film. Use a desert highway and vintage car to establish a stark atmosphere, maintain the female protagonist's appearance and the structure of the black handbag, and naturally incorporate the brand Logo at the end. This case focuses on testing cross-shot character consistency, product preservation, cinematic texture, and brand closure capabilities.
| Atmosphere and Scene Reference | Character Reference |
| - | - |
| 
| 
|
| Handbag Product Reference | Brand Logo Reference |
| - | - |
| 
| 
|
[Open or download the brand short film directly](https://cdn.acedata.cloud/uploads/6845b11d-1a58-4478-afd8-29e7e117772a)
Corresponding `content` organization method:
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "15 秒、16:9 高级时装品牌片。荒漠公路旁停着复古汽车，女主从后备箱取出黑色手袋，与男主短暂对视后独自离开。保持人物、手袋与品牌视觉一致；冷峻高级，电影颗粒，剪辑利落，结尾自然呈现品牌 Logo。"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/6e65f865-f1c2-4f80-8b51-9a98d4d930b1" },
"role": "reference_image"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/88d89cc3-e6cb-42b4-ab4c-1bbbf6c9f7c8" },
"role": "reference_image"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/e91f7fff-f8e3-4da5-b882-87edbc3c9473" },
"role": "reference_image"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.acedata.cloud/uploads/b68dac43-fb14-42b5-bf8b-fd4d65506520" },
"role": "reference_image"
}
],
"resolution": "2K",
"duration": 15,
"ratio": "16:9"
}
```
### Live-Action Vertical Short Drama: Face Consistency and Emotional Performance
**Objetivo de produção:** Prévia de curta-metragem romântico sombrio de 15 segundos, 9:16. Fixe a aparência dos personagens usando as imagens de referência do protagonista masculino e da protagonista feminina, e restrinja o espaço usando a imagem de referência do castelo; use planos médios fechados e close-ups faciais para mostrar o confronto de olhares, medo, contenção e sensação de perigo. Este caso é adequado para observar a estabilidade dos traços faciais reais, microexpressões, relações de olhar e atuação contínua.
| Referência do protagonista masculino e da protagonista feminina | Referência do cenário do castelo |
| - | - |
| 
| 
|
[Abra ou baixe diretamente o curta-metragem com pessoas reais](https://cdn.acedata.cloud/uploads/0f3e9bf2-5073-46f4-9a2d-7d8d912391cf)
O prompt deve deixar claras as relações entre os personagens, as emoções e o enquadramento, em vez de apenas descrever “um diálogo entre um homem e uma mulher”:
```text theme={null}
15 秒、9:16 真人暗黑浪漫短剧预告。女主误入禁忌古堡，唤醒沉睡的吸血鬼贵族；
他危险而克制地靠近，她恐惧但不屈服。保持两位角色的五官、发型与服装一致，
以中近景和面部特写表现眼神对峙与情绪张力，暗色电影光线，节奏紧凑。
```
### Anúncio de óculos de moda: preservação dos detalhes faciais e da estrutura do produto
**Objetivo de produção:** Anúncio de óculos de moda sofisticada em 9:16. A imagem de corpo inteiro da pessoa é responsável pela silhueta e pela caminhada, a imagem de referência do rosto é responsável pelos traços faciais e pela maquiagem, e a imagem do produto é responsável pelas curvas envolventes, reflexos das lentes, hastes e contorno gatinho. Este caso também testa close-ups faciais, consistência entre várias pessoas, relação de uso e estrutura geométrica do produto.
| Referência de modelo e estilo | Referência de detalhes faciais | Referência do produto de óculos |
| - | - | - |
| 
| 
| 
|
[Abra ou baixe diretamente o anúncio de óculos de moda](https://cdn.acedata.cloud/uploads/55715089-b6bd-4ef6-a3c2-e762a672f751)
Em anúncios de produtos, o prompt deve separar e explicar claramente as responsabilidades da referência da pessoa e da referência do produto: os materiais da pessoa restringem rosto, maquiagem, silhueta e temperamento; os materiais do produto restringem contorno, material, reflexos e posição de uso. Isso é mais estável do que escrever genericamente “gere um anúncio de óculos”.
## Vídeo a partir de texto
Quando há apenas um item de texto, trata-se de vídeo a partir de texto. É adequado para gerar imagens diretamente a partir de uma ideia, roteiro ou descrição de cena. O prompt pode ser organizado na ordem “sujeito + ação + cenário + câmera + iluminação + som”.
```bash theme={null}
curl -X POST 'https://api.acedata.cloud/minimax/videos' \
-H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "15 秒电影级香水广告：清晨海岸的黑色礁石上，透明香水瓶被薄雾与海浪环绕。微距展现瓶身水珠和玻璃折射，镜头从产品特写缓慢拉升到广阔海面；银蓝色调，真实自然光，高级克制，结尾定格产品。"
}
],
"resolution": "2K",
"duration": 15,
"ratio": "16:9"
}'
```
O modo síncrono padrão retorna a tarefa completa após a geração ser concluída:
```json theme={null}
{
"task": {
"id": "f5977217-ed2c-40da-adbe-93d08235618f",
"model": "MiniMax-H3",
"status": "succeeded",
"content": { "url": "https://cdn.acedata.cloud/minimax/f5977217.mp4" },
"resolution": "2K",
"duration": 15,
"ratio": "16:9"
}
}
```
Se `"async": true` for adicionado à solicitação, a interface retorna imediatamente:
```json theme={null}
{
"task_id": "f5977217-ed2c-40da-adbe-93d08235618f",
"trace_id": "trace_7f8c2b1a"
}
```
## Vídeo a partir de imagem do primeiro quadro
Marque a imagem como `first_frame`, e o modelo começará a gerar a partir dessa imagem. É adequado para dar movimento natural a pôsteres, imagens de produtos, imagens de definição de personagens e obras fotográficas.
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "人物自然呼吸并看向窗外，衣角被微风吹动，镜头缓慢推进"
},
{
"type": "image_url",
"image_url": {
"url": "https://cdn.acedata.cloud/b1c82e4937.png"
},
"role": "first_frame"
}
],
"resolution": "2K",
"duration": 5,
"ratio": "adaptive"
}
```
## Vídeo de quadro final e de quadro inicial e final
Fornecer apenas `last_frame` permite que o modelo gere naturalmente até o quadro especificado; fornecer simultaneamente `first_frame` e `last_frame` permite controlar claramente o ponto de início e o ponto de término. Adequado para transições, mudanças de forma, processos de crescimento ou comparações de produto antes e depois.
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "A menina cresce naturalmente da infância até a juventude, a passagem do tempo é suave, e a personagem permanece sempre no centro da imagem"
},
{
"type": "image_url",
"image_url": { "url": "YOUR_FIRST_FRAME_URL" },
"role": "first_frame"
},
{
"type": "image_url",
"image_url": { "url": "YOUR_LAST_FRAME_URL" },
"role": "last_frame"
}
],
"resolution": "2K",
"duration": 5,
"ratio": "adaptive"
}
```
O tamanho e a proporção entre largura e altura do primeiro e do último quadro devem ser, tanto quanto possível, consistentes, e as diferenças na posição do sujeito, na composição e na iluminação não devem ser muito grandes, para que seja mais fácil obter uma transição natural.
## Vídeo gerado com referência multimodal
Os materiais de referência podem ser usados em combinação: imagens de referência controlam a aparência de personagens ou produtos, vídeos de referência controlam ações e movimentos de câmera, e áudios de referência controlam o timbre dos diálogos, a música ou o ritmo de edição. O prompt deve indicar claramente o que cada tipo de material deve controlar, evitando apenas enviar os materiais sem fornecer as relações entre eles.
```json theme={null}
{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "Mantenha os traços faciais, o penteado e as roupas da pessoa de referência consistentes, e conclua um curta-metragem de moda seguindo os movimentos de atuação do vídeo de referência; o ritmo da câmera segue o áudio de referência, com planos próximos destacando expressões faciais naturais"
},
{
"type": "image_url",
"image_url": { "url": "YOUR_CHARACTER_IMAGE_URL" },
"role": "reference_image"
},
{
"type": "video_url",
"video_url": { "url": "YOUR_PERFORMANCE_VIDEO_URL" },
"role": "reference_video"
},
{
"type": "audio_url",
"audio_url": { "url": "YOUR_AUDIO_URL" },
"role": "reference_audio"
}
],
"resolution": "2K",
"duration": 5,
"ratio": "adaptive"
}
```
## Notificação de callback
Enviar `callback_url` ativará automaticamente o modo assíncrono: a interface de criação retorna imediatamente `task_id` e `trace_id` e, após a conclusão da tarefa, envia o resultado final por POST para esse endereço, com uma estrutura igual à resposta de consulta da tarefa.
Os estados finais no callback são `succeeded`, `failed` ou `cancelled`. Mesmo ao usar callbacks, também é recomendável salvar o `task_id`, para realizar consultas ativas ou compensar notificações perdidas.
## Erros comuns
| Código de status HTTP | Significado | Recomendação de tratamento |
| - | - | - |
| `400` | Erro de parâmetro ou combinação de materiais inválida | Verifique os campos obrigatórios, `role`, a quantidade e o formato dos materiais |
| `401` | Token ausente ou inválido | Verifique `Authorization: Bearer ...` |
| `402` | Saldo ou cota insuficiente | Recarregue o saldo geral no console |
| `422` | Falha na verificação de segurança de conteúdo | Ajuste o prompt ou os materiais e envie novamente |
| `429` | Solicitações muito frequentes | Tente novamente após backoff exponencial; recomenda-se um intervalo de cerca de 10 segundos para a consulta de tarefas |
| `500` | Serviço temporariamente indisponível | Mantenha as informações da solicitação e tente novamente mais tarde |
`task.status: succeeded` na resposta síncrona indica que o vídeo foi gerado; a confirmação assíncrona apenas representa que a tarefa entrou na fila. A cobrança ocorre apenas quando a tarefa é concluída com sucesso; a consulta de tarefas é gratuita e não haverá cobrança repetida.
### H3 Max
`MiniMax-H3-Max` oferece suporte a 480P ou 768P e duração inteira de 5 a 15 segundos. A entrada de áudio não gera cobrança adicional, as primeiras 2 imagens são gratuitas e as imagens excedentes são cobradas individualmente; o vídeo de referência é cobrado conforme a duração real de entrada. Este modelo não oferece suporte a 2K.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.