Guia da API Hailuo 2.3: texto para vídeo, imagem para vídeo e versão Fast

TL;DR

• O Hailuo 2.3 é o modelo de vídeo da MiniMax. No HiAPI ele tem três endpoints: hailuo-2.3/text-to-video, hailuo-2.3/image-to-video e o mais barato hailuo-2.3-fast/image-to-video.
• Ele cobra por vídeo, não por segundo: vídeo de 6 segundos por $0.40, vídeo de 10 segundos por $0.80. O Fast imagem para vídeo custa $0.27 e $0.46.
• Os parâmetros de entrada são poucos: prompt, duration (string "6" ou "10"), prompt_optimizer, e no imagem para vídeo mais um image_url. Não há parâmetros de resolução, proporção ou seed. Abra a página do modelo de texto para vídeo para experimentar; novas contas ganham 200 créditos gratuitos.

Qual endpoint usar

	Texto para vídeo	Imagem para vídeo	Fast imagem para vídeo
ID do modelo	hailuo-2.3/text-to-video	hailuo-2.3/image-to-video	hailuo-2.3-fast/image-to-video
Parâmetros obrigatórios	prompt	prompt + image_url	prompt + image_url
Vídeo de 6 segundos	$0.40	$0.40	$0.27
Vídeo de 10 segundos	$0.80	$0.80	$0.46
Entrada de imagem	Nenhuma	Um primeiro frame	Um primeiro frame

Preços do HiAPI em tempo real, verificados em 20 de outubro de 2026. Tarefas com falha não são cobradas.

Ao explorar uma cena, comece pelo texto; quando o primeiro frame precisa ser exato (por exemplo, um produto ou personagem já existente), comece pela imagem. No cenário imagem para vídeo, o Fast custa um terço menos com a mesma entrada, então você pode rascunhar com o Fast e mudar para o modelo padrão quando uma cena precisar de mais detalhes de movimento.

Texto para vídeo: saída real

Este é o exemplo da página do modelo, com duração de 6 segundos:

a kung fu master practicing forms in heavy rain, water droplets scattering in slow motion, smooth natural motion, stable cinematic camera movement, consistent lighting across frames, cinematic composition, dramatic directional lighting, rich cohesive color grade, ultra-detailed, premium commercial finish

Gerar com este prompt →

hailuo-2.3/text-to-video, 6 segundos, 1366×768, sem áudio, $0.40.

Ao longo dos seis segundos, o mestre executa várias posturas e golpes de braço em sequência, enquanto a chuva continua caindo ao fundo. A câmera permanece estável. Embora a requisição não tenha um campo de proporção, a saída é paisagem; texto para vídeo não permite especificar retrato.

Imagem para vídeo: saída real

O imagem para vídeo preserva a sua imagem e a anima. Os dois exemplos abaixo usam um primeiro frame 16:9, e o resultado retorna em 1364×768.

Primeiro frame:

steam bursts from the locomotive as it slowly starts moving, wheels turning, smooth natural motion, stable cinematic camera movement, consistent lighting across frames, cinematic composition, dramatic directional lighting, rich cohesive color grade, ultra-detailed, premium commercial finish

Gerar com este prompt →

hailuo-2.3/image-to-video, 6 segundos, 1364×768, sem áudio, $0.40.

A estação, os vagões e o pôr do sol permanecem consistentes com a imagem. A locomotiva avança e o vapor se espalha baixo pela plataforma.

A mesma ideia com o Fast, numa cena mais silenciosa:

boats rocking gently, seagulls gliding through the morning mist, smooth natural motion, stable cinematic camera movement, consistent lighting across frames, cinematic composition, dramatic directional lighting, rich cohesive color grade, ultra-detailed, premium commercial finish

Gerar com este prompt →

hailuo-2.3-fast/image-to-video, 6 segundos, 1364×768, sem áudio, $0.27.

O movimento é sutil: os barcos balançam levemente, a névoa se desloca devagar e, perto do final, aparece uma gaivota. Para planos silenciosos e atmosféricos como este, o Fast é suficiente.

Os prompts de imagem para vídeo devem descrever o que acontece em seguida. O modelo já viu a imagem, então "uma locomotiva preta parada na estação" não acrescenta nada; "vapor jorra quando ela começa a se mover" é o que diz a ele o que fazer.

