Hailuo API: guia do MiniMax H3 em Python e 3 modos de vídeo testados

A API Hailuo é a API de vídeo da MiniMax, e o modelo atual é o MiniMax H3 (MiniMax-H3), a geração seguinte ao Hailuo 01 e ao 02. Toda chamada é assíncrona: criar a tarefa, consultar, baixar o MP4. Em 26 de outubro de 2026, nossos clipes de 5 segundos em 768P levaram de 35 a 42 segundos nos três modos, e todos vieram com som.

Resposta rápida

• Modelo: MiniMax-H3 na API da MiniMax, anunciado em 31 de julho de 2026 (notas da versão); minimax-h3 na OmniaKey, um id para os três tipos de tarefa (documentação de vídeo).
• Ajustes: resolution (obrigatório) com "768P" ou "2K", duration de 4 a 15 segundos inteiros, aspect_ratio (documentação de vídeo).
• Custo: $0.08 por segundo em 768P, $0.40 por 5 segundos, $0.13 em 2K, o preço de tabela da MiniMax (preços, conferido em 26 de outubro de 2026); a tarifa da OmniaKey está na página do modelo.
• Tempo e som: de 35 a 42 segundos por clipe, todos com som estéreo; a referência de criação da V2 não lista nenhuma opção para desligar o som (referência de criação).

Existe uma API Hailuo oficial?

Sim. A MiniMax mantém a API em platform.minimax.io, e o modelo atual lá é o MiniMax H3, com id MiniMax-H3 (página de modelos, conferida em 26 de outubro de 2026).

O anúncio da MiniMax apresenta o H3 como a geração seguinte ao Hailuo 01 e ao Hailuo 02 (anúncio). Os modelos anteriores continuam na API, como MiniMax-Hailuo-2.3 e MiniMax-Hailuo-02 (referência da V1).

O nome muda de página para página. A documentação da MiniMax escreve "MiniMax H3", a descrição do modelo na API escreve "Hailuo-03" (referência de criação) e o aplicativo Hailuo AI, para onde o anúncio manda quem quer testar, escreve "Hailuo 3.0" (aplicativo). "Hailuo 3" não é nome oficial.

A chave é criada em Account > API Keys, e a cobrança é por uso (FAQ da API). Os pacotes de vídeo da MiniMax cobrem os modelos anteriores, não o H3 (preços).

A MiniMax lista quatro variantes do H3 (referência de criação):

Na API própria da MiniMax, uma chamada tem três passos (guia de vídeo):

• POST https://api.minimax.io/v2/video_generation devolve um task_id (referência de criação).
• Consulte GET /v2/query/video_generation/{task_id} até succeeded e baixe content.url (referência de consulta).
• Só é possível consultar tarefas dos últimos 7 dias, e a MiniMax não publica por quanto tempo a URL de download vale (referência de consulta).

A V1 (Hailuo 2.3 e 02) passa o id da tarefa como parâmetro ?task_id= em vez de um trecho do caminho, então mantenha os dois fluxos separados (referência da V1).

A OmniaKey vende acesso à API do MiniMax H3, e foi por ela que rodamos estes exemplos. O fluxo é o mesmo: POST https://api.omniakey.com/v1/media/tasks com o cabeçalho Idempotency-Key devolve 202 e um id, e você consulta GET /v1/media/tasks/{id} (visão geral de mídia). O mesmo fluxo roda o Grok Imagine Video no nosso guia da API do Grok Imagine Video. Todos os preços abaixo são os de tabela da MiniMax.

Quais parâmetros dá para ajustar?

• resolution é obrigatório; 1080P e 4K falham com 400 model_price_error (documentação de vídeo), e a V2 não tem 1080P para o H3 (referência de criação). Os três modos rodaram em 768P, e não testamos 2K.
• duration vai de 4 a 15 segundos inteiros (documentação de vídeo); o MiniMax-H3-Max começa em 5 e recusa 4 (referência de criação).
• aspect_ratio aceita adaptive, 16:9, 9:16, 1:1, 4:3, 3:4 ou 21:9 (documentação de vídeo). Na API da MiniMax, texto para vídeo exige uma proporção fixa e imagem para vídeo segue o formato da imagem (referência de criação). Deixamos a proporção de fora no nosso teste de imagem para vídeo, e o clipe manteve o formato da imagem estática, 1376×768.
• input.media[] aceita first_frame e um last_frame opcional para imagem para vídeo, ou reference_image, reference_video e reference_audio para referência para vídeo. Os dois tipos não se misturam, e uma referência de áudio precisa de uma referência de imagem ou de vídeo junto (documentação de vídeo). Cada item é um type e uma url, seja um link HTTPS público, seja um data URI. A OmniaKey limita a requisição inteira a 1 MiB, Base64 incluído (visão geral de mídia), por isso o script envia JPEGs de 1024 pixels.
• O prompt vai em input.prompt (documentação de vídeo), até 7,000 caracteres (guia de vídeo). O som que você quer também se descreve ali.

