Como usar a API MiniMax H3 Max? Gerar vídeo a partir de texto ou imagem

No HiAPI, o MiniMax H3 Max aparece em dois nomes de modelo: texto para vídeo minimax-h3-max/text-to-video e imagem para vídeo minimax-h3-max/image-to-video, gerando vídeos de 0,92–15 segundos, 480P a $0,072 por segundo, 768P a $0,115 por segundo, 1080P a $0,229 por segundo, cobrado pelos segundos solicitados. Primeiro, use o prompt do barco de papel abaixo para gerar um curta-metragem horizontal de 5 segundos; o orçamento em 768P é de $0,575; ao integrar a API, envie uma tarefa e depois use o taskId retornado para obter o vídeo.

O MiniMax H3 Max já está disponível no HiAPI, gerar com este prompt →. O prompt é preenchido automaticamente; em seguida, selecione manualmente 5 segundos, 768P e 16:9.

Primeiro vídeo: o barco de papel após a chuva

After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.

gerar com este prompt →

Este prompt separa a ação do movimento de câmera: o barco de papel flutua com a água, uma câmera baixa acompanha suavemente e o som é indicado pelo canto distante dos pássaros. Ao substituir o barco de papel pelo seu próprio objeto, mantenha primeiro uma ação e um tipo de movimento de câmera; assim fica mais fácil ver o que precisa ser ajustado.

Teste online ou integração via API: como escolher?

Para ver o resultado primeiro, abra a página do modelo de texto para vídeo, copie o prompt, escolha a duração e a resolução e envie para gerar; se já tiver uma imagem inicial, vá para a página do modelo de imagem para vídeo e envie a imagem do primeiro frame. Para integrar em uma aplicação, primeiro obtenha a chave na página de API Key, crie a tarefa com uma requisição no servidor, salve o taskId e, após a tarefa ser concluída com sucesso, leia o endereço do vídeo.

Recomenda-se informar a resolução explicitamente: 5 segundos em 480P custa $0,36, em 768P custa $0,575 e em 1080P custa $1,145. Primeiro confirme o movimento em resolução mais baixa e depois escolha o nível conforme a necessidade de entrega; veja o orçamento completo na tabela de preços do H3 e H3 Max.

cURL: criar a tarefa e depois consultar o resultado

Após definir a API Key na variável de ambiente local HIAPI_API_KEY, execute esta requisição:

curl --fail-with-body --connect-timeout 10 --max-time 60 -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}'

Quando o POST expirar, a conexão for interrompida ou o conteúdo retornado não permitir confirmar a criação, o estado da submissão é desconhecido: consulte primeiro o registro da tarefa e não execute o POST novamente de imediato. Após confirmar que a resposta tem code=200, que data é um objeto e que data.taskId não está vazio, salve o ID e substitua YOUR_TASK_ID no endereço de consulta:

curl --fail-with-body --connect-timeout 10 --max-time 60 "https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Para tarefas em espera, continue consultando o mesmo ID. Quando data.status for success, leia o url do item de vídeo em data.output; quando for fail, verifique a mensagem de erro da tarefa; se houver erro de entrada ou de autenticação, corrija o problema correspondente primeiro e, se já tiver o ID da tarefa, continue consultando essa tarefa.

Python: enviar uma vez e aguardar a mesma tarefa

O exemplo abaixo usa a biblioteca padrão do Python. Faça o POST apenas uma vez e valide a resposta; se o resultado da submissão for desconhecido, pare e avise para consultar o registro da tarefa. Se a consulta falhar temporariamente, mantenha o ID da tarefa e continue o GET; 600 segundos é o limite de espera deste exemplo.

import json
import os
import time
import urllib.error
import urllib.request

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer " + os.environ["HIAPI_API_KEY"],
    "Content-Type": "application/json",
}


def request(method, url, body=None):
    data = json.dumps(body).encode() if body is not None else None
    req = urllib.request.Request(url, data=data, headers=HEADERS, method=method)
    with urllib.request.urlopen(req, timeout=30) as response:
        result = json.load(response)
    if not isinstance(result, dict) or result.get("code") != 200:
        raise ValueError(f"Unexpected API response: {result!r}")
    if not isinstance(result.get("data"), dict):
        raise ValueError("Missing data object")
    return result["data"]


payload = {
  "model": "minimax-h3-max/text-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "aspect_ratio": "16:9"
  }
}
try:
    created = request("POST", BASE, payload)
    task_id = created.get("taskId")
    if not isinstance(task_id, str) or not task_id.strip():
        raise ValueError("Missing taskId")
except (OSError, ValueError) as exc:
    raise SystemExit(
        f"Submission outcome is unconfirmed: {exc}. "
        "Check task history before another POST; do not blindly resubmit."
    )

