01content: text
Texto para vídeo (t2va)
Envie um item de texto obrigatório e crie o plano completo. Para geração pura de texto, ratio é obrigatório e não pode ser adaptativo.
MiniMax H3 APIMiniMax-H3 · API de geração de vídeo · minimaxh3.video
MiniMax H3 API para geração de vídeo em produção
Crie fluxos de texto para vídeo, controle de primeiro e último quadro e geração com referências com a API do MiniMax H3. O contrato assíncrono retorna um task_id e, em seguida, uma URL para download do conteúdo.
POST /api/v1/video_generation200 · task_id
curl --request POST \
--url https://minimaxh3.video/api/v1/video_generation \
--header "Authorization: Bearer $MINIMAX_H3_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "MiniMax-H3",
"content": [
{
"type": "text",
"text": "Um ciclista atravessa uma rua da cidade iluminada pela chuva à noite, reflexos de neon no asfalto molhado, câmera acompanhando ao lado da bicicleta."
}
],
"duration": 5,
"resolution": "2K",
"ratio": "16:9"
}'- Endpoint
- POST /api/v1/video_generation
- Model ID
- MiniMax-H3
- Fluxo
- Tarefa assíncrona
- Saída
- 2K · 4–15s
- Auth
- Bearer API key
- Limite do prompt
- 7.000 caracteres
Contrato público
Um endpoint MiniMax H3, três modos criativos.
O MiniMax-H3 usa uma lista content[] multimodal. As funções que você atribui definem se a requisição é texto para vídeo, imagem para vídeo com primeiro/último quadro ou vídeo com referências.
02content: text + images
Primeiro / último quadro (i2va)
Adicione itens image_url com a função first_frame e, opcionalmente, last_frame para controlar a composição de abertura e encerramento.
03content: text + refs
Geração com referências (r2va)
Oriente personagem, movimento, câmera, estilo ou voz com imagens, vídeos e áudios de referência, sem misturar as funções de primeiro e último quadro.
O que a API oferece
Controle a cena, as referências e o contrato de saída.
O MiniMax H3 é documentado como um modelo de vídeo multimodal aberto e de uso geral. A API V2 foi construída para backends de produto, não apenas para testes isolados.
Entrada multimodal
Texto, imagem, vídeo e áudio em uma só requisição
Cada elemento de content[] tem um tipo e pode receber uma função. Referências de áudio precisam acompanhar uma entrada de imagem ou vídeo.
Janela de saída
2K nativo por 4–15 segundos
Duration aceita segundos inteiros de 4 a 15. Proporções comuns são suportadas; adaptativo é permitido quando a mídia define a geometria.
Orçamento de prompt
Até 7.000 caracteres de direção
Use esse espaço para estrutura do plano, movimento, trajetória de câmera, intenção de diálogo e mapeamento de referências — não para encher de palavras-chave.
Compatibilidade de funções
Primeiro/último quadro e referências são mutuamente exclusivos
Se houver qualquer função reference_*, first_frame e last_frame não podem aparecer. Validar essa regra evita erros 400 desnecessários.
Resultado assíncrono
task_id → status → content.url
Tarefas bem-sucedidas retornam uma URL de download com tempo limitado diretamente na resposta de consulta. Persista os identificadores e armazene o arquivo se precisar de durabilidade.
Gestão de tarefas
Listar, cancelar e janelas de expiração
A V2 documenta listagem, cancelamento/exclusão e uma janela curta de consulta para tarefas recentes. Trate a geração como uma tarefa gerenciada, não como uma única chamada HTTP longa.
Aplicações do produto
O que as equipes constroem com a API MiniMax H3
Use o mesmo fluxo assíncrono para ativos criativos únicos, ferramentas para criadores ou pipelines em lote.
Produtos para criadores
Geração de planos dentro do app
Permita que os usuários enviem um prompt ou primeiro quadro, mostre o estado da fila e entregue um clipe em 2K quando a tarefa for concluída.
Sistemas de marca
Campanhas guiadas por referências
Mantenha referências de personagem, produto, movimento ou voz entre planos curtos, sem reconstruir a identidade toda vez.
Ferramentas editoriais
Transições de primeiro para último quadro
Direcione quadros de abertura e encerramento controlados quando a continuidade do storyboard for mais importante que a improvisação pura.
Pipelines para redes sociais
Proporções verticais e cinemáticas
Gere ganchos em 9:16 ou planos-mestre em 16:9 a partir de uma única interface de integração, ramificando apenas em ratio e duration.
Backends de agentes
Tarefas multimodais em fila
Agentes podem montar arrays de conteúdo, consultar status e entregar content.url para etapas de armazenamento, moderação ou edição.
Estúdios de protótipo
Testes rápidos de direção
Explore combinações de câmera, performance e referências antes de se comprometer com um pipeline de produção completo.
Fluxo de trabalho assíncrono
Da chave de API a um vídeo MiniMax H3 pronto para download
A geração nunca precisa manter uma requisição HTTP aberta. Armazene os identificadores e siga os passos documentados da V2.
Criar
Enviar uma tarefa de geração
POST com model MiniMax-H3, um array de conteúdo, duration, resolution e ratio quando necessário. Uma resposta bem-sucedida retorna task_id.
POST /api/v1/video_generationObservar
Consultar status da tarefa
Consulte a tarefa até que ela atinja um estado terminal. Trate queued e running como estados intermediários normais.
GET /api/v1/video_generation/{task_id}Recuperar
Fazer download de content.url
Quando o status for succeeded, a resposta inclui content.url. A URL tem tempo limitado — copie o arquivo para um armazenamento que você controle se precisar de durabilidade.
content.url · mp4Design da requisição
Os campos que definem uma requisição MiniMax-H3 confiável
Mantenha a requisição pública explícita e valide as combinações específicas de cada modo antes de enviar uma tarefa.
Obrigatório
model
Use o identificador documentado exato MiniMax-H3. Não invente apelidos de produto como model IDs.
Corpo multimodal obrigatório
content[]
Inclua pelo menos um item type=text. Para os modos controlados, adicione itens image_url, video_url ou audio_url com as funções correspondentes.
4–15 segundos inteiros
duration
Escolha uma janela inteira única. Mais longo nem sempre é melhor se o plano precisa apenas de uma ação clara.
Saída documentada
resolution
O MiniMax H3 é documentado para saída em 2K. Confirme os valores de enum atuais na referência da API em produção antes de lançar.
Controle de geometria
ratio
Obrigatório para texto para vídeo puro e não deve ser adaptativo nesse modo. Fluxos guiados por imagem podem seguir a geometria da fonte.
Funções opcionais de mídia
first_frame · last_frame · reference_*
As funções alteram o contrato criativo. Valide a exclusão mútua e os limites de tamanho de cada arquivo durante o upload.
Estado da tarefa
Trate status como uma máquina de estados
Clientes de consulta devem tolerar estados intermediários e parar apenas nos resultados terminais documentados.
| Status | Significado | Comportamento recomendado da aplicação |
|---|---|---|
| queued | Aguardando capacidade | Persista task_id e aguarde entre consultas |
| running | Geração em andamento | Mantenha a tarefa visível; evite envios duplicados |
| succeeded | Vídeo pronto | Leia content.url e armazene o ativo |
| failed | Geração não foi concluída | Apresente código/mensagem de erro e permita nova tentativa deliberada |
| cancelled | Tarefa foi cancelada | Feche a tarefa na interface e mantenha um registro de auditoria |
| expired | Tarefa não está mais disponível | Não consulte indefinidamente; recrie se necessário |
Apenas tarefas recentes permanecem consultáveis. Confirme a janela oficial de retenção antes de projetar fluxos de recuperação de longa duração.
Limites de entrada
Valide a mídia antes de enviar à MiniMax H3
Os limites documentados são simples o suficiente para serem aplicados no momento do upload, evitando falhas de tarefa.
Imagens
JPG, JPEG, PNG, WEBP, HEIC, HEIF · ≤ 30 MB
Largura/altura em [256, 5760]; proporção entre 2:5 e 5:2. Primeiro quadro ≤ 1, último quadro ≤ 1, imagens de referência ≤ 9.
Vídeos
MP4/MOV com H.264/H.265 · ≤ 50 MB cada
Até 3 clipes de referência, cada um de 2–15s, total ≤ 15s. Áudio no vídeo pode ser AAC ou MP3.
Áudio
WAV ou MP3 · ≤ 15 MB cada
Até 3 clipes, cada um de 2–15s, total ≤ 15s. Áudio não pode ser enviado sozinho — combine com referências de imagem ou vídeo.
Refs mistas
No máximo 12 arquivos de mídia em uma requisição
O corpo da requisição deve ficar ≤ 64 MB. Prefira URLs públicas para ativos grandes em vez de Base64.
Exclusão de modo
Não misture primeiro/último quadro com funções de referência
Escolha entre controlar a composição com primeiro/último quadro ou gerar com referências multimodais; não combine os dois na mesma lista content[].
Prompt
Mantenha a direção abaixo de 7.000 caracteres
Mapeie referências no texto quando identidade, voz ou movimento devem seguir um ativo específico.
Preços ficam na página de preços
Taxas de créditos e limites de plano podem mudar. Aponte para a página de preços atual do MiniMax H3 em vez de codificar um número fixo na sua integração.
Adequação técnica
Quando a geração assíncrona do MiniMax H3 é a escolha certa
Use a API V2 quando seu produto puder criar uma tarefa e aguardar o conteúdo gerado.
Indicado para
Serviços de backend e ferramentas para criadores
Geração enfileirada, armazenamento durável e interfaces de status se integram naturalmente a fluxos de task_id.
Indicado para
Controle criativo multimodal
Planos que combinam direção de prompt com primeiros quadros, últimos quadros ou mídia de referência.
Limite
Não é um socket de streaming de vídeo em tempo real
Projete para consultas periódicas ou processadores internos de fila, em vez de manter uma conexão de geração aberta.
Limite
Projete para tarefas, não para conexões abertas
Mantenha gerações de longa duração na sua fila de backend e apresente o status na interface do produto.
Perguntas sobre a API
Perguntas sobre a API MiniMax H3
Respostas práticas antes de conectar a primeira requisição de produção.
MiniMax-H3 é o model ID para essa API?
Sim. Envie model MiniMax-H3 no endpoint de geração de vídeo do MiniMax H3 ao criar uma tarefa.
Qual endpoint devo chamar?
Crie tarefas com POST https://minimaxh3.video/api/v1/video_generation, depois consulte com GET https://minimaxh3.video/api/v1/video_generation/{task_id}. Em caso de sucesso, faça o download do mp4 em content.url.
Qual a diferença entre MiniMax H3 e a integração Hailuo 2.3?
O H3 é o modelo multimodal de uso geral atual, com contrato content[], saída documentada em 2K, duration de 4–15s e referências multimodais. O Hailuo 2.3 pertence a uma família anterior, com outro formato de requisição.
Posso combinar controle de primeiro quadro com áudio de referência?
Não na mesma requisição. As funções de primeiro/último quadro e as funções reference_* são mutuamente exclusivas. Escolha o modo adequado ao tipo de controle desejado.
Como faço autenticação?
Envie uma Bearer API key no header Authorization. Crie e gerencie chaves nas configurações da sua conta MiniMax H3 após ter acesso.
Onde devo confirmar os preços atuais?
Use a página de preços do site para planos de produto e créditos. O uso da API segue as mesmas regras de carteira de créditos publicadas lá.
Prototipe o plano. Envie a requisição da API.
Defina a direção criativa no gerador e depois chame a API do MiniMax H3 em minimaxh3.video com sua chave.