Como chamar a API Hailuo em Python?

Você precisa de Python 3 e requests, com a chave em uma variável de ambiente.

pip install requests
export OMNIAKEY_API_KEY="your-key"
python hailuo_h3.py t2v   # or i2v (needs bicycle.jpg) or r2v (needs robot.jpg)

O único argumento é t2v, i2v ou r2v; as execuções que precisam de imagem leem bicycle.jpg ou robot.jpg da mesma pasta.

Este é o script que rodamos, sem alterações:

import base64
import os
import sys
import time
import uuid

import requests

API = "https://api.omniakey.com/v1/media/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}"}

DRUMMER = (
    "A street drummer plays a fast rhythm on upturned plastic buckets on a rainy city sidewalk "
    "at night. Neon signs reflect in the puddles and a few people with umbrellas walk past "
    "behind him. The camera slowly pushes in from a medium shot to a close-up of his hands and "
    "drumsticks. Realistic, handheld documentary look, with the sound of rain and drumming."
)
BICYCLE = (
    "A gentle breeze moves the daisies in the basket and a few petals drift down to the "
    "cobblestones. The camera slowly pushes in toward the basket. The bicycle and the wall "
    "stay exactly as they are."
)
ROBOT = (
    "The small orange robot from the reference image waters potted plants on a sunny "
    "apartment balcony with a red watering can. Medium shot, slow sideways camera move, "
    "city rooftops in the background."
)


def data_uri(path):
    # A local JPEG sent inline. The whole request must stay under 1 MiB, so keep it small.
    with open(path, "rb") as f:
        return "data:image/jpeg;base64," + base64.b64encode(f.read()).decode()


def make_video(operation, prompt, parameters, media, out):
    task_input = {"prompt": prompt}
    if media:
        task_input["media"] = media

    # 1. Create the task. Reuse the same Idempotency-Key only when retrying this exact request.
    resp = requests.post(
        API,
        headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
        json={
            "model": "minimax-h3",
            "type": "video",
            "operation": operation,
            "input": task_input,
            "parameters": parameters,
        },
        timeout=60,
    )
    resp.raise_for_status()
    task = resp.json()
    print(operation, "task:", task["id"])

    # 2. Poll the same task. Slow is not failed: never resubmit, keep polling this id.
    deadline = time.time() + 15 * 60
    while task["status"] in ("queued", "processing"):
        if time.time() > deadline:
            raise SystemExit(f"still {task['status']}: poll {task['id']} again later")
        time.sleep(5)
        task = requests.get(f"{API}/{task['id']}", headers=HEADERS, timeout=30).json()
    if task["status"] != "succeeded":
        raise SystemExit(f"{operation} ended {task['status']}: {task.get('error')}")

    # 3. Download the clip now: the signed URL lasts about an hour.
    asset = task["assets"][0]
    with open(out, "wb") as f:
        f.write(requests.get(asset["url"], timeout=120).content)
    print("saved", out, asset["byte_size"], "bytes")


mode = sys.argv[1] if len(sys.argv) > 1 else "t2v"
if mode == "t2v":
    make_video(
        "text_to_video", DRUMMER,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        None, "drummer.mp4",
    )
elif mode == "i2v":
    make_video(
        "image_to_video", BICYCLE,
        {"resolution": "768P", "duration": 5},
        [{"type": "first_frame", "url": data_uri("bicycle.jpg")}], "bicycle.mp4",
    )
elif mode == "r2v":
    make_video(
        "reference_to_video", ROBOT,
        {"resolution": "768P", "duration": 5, "aspect_ratio": "16:9"},
        [{"type": "reference_image", "url": data_uri("robot.jpg")}], "robot.mp4",
    )

A saída de 27 de outubro de 2026:

