Integração da API MiniMax Hailuo 2.3: gerar movimento humano complexo em vídeo com IA
Modelo alvo:
MiniMax-Hailuo-2.3
Endpoint de inferência:https://api.toapis.com/v1/videos/generations
Relacionado: Guia da API MiniMax H3 · Prompts de movimento de câmera do H3 · Pipeline R2V automatizado
1. Resumo e visão geral de desempenho
- Trabalho: enviar tarefas de texto para vídeo ou de imagem para vídeo com primeiro quadro para clipes de personagens e de movimento humano ao endpoint de gerações da ToAPIs.
- Contrato:
MiniMax-Hailuo-2.3aceita durações inteiras de 6 ou 10 segundos e resoluções768Pou1080P.1080Paceita apenas 6 segundos. A referência atual da API limita o prompt a 2.000 caracteres. - IDs: use a string do catálogo
MiniMax-Hailuo-2.3(texto para vídeo e imagem para vídeo).MiniMax-Hailuo-2.3-Fasté apenas imagem para vídeo e exige uma URL de primeiro quadro. Nenhum dos dois IDs é intercambiável comminimax-h3. - Linguagem de câmera: a referência do Hailuo 2.3 da ToAPIs documenta diretivas entre colchetes como
[Push in]e[Pan left, Pedestal up]. Trate a tabela abaixo como o vocabulário documentado atual e confirme com a documentação vigente antes de fixar em código uma gramática de planos. - Protocolo: REST com Bearer. Guarde o
idda tarefa do envelope de resposta e consulteGET /v1/videos/generations/{task_id}(ouGET /v1/tasks/{task_id}) com um prazo limitado. Um tempo esgotado no cliente não prova que a tarefa upstream falhou.
2. Padrões de prompt para movimento humano
O catálogo público da ToAPIs descreve o MiniMax Hailuo 2.3 como um modelo de vídeo para movimento de personagens, expressões e estilo em histórias expressivas e clipes de personagens. Isso é posicionamento de produto, não um benchmark independente de “zero distorção de membros”. Para trabalho de produção, escreva prompts que descrevam um sujeito e uma ação principal com linguagem mecânica clara e depois revise a tomada.
Um prompt útil de movimento humano nomeia a mecânica corporal antes de acrescentar estilo: quem se move, qual membro lidera, como o peso se desloca e como a ação começa e termina. Mantenha esse núcleo estável quando fizer testes A/B de duração ou de resolução; caso contrário, uma mudança de redação pode explicar uma tomada diferente.
A referência da API do Hailuo 2.3 da ToAPIs documenta as diretivas de câmera abaixo. Elas ficam dentro da string do prompt, não em um campo separado da requisição. O contrato de requisição do frontend continua validando prompt como texto. Combine no máximo três diretivas em um mesmo colchete para movimento simultâneo, ou coloque-as em sequência na frase para movimentos ordenados.
| Categoria | Diretivas documentadas |
|---|---|
| Pan | [Pan left], [Pan right] |
| Tilt | [Tilt up], [Tilt down] |
| Push / Pull | [Push in], [Pull out] |
| Pedestal | [Pedestal up], [Pedestal down] |
| Truck | [Truck left], [Truck right] |
| Zoom | [Zoom in], [Zoom out] |
| Outros | [Shake], [Tracking shot], [Static shot] |