print("taskId:", task_id, flush=True)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    try:
        task = request("GET", f"{BASE}/{task_id}")
    except urllib.error.HTTPError as exc:
        if exc.code in (400, 401, 403, 404):
            raise SystemExit(
                f"Query rejected ({exc.code}). Correct URL/auth, then GET existing task {task_id}."
            )
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    except (OSError, ValueError) as exc:
        print(f"Query error: {exc}; keep querying task {task_id}", flush=True)
        time.sleep(5)
        continue
    status = task.get("status")
    if status not in ("queued", "handling", "archiving", "success", "fail"):
        raise RuntimeError(f"Unexpected task status {status!r}; keep task ID {task_id}")
    if status == "success":
        output = task.get("output")
        if not isinstance(output, list):
            raise RuntimeError(f"Invalid output; keep task ID {task_id}")
        videos = [item["url"] for item in output
                  if isinstance(item, dict) and item.get("type") == "video"
                  and isinstance(item.get("url"), str) and item["url"]]
        if not videos:
            raise RuntimeError(f"No video URL; keep task ID {task_id}")
        print(videos[0])
        break
    if status == "fail":
        raise RuntimeError(f"Task {task_id} failed: {task!r}")
    time.sleep(5)
else:
    raise TimeoutError(f"Keep querying existing task {task_id}; do not POST again")

Usar uma imagem para controlar o primeiro ou o último frame

Para o vídeo começar a partir da imagem do seu produto, troque o nome do modelo para minimax-h3-max/image-to-video e adicione first_frame_image em input; para especificar o final, adicione last_frame_image. É possível enviar apenas o último frame ou enviar primeiro e último frames juntos; imagem para vídeo não tem o campo aspect_ratio, e a proporção segue a imagem.

Campo	Uso
prompt	Obrigatório, até 50000 caracteres, descreve ação, movimento de câmera e som
duration	0,92–15 segundos, pode ter casas decimais, padrão 5 segundos
resolution	480P, 768P ou 1080P, padrão 768P
aspect_ratio	Apenas em texto para vídeo: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, padrão 16:9
first_frame_image	Imagem para vídeo: URL público da imagem do primeiro frame
last_frame_image	Imagem para vídeo: URL público da imagem do último frame
target_audio_url	Opcional, substitui a faixa de áudio pela sua própria, com pelo menos 2 segundos
prompt_expansion_mode	Opcional, disabled / balanced (padrão) / quality

Abaixo está o corpo completo da requisição com primeiro e último frames; as URLs das imagens são placeholders para seus próprios endereços publicamente acessíveis; as imagens definem a composição inicial e final:

{
  "model": "minimax-h3-max/image-to-video",
  "input": {
    "prompt": "After a morning rain, a red paper boat drifts through shallow water beneath a stone bridge. A low camera tracks smoothly beside it, small ripples spread across the water, and birds sing softly in the distance. No text or subtitles.",
    "duration": 5,
    "resolution": "768P",
    "first_frame_image": "https://your-domain.com/images/paperboat-first.jpg",
    "last_frame_image": "https://your-domain.com/images/paperboat-last.jpg"
  }
}

Se precisar controlar apenas o último frame, remova first_frame_image e mantenha last_frame_image. Escreva no prompt apenas o movimento da câmera; a imagem define o objeto e a composição inicial. Para múltiplos planos, descreva cada corte no prompt; os campos da requisição continuam sendo os desta tabela, não adicione camera_angle, mode ou watermark.

Para um curta-metragem vertical, use diretamente em texto para vídeo "aspect_ratio": "9:16"; em imagem para vídeo, use uma imagem inicial vertical, e a proporção segue a imagem.

Ao integrar na aplicação, coloque o callback no nível superior da requisição

Adicione um callback opcional no nível superior da requisição de criação, em paralelo a model e input:

{
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}

Combine este bloco na requisição completa. O receptor deve deduplicar por taskId, tratar sucesso e falha separadamente e compensar notificações perdidas com a consulta de tarefas. Após obter o ID da tarefa, não envie novamente; em caso de erro HTTP, leia primeiro o conteúdo da resposta e distinga se é problema de autenticação ou de parâmetros.

Após a integração, verifique estes quatro itens

1. Salve o data.taskId não vazio e continue usando-o mesmo após falhas de consulta.
2. Confirme que o estado final é success ou fail, sem tratar o limite de espera como tempo de execução do modelo.
3. Em data.output de tarefas bem-sucedidas, procure a URL do vídeo por type=video.
4. Baixe o produto e verifique se o tamanho real, a duração e a imagem atendem aos requisitos de entrega.

Perguntas frequentes

O H3 Max pode usar vídeo ou áudio de referência? O H3 Max usa target_audio_url para substituir a faixa de áudio e não aceita vídeo de referência; quando precisar de referência multimodal com imagem, vídeo e áudio, escolha o MiniMax H3.

Em comparação com o H3, o Max é mais caro? O H3 2K custa $0,1189 por segundo, o Max 768P custa $0,115 por segundo e 1080P custa $0,229 por segundo. Escolha primeiro o modelo conforme a resolução e o material de referência necessários e depois calcule o orçamento pela duração.

Como começar um curta-metragem vertical? Em texto para vídeo, use "aspect_ratio": "9:16"; em imagem para vídeo, prepare uma imagem inicial vertical, e a proporção segue a imagem.

Copie o prompt do barco de papel, gere com este prompt → e crie primeiro um curta de 5 segundos. Para mais formas de descrever ações e movimentos de câmera, veja 4 vídeos reais e prompts completos; para os campos completos, veja a documentação de parâmetros de texto para vídeo e a documentação de parâmetros de imagem para vídeo.