$ python hailuo_h3.py t2v
text_to_video task: task_V5TXAJG7n3ny42imJNqgTXRL4L8PGStd
saved drummer.mp4 4612510 bytes
$ python hailuo_h3.py i2v
image_to_video task: task_c4m3wHmF79Cmq7ZhDrTnCyt8SmIaW1ls
saved bicycle.mp4 4705286 bytes
$ python hailuo_h3.py r2v
reference_to_video task: task_dqx1TYA7u0znN5PFTl9tbfdWgtbBUbKd
saved robot.mp4 5630121 bytes

Cada execução levou de 47 a 60 segundos do início ao arquivo salvo.

Guarde o id da tarefa. Uma tarefa lenta não falhou, então consulte o mesmo id em vez de reenviar (visão geral de mídia). A URL de download assinada dura cerca de uma hora e o registro da tarefa 24 horas, então salve o arquivo na hora ou consulte de novo para pegar uma URL nova. O download em si não precisa de chave de API.

O que os três modos devolveram

Os três clipes vieram de três tarefas de 26 de outubro de 2026, com os corpos de requisição exatos do script.

Todo clipe era MP4, H.264, 24 fps, 5.17 segundos, com áudio AAC estéreo a 32 kHz; o usage trazia output_seconds: 5.

Texto para vídeo: o baterista de rua

O prompt é o DRUMMER do script.

O que vimos:

• Uma calçada molhada à noite, com neon vermelho e azul refletido no chão, carros estacionados e um baterista de jaqueta preta com capuz inclinado sobre baldes azuis virados para baixo. O capuz esconde o rosto o tempo todo.
• A câmera avança de um plano aberto para um close das mãos, das baquetas em movimento e do topo dos baldes, enquanto uma pessoa de guarda-chuva passa atrás.
• As letras das placas de neon não formam palavras reais. As batidas de tambor ficam mais fortes perto do fim, mas a chuva não se distingue no som.

O que mudar: se precisar de um rosto, acrescente "hood down, face visible"; se a chuva tiver que ser ouvida, dê a ela uma frase de som própria.

Imagem para vídeo: o primeiro quadro fica

O primeiro quadro é uma imagem estática feita com o Nano Banana 2.1; o prompt é o BICYCLE e descreve só o movimento.

O que vimos:

• O primeiro quadro corresponde à imagem estática: a mesma bicicleta vermelha, a parede de reboco amarela, as venezianas, as plantas em vaso e o calçamento de pedras.
• A câmera avança até a cesta de margaridas brancas preencher o quadro, e a bicicleta e a parede mantêm a forma até o fim.
• Nos quadros que conferimos, não vimos pétalas caindo. O som é uma melodia lenta de piano solo, embora o prompt não mencione som nem música.

O que mudar: descreva só o movimento e o som, porque a imagem estática já define a aparência, e faça a imagem estática no formato que o clipe deve ter.

Referência para vídeo: uma imagem mantém o personagem

A referência é uma única imagem de um robô laranja pequeno feita com o Nano Banana 2.1; o prompt é o ROBOT.

O que vimos:

• O mesmo robô: corpo arredondado laranja, olhos redondos de vidro azul, uma antena curta com uma bola no topo e um disco redondo na lateral da cabeça, agora numa varanda ensolarada com vasos de flores e ervas.
• Ele rega com um regador vermelho, o jato de água aparece por volta de 1 segundo e a câmera se desloca um pouco para o lado.
• O som é de água correndo e respingando, começa pouco antes de o jato aparecer e não tem música.

O que mudar: o personagem não precisou de correção. Para mantê-lo igual em vários clipes, reutilize a mesma imagem de referência a cada vez.

Som: descreva, ou o H3 escolhe

Quando o prompt não dizia nada sobre som, o H3 escolheu: água para o robô, o que combina com a rega, e piano para a bicicleta. Descreva no prompt o som de que você precisa. A referência de criação da V2 não lista nenhuma opção para desligar o som (referência de criação), então, para um clipe mudo, remova a faixa depois:

ffmpeg -i drummer.mp4 -an -c copy drummer-silent.mp4

Isso grava uma cópia só com o vídeo H.264, ainda com 5.17 segundos e sem recodificar.

Quais erros você vai encontrar?

Os erros vêm da API de tarefas da OmniaKey e, numa chamada direta, da API da MiniMax.