Figura 1: trate uma pose estática como entrada de primeiro quadro, descreva a ação seguinte no prompt e envie uma única requisição de geração pelo gateway da ToAPIs.
Um modelo compacto que continua testável:
SUBJECT and PRIMARY ACTION (lead limb, weight shift, follow-through), ENVIRONMENT, [CAMERA], STYLE NOTES
Exemplo: A contemporary dancer in a black practice leotard plants the left foot, then uncoils a slow 360-degree turn with the right arm leading and the torso stacked over the standing leg, warehouse skylight, [Tracking shot], photorealistic, no morphing limbs.
Para imagem para vídeo, envie uma URL de primeiro quadro acessível publicamente em image_urls. A imagem é o quadro inicial; o prompt descreve o movimento que vem depois. Os limites de imagem documentados atualmente são JPG, JPEG, PNG ou WebP; menos de 20 MB; lado curto maior que 300 px; e proporção entre 2:5 e 5:2. Não coloque base64 em image_urls: envie primeiro um arquivo local.
MiniMax-Hailuo-2.3-Fast não aceita texto para vídeo: é exigida uma URL de primeiro quadro. O Hailuo 2.3 não documenta um campo de último quadro; a interpolação de primeiro para último quadro pertence ao MiniMax-Hailuo-02, não a este ID. Não copie campos do H3 como ratio ou reference_videos para uma requisição do Hailuo 2.3.
Os rótulos das opções do Playground podem mostrar 768p / 1080p em minúsculas. Os exemplos atuais da API usam 768P e 1080P. Confirme o valor que a sua conta aceita antes de automatizar um lote. A mesma redação de câmera pode ser reutilizada quando você levar um plano para o MiniMax H3, mas os contratos de duração, resolução e modo de mídia são diferentes: troque de ID só depois de reler esse guia.
3. Implementação em produção: cURL e Python
Passo 1: envio com cURL
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MiniMax-Hailuo-2.3",
"prompt": "A contemporary dancer in a black practice leotard plants the left foot, then uncoils a slow 360-degree turn with the right arm leading and the torso stacked over the standing leg, warehouse skylight, [Tracking shot], photorealistic, no morphing limbs",
"duration": 6,
"resolution": "768P"
}'
Passo 2: auxílio e sondagem em Python
A documentação oficial registra atualmente a origem pública https://toapis.com (e https://toapis.cn para a China continental). Outros guias da ToAPIs nesta série usam https://api.toapis.com. Escolha uma URL base e mantenha a coerência. O trecho abaixo segue o caminho de status de tarefa documentado e os estados completed / failed; confirme id, result.data[0].url e o envelope com a referência da API da sua conta antes de publicar.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_motion_clip(
prompt: str,
duration: int = 6,
resolution: str = "768P",
image_url: str | None = None,
model: str = "MiniMax-Hailuo-2.3",
) -> str:
if resolution == "1080P" and duration != 6:
raise ValueError("1080P currently supports a 6-second duration only")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"metadata": {"prompt_optimizer": True, "aigc_watermark": False},
}
if image_url:
payload["image_urls"] = [image_url]
elif model == "MiniMax-Hailuo-2.3-Fast":
raise ValueError("MiniMax-Hailuo-2.3-Fast requires a first-frame image_urls value")
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 300) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 5.0
start = time.time()
while time.time() - start < deadline_s:
time.sleep(interval)
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 30))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
interval = min(interval * 1.5, 10.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
prompt = (
"A contemporary dancer in a black practice leotard plants the left foot, "
"then uncoils a slow 360-degree turn with the right arm leading and the "
"torso stacked over the standing leg, warehouse skylight, [Tracking shot], "
"photorealistic, no morphing limbs"
)
task_id = dispatch_motion_clip(prompt)
print("Task:", task_id)
print("Video:", poll_task(task_id))
Guarde a versão do modelo de prompt junto ao registro da tarefa para poder distinguir uma mudança de modelo de uma mudança de redação. Se você precisa de uma tarefa com primeiro quadro, passe image_url= para dispatch_motion_clip. Para a SKU Fast, esse argumento é obrigatório.
A duração do Hailuo 2.3 base é de 6 ou 10 segundos. Não envie 1080P com duration: 10. Se você precisa de clipes contínuos de 4 a 15 segundos, mídia de referência ou entradas de último quadro, esse é outro contrato: consulte o guia da API do H3 e o tutorial do pipeline R2V.
4. Tratamento de erros e matriz de status
As categorias abaixo são pontos de partida para diagnóstico, não uma garantia dos códigos de erro exatos da ToAPIs. Uma consulta HTTP bem-sucedida ainda exige ler o status da tarefa.
| Status HTTP | Categoria comum | Ação recomendada |
|---|---|---|
400 | Campo inválido, combinação não aceita ou conflito de modo de mídia | Verifique o ID de modelo exato, se a duração é 6 ou 10, se 1080P está combinado apenas com 6 segundos e se tarefas Fast incluem image_urls. Não envie um campo de último quadro no Hailuo 2.3 |
401 | Chave de API ausente ou inválida | Rotacione a chave no painel da ToAPIs e confirme o cabeçalho Authorization |
429 | Limite de taxa ou de concorrência | Respeite Retry-After quando presente; recue com variação aleatória; 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 |
5. Preços e retorno de FinOps
- Não reutilize preços unitários de rascunhos de planejamento. Tarifas por segundo ou por vídeo, unidades de cobrança e tratamento de tarefas com falha variam por modelo, resolução, duração, rota e conta. As linhas de referência oficiais do fornecedor na página de preços da ToAPIs são apenas informativas e podem não corresponder ao que é cobrado da sua conta. Leia o catálogo atual e a cotação da sua conta antes de prever uma lista de planos.
- Fast é uma SKU diferente, não um interruptor de velocidade gratuito sobre o mesmo ID.
MiniMax-Hailuo-2.3-Fastestá documentado apenas como imagem para vídeo. Confirme o preço atual da conta separadamente. - Controle o gasto na camada de prompt: faça rascunhos em
768Pe 6 segundos, mantenha um modelo versionado, mude uma variável por vez e não reenvie depois de um tempo esgotado no cliente até verificar o status da tarefa. - Contratos oficiais de fornecedores normalmente acrescentam compromissos anuais, cotas por usuário e mínimos de pré-pagamento. A cobrança da ToAPIs costuma ser pagamento conforme o uso: confirme os termos ativos da sua conta.
6. Perguntas frequentes
Consulte o bloco de perguntas frequentes do frontmatter. Em resumo: a string de modelo da requisição é MiniMax-Hailuo-2.3, não um slug com hífens nem um ID do H3; 1080P é limitado a 6 segundos; Fast exige uma URL de primeiro quadro e não aceita texto para vídeo; as diretivas de câmera documentadas ficam no prompt, não em campos separados; o Hailuo 2.3 não tem entrada de último quadro.
7. Checklist de ações
- Crie uma chave no Portal de desenvolvedores da ToAPIs.
- Faça um teste rápido do trecho cURL com
MiniMax-Hailuo-2.3,resolution: "768P"e duração de 6 segundos. - Confirme se a sua conta espera
768Pou768pe consulteGET /v1/videos/generations/{id}com um prazo limitado. - Próximo passo: o guia de movimento de câmera do H3 se você precisar de outra duração ou de outro contrato de mídia, e o guia do modelo Hailuo 2.3 para o estado do catálogo em produção.







