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 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.
📘 Documentação completa: API de Geração de Vídeos MiniMax H3 →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:
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/jsoncontent-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
taskcompleto; ao transmitirasync: trueoucallback_url, retorna imediatamentetask_idetrace_id - Consulta de resultados: obtenha o status e o vídeo final por meio da API de Consulta de Tarefas MiniMax H3
- Callback assíncrono: opcional, receba o resultado final da tarefa por meio de
callback_url
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
Fluxo de chamada
Quandoasync 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:
- Salve o
task_ide otrace_idna resposta imediata. - Quando nenhum callback estiver configurado, chame
/minimax/tasksaproximadamente a cada 10 segundos para consultar. - Quando
task.statusse tornarsucceeded, obtenha o vídeo emtask.content.url. - Quando o status for
failedoucancelled, interrompa a consulta e leiatask.error.
Parâmetros de solicitação de nível superior
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.
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:
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
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.
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 |
|---|---|
 |  |
content organization method:
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 |
|---|---|
 |  |
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 |
|---|---|---|
 |  |  |
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”."async": true for adicionado à solicitação, a interface retorna imediatamente:
Vídeo a partir de imagem do primeiro quadro
Marque a imagem comofirst_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.
Vídeo de quadro final e de quadro inicial e final
Fornecer apenaslast_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.
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.Notificação de callback
Enviarcallback_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
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.