Guia da API MiniMax H3: texto para vídeo e entradas de referência
Requisições ao MiniMax H3 são fáceis de configurar errado quando um cliente trata todas as variantes do modelo como intercambiáveis. O ID de modelo escolhido afeta a validação de duração e resolução, enquanto o modo de mídia define quais campos de imagem, vídeo e áudio podem ser enviados juntos.
Este guia descreve o contrato de requisição representado no frontend da ToAPIs em 22 de outubro de 2026. É um guia de integração, não um relatório de desempenho do provedor upstream nem do preço atual da sua conta. Confirme se a sua conta tem acesso ao modelo solicitado antes de enviar tarefas de produção.
Início rápido
O endpoint de geração usado nos exemplos da API da ToAPIs é POST /v1/videos/generations. Autentique-se com uma chave de API da ToAPIs e envie um prompt, um ID de modelo habilitado, a duração e a proporção. Por exemplo:
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3",
"prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
"duration": 5,
"ratio": "16:9"
}'
Trate a resposta como o envio de uma tarefa assíncrona. Leia o identificador de tarefa devolvido pela resposta da API da sua conta e consulte o estado pelo endpoint de status documentado. Não presuma um formato de resposta fixo, a menos que ele esteja especificado na referência da API da sua conta.
import os
import time
import requests
BASE_URL = "https://api.toapis.com/v1"
API_KEY = os.environ["TOAPIS_API_KEY"]
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.post(
f"{BASE_URL}/videos/generations",
headers=headers,
json={
"model": "minimax-h3",
"prompt": "A slow cinematic pan across a quiet coastal town at sunrise",
"duration": 5,
"ratio": "16:9",
},
timeout=30,
)
response.raise_for_status()
submission = response.json()
print("Submission response:", submission)
O exemplo imprime a resposta de propósito, em vez de supor onde aparecem o ID da tarefa ou a URL do vídeo. Ajuste o código de leitura e de consulta ao esquema de resposta documentado para a sua conta. Assim você evita tratar silenciosamente um formato alterado como uma tarefa bem-sucedida.
Escolha o ID de modelo exato
O frontend reconhece minimax-h3 e minimax-h3-global como IDs da família base, além de IDs que contêm minimax-h3-max. Por exemplo, o ID do modelo Turbo usado no produto é minimax-h3-max-turbo. Use o identificador canônico exibido no catálogo de modelos disponível e evite criar aliases ou encurtar o ID.
No momento, o frontend aplica estes limites de capacidade:
| Família / ID de modelo | Duração aceita pelo frontend | Opções de resolução representadas no frontend |
|---|---|---|
minimax-h3 e minimax-h3-global | 4 a 15 segundos, número inteiro | 2K, 768p |
minimax-h3-max-turbo e outras variantes Max | 5 a 15 segundos, número inteiro | 480P, 768P |
minimax-h3-max canônico | 5 a 15 segundos, número inteiro | Opções Max mais 1080P |
São restrições de validação do frontend, não uma garantia de que toda conta ou rota upstream tenha a mesma disponibilidade. Em especial, a opção extra de 1080P está associada apenas ao ID canônico exato minimax-h3-max no cliente atual. Não presuma que Turbo, um alias -global ou qualquer modelo H3 aceite 1080P.
Escolha um único modo de mídia
O formulário do H3 aceita dois fluxos de trabalho mutuamente exclusivos:
- Modo de quadros: envie no máximo um
first_frame_imagee no máximo umlast_frame_image. O cliente escolhe uma proporção adaptativa quando há entradas de quadro. - Modo de referência: envie imagens, vídeos e/ou áudios de referência sem entradas de primeiro ou último quadro. O cliente usa a proporção selecionada para essas referências.
Exemplo de requisição com primeiro quadro:
{
"model": "minimax-h3",
"prompt": "The subject turns toward the camera as the camera gently moves forward",
"duration": 5,
"ratio": "16:9",
"first_frame_image": ["https://example.com/starting-frame.jpg"]
}
Exemplo de requisição com mídia de referência:
{
"model": "minimax-h3",
"prompt": "Use the supplied references to guide the scene and motion",
"duration": 5,
"ratio": "16:9",
"media_mode": "reference",
"reference_images": ["https://example.com/character-reference.jpg"],
"reference_videos": ["https://example.com/motion-reference.mp4"]
}
O formato exato dos valores para mídia enviada depende do fluxo de upload de mídia do gateway. Estes exemplos mostram os campos da requisição, não afirmam que qualquer URL pública seja aceita por todas as rotas. Use as URLs ou os identificadores de recurso devolvidos pelo fluxo de upload documentado.
O frontend aplica estes limites de referência:
- Até 9 imagens de referência.
- Até 3 vídeos de referência.
- Até 3 áudios de referência.
- No máximo 12 recursos de referência no total.
- Cada vídeo de referência deve ter de 2 a 15 segundos, e a duração total das referências enviadas não pode passar de 15 segundos.
- Referências de áudio exigem pelo menos uma referência visual.
- Requisições Turbo não podem incluir mídia de referência.
Respeite essas restrições antes de enviar. Uma requisição que mistura modos de entrada, excede uma contagem ou omite o contexto visual exigido é rejeitada localmente pelo frontend, em vez de ser enviada como uma requisição válida de geração H3.
Opções de prompt e de geração
O prompt é obrigatório e o frontend atual o limita a 7.000 caracteres Unicode. Descreva a cena, o sujeito, o movimento e a intenção visual em linguagem natural. Trate as etiquetas de câmera entre colchetes e qualquer outra sintaxe especial como texto comum de prompt, a menos que a documentação do modelo upstream as defina explicitamente. As evidências disponíveis no contrato do frontend não confirmam que strings como [Pan Left] sejam comandos nativos do H3.
O montador de requisições repassa controles opcionais aceitos, como prompt_optimizer, watermark e seed, conforme a rota de modelo escolhida. Não presuma que todos os canais upstream aceitem esses campos opcionais da mesma forma. Se você os expuser na sua própria interface, valide-os contra o catálogo específico do modelo e remova campos obsoletos quando o usuário trocar de variante.
Para proporção, o frontend aceita adaptive, 21:9, 16:9, 4:3, 1:1, 3:4 e 9:16. Entradas de quadro forçam adaptive. Em texto para vídeo, uma seleção adaptativa é normalizada para 16:9; o modo de referência mantém a proporção aceita que foi solicitada.
Crie prompts que possam ser testados
Escrever prompts não é um parâmetro da API, mas influencia o quanto uma integração técnica é útil para quem a utiliza. Peça aos usuários que descrevam uma cena e uma ação principal antes de acrescentar direção de câmera, iluminação ou estilo. Um prompt compacto pode especificar sujeito, ação, ambiente e comportamento da câmera nessa ordem. Mantenha essas partes estáveis durante uma comparação de modelos; caso contrário, uma mudança de redação pode explicar um resultado diferente.
Não prometa que uma frase específica garante movimento de câmera, correspondência de identidade, taxa de quadros ou estilo visual. O contrato do frontend valida o prompt como texto e aplica um limite de caracteres. Ele não define uma gramática de comandos padrão para etiquetas de câmera. Se a sua aplicação oferece controles de prompt predefinidos, rotule-os como auxílios de prompt e não como controles garantidos do modelo, a menos que a documentação upstream confirme esse comportamento.
Para fluxos de geração repetidos, guarde a versão do modelo de prompt junto ao registro da tarefa. Isso permite distinguir uma mudança de modelo de uma mudança de prompt quando os usuários relatam resultados diferentes. Evite incluir chaves de API, identificadores privados ou dados pessoais nos prompts. Revise o conteúdo do prompt em relação às políticas de conteúdo e privacidade do seu produto antes de permitir envios em lote sem supervisão.
Normalize proporção e resolução de forma deliberada
Proporção e resolução respondem a perguntas distintas: a proporção descreve a forma da saída, enquanto a resolução escolhe um tamanho de saída aceito pela rota do modelo. Uma proporção aceita não implica que qualquer resolução possa ser combinada com ela. Mantenha os dois campos na interface e valide-os contra o modelo selecionado no momento.
Se o usuário escolher o modo de primeiro quadro ou de primeiro e último quadro, o frontend força uma proporção adaptativa para que os quadros de entrada guiem a forma da tela. Não exiba uma proporção personalizada conflitante como se ela fosse ser respeitada. No modo de texto para vídeo, a opção adaptativa resolve para o comportamento padrão de 16:9 no montador atual. Se você tornar essa normalização visível, mostre o valor realmente enviado em uma etapa de revisão, para que os usuários entendam o que o gateway recebe.
Os rótulos de resolução também diferem em maiúsculas entre variantes (768p versus 768P). Normalize-os apenas se o contrato da API do modelo escolhido permitir isso explicitamente. Evite converter valores de modelo globalmente, porque um valor aceito por uma rota pode ser rejeitado por outra.
Consulta de status e erros
A geração de vídeo é assíncrona. Depois de enviar, guarde o identificador da tarefa e consulte o endpoint de status documentado para a sua conta de API. Use recuo exponencial limitado com variação aleatória em vez de um laço curto e repetido, defina um prazo final e trate a falha terminal separadamente do tempo esgotado. Um tempo esgotado não prova que a tarefa upstream falhou; verifique o status da tarefa antes de repetir uma geração faturável.
No mínimo, o seu cliente deve:
- Chamar
raise_for_status()ou equivalente nas respostas HTTP. - Ler a resposta conforme o esquema de API publicado.
- Parar de consultar em um estado final documentado de sucesso ou de falha.
- Limitar o número de tentativas e o tempo total decorrido.
- Evitar enviar uma geração duplicada apenas porque uma requisição do lado do cliente estourou o tempo.
- Registrar um identificador de requisição ou de tarefa, mas nunca a chave de API nem URLs de mídia privadas.
As categorias genéricas de erro abaixo são pontos de partida para diagnóstico, não uma garantia dos códigos de erro exatos da ToAPIs:
| Status HTTP | Categoria comum | Ação recomendada |
|---|---|---|
400 | Campo inválido, valor não aceito ou conflito de modo de mídia | Verifique o ID de modelo, a duração, a resolução, a proporção e as contagens de entrada. |
401 | Chave de API ausente ou inválida | Verifique a chave no seu gerenciador de segredos e nos cabeçalhos da requisição. |
429 | Limite de taxa ou de concorrência | Recue com variação aleatória e repita apenas quando for seguro. |
5xx ou tempo esgotado na rede | Problema temporário do gateway ou do upstream | Verifique o status da tarefa antes de reenviar; use uma política de repetição limitada. |
Preços e garantias de serviço
Preços, tempo de atividade, comportamento de reembolso e acordos de nível de serviço podem variar por modelo, rota e conta. Este guia não cita de propósito um preço por segundo nem promete um SLA de disponibilidade. Consulte o catálogo atual de modelos da ToAPIs e o preço da sua conta antes de estimar custos de projeto. Não use um preço de rascunho de planejamento como cotação de produção.
Um fluxo de trabalho mais seguro para montar requisições
Mantenha a seleção e a validação de modelo em um único lugar da sua aplicação. Quando o usuário trocar de modelo, reconstrua as opções permitidas em vez de levar todos os campos da seleção anterior para a próxima requisição. Isso importa ao passar do H3 base para Max ou Turbo: uma resolução, uma lista de mídia de referência ou um valor de duração podem ser válidos para um modelo e inválidos para outro.
Uma sequência confiável do lado do cliente é esta:
- Leia o ID do modelo selecionado no momento a partir do catálogo de modelos.
- Carregue as opções de duração e de resolução desse modelo.
- Peça ao usuário que escolha o modo de quadros ou o modo de referência.
- Valide contagens de campo e compatibilidade antes de enviar mídia.
- Envie a mídia escolhida pelo endpoint de recursos documentado.
- Monte um objeto de requisição novo a partir dos valores validados.
- Envie uma única vez, guarde o identificador de tarefa devolvido e exponha o estado da tarefa ao usuário.
Evite modificar no local um objeto de requisição antigo. Um objeto novo reduz a chance de um campo como reference_videos vazar para uma requisição Turbo depois de uma troca de modelo. O contrato do frontend da ToAPIs também torna o modo explícito: media_mode pode ser frame ou reference, e entradas misturadas são rejeitadas.
Para uma integração própria, replique estas verificações antes da chamada de rede:
def validate_h3_request(model, duration, resolution, frame_images, refs):
is_max_family = "minimax-h3-max" in model
is_turbo = "turbo" in model
min_duration = 5 if is_max_family else 4
if not isinstance(duration, int) or not min_duration <= duration <= 15:
raise ValueError("Duration is outside this model's supported range")
if len(frame_images) > 2:
raise ValueError("Use at most one first frame and one last frame")
if frame_images and refs:
raise ValueError("Frame inputs and reference media are separate modes")
if is_turbo and refs:
raise ValueError("This Turbo route does not accept reference media")
if len(refs.get("images", [])) > 9:
raise ValueError("Too many reference images")
if len(refs.get("videos", [])) > 3:
raise ValueError("Too many reference videos")
Esta é uma proteção ilustrativa do lado do cliente, não um substituto para a validação no servidor. O código de produção também deve validar cada tipo de mídia, calcular a contagem total de referências e a duração dos vídeos, aplicar a lista de resoluções específica do modelo e usar os identificadores reais devolvidos pelo fluxo de upload.
Considerações de upload e privacidade
Trate a mídia de referência como dados do usuário. Envie apenas arquivos que o usuário está autorizado a usar e garanta que as suas regras de retenção e de acesso cobrem as imagens, os áudios e os vídeos de origem. Não publique mídia de origem privada em URLs públicas apenas para simplificar uma demonstração. Se a API devolver uma URL temporária de recurso, evite gravá-la em ferramentas de análise ou em logs de longa duração.
Valide os arquivos antes do upload: rejeite extensões e tipos MIME não aceitos, aplique os limites documentados de tamanho e de quantidade e mostre um erro claro antes de gastar tempo com uma requisição de geração. Mantenha o identificador de upload associado ao registro da tarefa, mas não exponha caminhos de armazenamento internos em uma página pública. Se um upload falhar, pare antes de criar uma tarefa de geração em vez de enviar uma requisição incompleta.
Para repetições, distinga leituras idempotentes de envios de geração faturáveis. Repetir uma verificação de status por GET geralmente é diferente de repetir um POST que já pode ter criado uma tarefa. Se o cliente perder a resposta do envio, use primeiro qualquer identificador de requisição ou mecanismo de recuperação documentado para a conta. Se não existir nenhum, mostre um estado incerto ao operador em vez de criar silenciosamente um duplicado.
Lista de verificação de implantação
Antes de publicar uma integração H3, teste ao menos uma requisição válida por ID de modelo habilitado para a sua conta. Adicione testes negativos com duração fracionária, resolução não aceita, referências em excesso, entradas de quadro e referência combinadas e referências em Turbo. Verifique se a interface limpa os valores incompatíveis depois de uma troca de modelo.
No ambiente de staging, registre os campos da requisição após a validação e compare-os com o esquema documentado do gateway. Não capture chaves de API nem dados de mídia privada nos logs. Confirme a URL de consulta de status, os estados da tarefa e o campo de resultado com um fixture que não seja de produção ou com uma conta de teste aprovada. Este artigo não chama um endpoint em live nem valida o comportamento do serviço remoto.
Por fim, verifique o preço da conta do usuário e o catálogo de modelos imediatamente antes do lançamento. A disponibilidade e o preço de modelos são informações próprias de cada conta; valores copiados de um artigo antigo podem ficar desatualizados mesmo que os campos de requisição não mudem.
Modelos relacionados e próximos passos
- Explorar os modelos de vídeo
- Abrir o Playground com MiniMax H3
- Abrir o Playground com MiniMax H3 Max Turbo
Antes de implantar, verifique o ID de modelo exato, a disponibilidade atual da rota, o formato de upload, o esquema de resposta e o preço da conta na documentação da API à sua disposição.







