ToAPIs
    InícioToAPIs
    Geração de imagensGPT Image 2.6, Gemini, FLUX…Geração de vídeoSeedance, Veo, Kling, Sora…Chat e escritaGPT-5.6, Claude, DeepSeek…Voz e músicaLocuções, TTS, áudio
    NovidadeSeedance 2.5
    PreçosDocumentação da APIMCP
    BlogAlternativas
    EntrarComece grátis
    Todos os modelosPreçosDocumentação da APIMCPBlogAlternativas
    EntrarComece grátis

    Idioma

    Esc
    • Seedance 2.5Geração de vídeo
    • GPT Image 2Geração de imagens
    • GPT Image 2.6Geração de imagens
    • GPT Image 2.5Geração de imagens
    • Veo 3.1 FastGeração de vídeo
    • Kling 3.0 TurboGeração de vídeo
    • Kling V4 FlashGeração de vídeo
    • Grok Video 1.5Geração de vídeo
    • Nano Banana 2Geração de imagens
    • Seedream 5.5Geração de imagens
    • FLUXGeração de imagens
    • Sora 2Geração de vídeo
    • Todos os modelos de imagemCategoria
    • Todos os modelos de vídeoCategoria
    • GPT-5.6 SolChat e código
    • Claude Opus 4.8Chat e código
    • Claude Opus 4.7Chat e código
    • DeepSeek V4 ProDeepSeek · Texto
    • Gemini Omni 1.1 FlashGoogle · Multimodal
    1. Início
    2. Blog
    3. Tutorial
    4. Guia da API MiniMax H3: texto para vídeo e entradas de referência
    Voltar a todos os artigos
    tutorial2026-10-2212 min de leitura

    Guia da API MiniMax H3: texto para vídeo e entradas de referência

    Guia prático para chamar os modelos de vídeo MiniMax H3 pela ToAPIs, com exemplos de requisição, modos de entrada aceitos, limites por modelo e orientação para consultar o estado das tarefas.

    ToAPIs Engineering Team
    MiniMax H3API de vídeoR2VPythonTutorial
    TL;DR - Principais conclusões
    • O ID de modelo da API define qual variante do H3 fica disponível; use o ID exato habilitado para a sua conta.
    • O contrato atual do frontend da ToAPIs aceita clipes de 4 a 15 segundos na família H3 base, com limites de resolução que variam por variante.
    • Use entradas de primeiro e último quadro ou mídia de referência em uma mesma requisição; não misture os dois modos.
    • Este guia documenta a montagem de requisições, não um benchmark de latência, qualidade, disponibilidade ou preço.

    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:

    bash
    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.

    python
    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 modeloDuração aceita pelo frontendOpções de resolução representadas no frontend
    minimax-h3 e minimax-h3-global4 a 15 segundos, número inteiro2K, 768p
    minimax-h3-max-turbo e outras variantes Max5 a 15 segundos, número inteiro480P, 768P
    minimax-h3-max canônico5 a 15 segundos, número inteiroOpçõ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:

    1. Modo de quadros: envie no máximo um first_frame_image e no máximo um last_frame_image. O cliente escolhe uma proporção adaptativa quando há entradas de quadro.
    2. 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:

    json
    {
      "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:

    json
    {
      "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 HTTPCategoria comumAção recomendada
    400Campo inválido, valor não aceito ou conflito de modo de mídiaVerifique o ID de modelo, a duração, a resolução, a proporção e as contagens de entrada.
    401Chave de API ausente ou inválidaVerifique a chave no seu gerenciador de segredos e nos cabeçalhos da requisição.
    429Limite de taxa ou de concorrênciaRecue com variação aleatória e repita apenas quando for seguro.
    5xx ou tempo esgotado na redeProblema temporário do gateway ou do upstreamVerifique 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:

    1. Leia o ID do modelo selecionado no momento a partir do catálogo de modelos.
    2. Carregue as opções de duração e de resolução desse modelo.
    3. Peça ao usuário que escolha o modo de quadros ou o modo de referência.
    4. Valide contagens de campo e compatibilidade antes de enviar mídia.
    5. Envie a mídia escolhida pelo endpoint de recursos documentado.
    6. Monte um objeto de requisição novo a partir dos valores validados.
    7. 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:

    python
    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.

    Explore os modelos mencionados neste artigo

    MiniMaxVIDEO

    minimax-h3

    Taxa atual: 20.8 credits /second
    Guia do modeloTestar no consoleObter chave de API
    MiniMaxVIDEO

    minimax-h3-max

    Taxa atual: 8 credits /second
    Guia do modeloTestar no consoleObter chave de API
    ToAPIsAI Model

    minimax-h3-max-turbo

    Taxa atual: Ver preços em tempo real
    Guia do modeloTestar no consoleObter chave de API

    Artigos relacionados

    tutorial2026-11-10T14:00:00+08:006 min de leitura

    Como criar um pipeline automatizado de imagem para vídeo (R2V) com a API MiniMax H3

    Tutorial de engenharia para um pipeline automatizado de Reference-to-Video no MiniMax H3: entradas de primeiro quadro, preparação de recursos, sondagem limitada de tarefas e o contrato de requisição do frontend da ToAPIs.

    TO
    ToAPIs Engineering & Evaluation Team
    #MiniMax H3
    tutorial2026-11-10T10:00:00+08:006 min de leitura

    Guia de prompts do MiniMax H3: como criar movimentos de câmera cinematográficos pela API

    Guia para desenvolvedores sobre como escrever prompts de movimentos de câmera cinematográficos para a API de vídeo MiniMax H3 na ToAPIs: modelos reutilizáveis, exemplos em cURL e Python e o contrato de requisição atual do frontend.

    TO
    ToAPIs Engineering & Evaluation Team
    #MiniMax H3
    tutorial2026-11-11T10:00:00+08:007 min de leitura

    Integração da API MiniMax Hailuo 2.3: gerar movimento humano complexo em vídeo com IA

    Guia para desenvolvedores sobre a API de vídeo MiniMax Hailuo 2.3 na ToAPIs: padrões de prompt para movimento humano, o contrato atual de requisição para trabalhos de 6 e 10 segundos em 768P e 1080P, e exemplos em cURL e Python.

    TO
    ToAPIs Engineering & Evaluation Team
    #MiniMax Hailuo
    ToAPIs
    InícioToAPIs
    Gateway empresarial de API de IA. Acesse GPT-5, Claude, Gemini e mais de 200 modelos por uma única API unificada.

    Modelos populares

    • Seedance 2.5 API
    • Seedance 2.0 API
    • Veo 3.1 Fast API
    • Kling 3.0 Turbo API
    Mostrar maisMostrar menos
    • GPT Image 2 API
    • Claude Opus 4.8 API
    • Nano Banana 2 API
    • Seedance 2 Mini API
    • Todos os modelos

    Categorias de API

    • API de imagem com IA
    • API de vídeo com IA
    • API de texto para vídeo
    • API de imagem para vídeo
    Mostrar maisMostrar menos
    • API de edição de imagens com IA
    • API de LLM e raciocínio
    • Todas as ferramentas de API →

    Alternativas

    Alternativas
    • Alternativa ao Kie.ai
    • Alternativa ao Fal.ai
    • Alternativa ao OpenRouter
    • Alternativa ao Replicate
    • Alternativa ao Wavespeed AI
    • Todas as comparações →

    Guias em destaque

    Guias em destaque
    • Preços do Seedance 2.0 e 2.5
    • Guia da API Seedance mais barata
    • Guia de integração do MiniMax H3
    • Chave de API gratuita do Seedance 2
    • Início rápido da API Seedance 2
    • Todos os artigos técnicos →

    Desenvolvedores e plataforma

    Desenvolvedores e plataforma
    • Documentação da API
    • MCP
    • Preços
    • Playground de modelos
    • LLMs.txt
    • Falar com o suporte
    • Diretório de guias de modelos
    Entidade operadora:
    鯨樞智能科技有限公司
    JINGSHU INTELLIGENT LIMITED
    Sede social:
    ROOM 5042, 5/F, YAU LEE CENTRE, NO.45, HOI YUEN ROAD, KWUN TONG, KOWLOON, HONG KONG
    PrivacidadeTermosUso aceitávelExclusão de dadosRetenção de dadosSubprocessadores e regiõesCobrança e reembolsosPolítica de CookiesMapa do siteSobre

    © 2026 ToAPIs. Todos os direitos reservados.