• 400 missing_idempotency_key: Falta o cabeçalho Idempotency-Key. Adicione um.
• 409 idempotency_key_reused: Mesma chave, corpo novo. Uma chave por tarefa.
• 400 model_price_error: 1080P ou 4K. Use 768P ou 2K.
• 400 invalid_request: Corpo ou parâmetro errado. Confira os parâmetros.
• 403 model_not_allowed: A chave não tem este modelo. Confira o acesso da chave.
• 503 no_available_channel: Modelo indisponível agora. Tente de novo mais tarde.
• provider_submit_uncertain: Recusado no envio. Use input.prompt e confira a mídia.
• Tarefa failed: A geração falhou. Leia o error.

Uma tarefa que falhou ou foi cancelada é reembolsada (visão geral de mídia). Na API própria da MiniMax (códigos de erro, conferidos em 26 de outubro de 2026):

• A MiniMax envia o status HTTP correspondente a cada código, por exemplo 401 com 1004 e 400 com 2013 (referência de criação).
• O H3 na V2 permite 300 requisições por minuto e 30 tarefas rodando ao mesmo tempo (limites de uso).

Quanto custa a API Hailuo?

A MiniMax cobra o H3 por segundo de vídeo gerado, conforme a variante e a resolução (página de preços, conferida em 26 de outubro de 2026):

Com esses preços: 5 segundos em 768P saem por $0.40, 10 segundos em 2K por $1.30 e 15 segundos em 2K por $1.95.

• As 5 primeiras imagens de entrada por tarefa são grátis (2 no Max), cada imagem extra custa $0.04 no H3 e a entrada de áudio é grátis. O vídeo de entrada é cobrado por segundo, e no Max um segundo de entrada ($0.143 em 768P) custa mais que um segundo de saída. Na mesma variante e resolução, os três tipos de tarefa custam o mesmo.
• O H3 é só por uso, e os pacotes de vídeo da MiniMax não o cobrem. Os números por segundo dos planos do aplicativo Hailuo AI são créditos do aplicativo, não preços de API (aplicativo).
• A plataforma chinesa da MiniMax tem uma tabela própria em yuans, então não converta uma na outra (preços da China, conferidos em 26 de outubro de 2026).
• Na OmniaKey, uma tarefa de vídeo é cobrada por segundo de saída na criação, e uma tarefa que falhou ou foi cancelada é reembolsada (visão geral de mídia).

A tarifa atual da OmniaKey está na página do modelo MiniMax H3; o formato da requisição está na documentação da API de vídeo.

Perguntas frequentes

A API Hailuo é grátis?

Na API própria da MiniMax, não: as páginas de preços, de início rápido e de FAQ não mostram teste grátis nem crédito para o H3 (conferidas em 26 de outubro de 2026). As únicas partes grátis são as 5 primeiras imagens de entrada por tarefa e a entrada de áudio (preços), e os créditos do aplicativo Hailuo AI não valem como créditos de API.

Qual é a diferença entre Hailuo 2.3 e MiniMax H3?

O Hailuo 2.3 roda na V1: 6 ou 10 segundos, até 1080P, cobrado por vídeo, com o preço de tabela da MiniMax em $0.28 por 6 segundos em 768P (preços, referência da V1). O H3 roda na V2: de 4 a 15 segundos, 768P ou 2K, cobrado por segundo e com som estéreo (referência de criação, página de modelos). A MiniMax ainda lista os dois (FAQ de modelos).

O que é o MiniMax H3 Max?

É um lançamento conjunto da MiniMax com a fal.ai, com pós-treino da fal.ai sobre o H3 para ganhar velocidade (guia de vídeo). Ele gera clipes em 480P ou 768P de 5 a 15 segundos, e extra.prompt_expansion_mode aceita disabled, balanced (o padrão) ou quality (referência de criação). As páginas da MiniMax divergem sobre referências: o guia de vídeo e a FAQ de modelos listam só texto para vídeo e imagem para vídeo, enquanto a referência de criação e a página de preços listam também referência para vídeo.

Dá para rodar o MiniMax H3 por conta própria?

Dá, fora de algumas regiões. Os pesos estão no Hugging Face (MiniMaxAI/MiniMax-H3) e no GitHub (MiniMax-AI/MiniMax-H3) sob a MiniMax H3 Community License Agreement, uma licença própria (Hugging Face, GitHub). Na revisão da licença conferida em 26 de agosto de 2026, Estados Unidos, União Europeia, Reino Unido e Coreia do Sul são territórios excluídos e precisam de uma licença separada (guia de implantação local).

Registro de atualizações

27 de outubro de 2026: primeira versão, com clipes feitos em 26 de outubro de 2026.