curl

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3/text-to-video",
    "input": {
      "prompt": "A glass of iced tea tips over in slow motion, tea splashing across a wooden table, ice cubes tumbling, macro shot",
      "duration": "6",
      "prompt_optimizer": true
    }
  }'

Você recebe um taskId. Faça polling em GET https://api.hiapi.ai/v1/tasks/{taskId} até que data.status seja success, e então baixe data.output[0].url. Os vídeos levam minutos, não segundos.

Para imagem para vídeo, troque o modelo e adicione uma imagem:

{
  "model": "hailuo-2.3-fast/image-to-video",
  "input": {
    "prompt": "The cat stretches, hops off the windowsill and walks toward the camera",
    "image_url": "https://your-cdn.example.com/first-frame.jpg",
    "duration": "6"
  }
}

Python: enviar, consultar, baixar

# pip install requests; export HIAPI_KEY=your-key first
import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def generate(model, timeout_s=900, **inp):
    r = requests.post(API, json={"model": model, "input": inp}, headers=H, timeout=30).json()
    if r.get("code") != 200:
        raise RuntimeError(r)  # a 400 lists every invalid field at once
    task_id = r["data"]["taskId"]  # save this; if your script dies, poll it again instead of resubmitting
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(10)
    raise TimeoutError(task_id)

url = generate("hailuo-2.3/image-to-video",
               prompt="Steam bursts from the locomotive as it slowly starts moving, wheels turning",
               image_url="https://your-cdn.example.com/train.jpg",
               duration="10")  # a string, not 10

with open("hailuo.mp4", "wb") as f:
    f.write(requests.get(url, timeout=120).content)

O link de saída expira cerca de 7 dias após a conclusão da tarefa, então salve o arquivo, não apenas o link.

Parâmetros

Campo	Obrigatório	Valores	Descrição
prompt	Sim	Texto	Descreve o movimento e o movimento de câmera
image_url	Somente imagem para vídeo	Uma URL pública	Uma única string, não um array. jpeg, png ou webp
duration	Não	"6" (padrão) ou "10"	Deve ser uma string
prompt_optimizer	Não	true (padrão) / false	Expande prompts curtos antes da geração

O movimento e o movimento de câmera ficam no prompt. Não há campos motion_strength, camera_movement, resolution, aspect_ratio ou seed.

Erros que você vai encontrar

Esses erros são retornados no envio como HTTP 400, portanto nenhuma tarefa é criada e não há cobrança:

• duration: got number, want string: você enviou 6. Envie "6".
• duration: value must be one of '6', '10': há apenas duas durações.
• image_url: missing required field "image_url": imagem para vídeo precisa de um primeiro frame. O nome do campo é image_url, no singular.
• additional properties 'resolution' not allowed (ou aspect_ratio, image_urls, seed): remova o campo.

Se a tarefa terminar em fail, leia data.error. No cenário imagem para vídeo, a causa comum é o servidor não conseguir buscar a URL da imagem, por exemplo um bucket privado ou um link assinado expirado.

Perguntas frequentes

Quanto custa o Hailuo 2.3 por segundo?

Ele não cobra por segundo. Você paga por vídeo: $0.40 por 6 segundos e $0.80 por 10 segundos no modelo padrão; $0.27 e $0.46 no Fast. Convertendo, um vídeo de 6 segundos do modelo padrão custa cerca de $0.067 por segundo, e o Fast cerca de $0.045 por segundo.

Posso gerar vídeos em retrato?

No texto para vídeo, não: ele não tem campo de proporção e retorna paisagem. O imagem para vídeo também não tem campo de proporção; a documentação não afirma se um primeiro frame em retrato produz um vídeo em retrato, então antes de construir algo com base nisso, teste um vídeo Fast de 6 segundos por $0.27.

Devo desativar o prompt_optimizer?

Mantenha ativado para prompts curtos. Desative quando você escreveu a formulação com cuidado e quer que o modelo a siga estritamente.

Há áudio?

Os três vídeos de exemplo acima não têm faixa de áudio, e não há campo para ativar som.

O Fast é pior?

A entrada é a mesma e o preço é um terço menor. No exemplo dos barcos acima, o movimento é suave e limpo. Para planos com muita ação rápida, gere um rascunho de 6 segundos nos dois modelos para comparar e depois renderize a versão de 10 segundos.

Mais comparações entre modelos de vídeo: As APIs de imagem e vídeo mais baratas no HiAPI. Para testar o Hailuo sem código, abra a página do modelo de imagem para vídeo.