Integración de la API de MiniMax Hailuo 2.3: generar movimiento humano complejo en vídeo con IA
Modelo objetivo:
MiniMax-Hailuo-2.3
Endpoint de inferencia:https://api.toapis.com/v1/videos/generations
Relacionado: Guía de la API de MiniMax H3 · Prompts de movimiento de cámara de H3 · Pipeline R2V automatizado
1. Resumen y panorama del rendimiento
- Trabajo: enviar trabajos de texto a vídeo o de imagen a vídeo con primer fotograma para clips de personajes y de movimiento humano al endpoint de generaciones de ToAPIs.
- Contrato:
MiniMax-Hailuo-2.3acepta duraciones enteras de 6 o 10 segundos y resoluciones768Po1080P.1080Psolo admite 6 segundos. La referencia actual de la API limita el prompt a 2.000 caracteres. - ID: usa la cadena del catálogo
MiniMax-Hailuo-2.3(texto a vídeo e imagen a vídeo).MiniMax-Hailuo-2.3-Fastes solo imagen a vídeo y exige una URL de primer fotograma. Ninguno de los dos ID es intercambiable conminimax-h3. - Lenguaje de cámara: la referencia de Hailuo 2.3 de ToAPIs documenta directivas entre corchetes como
[Push in]y[Pan left, Pedestal up]. Trata la tabla de abajo como el vocabulario documentado actual y confírmalo con la documentación vigente antes de fijar por código una gramática de planos. - Protocolo: REST con Bearer. Guarda el
idde la tarea del formato de respuesta y consultaGET /v1/videos/generations/{task_id}(oGET /v1/tasks/{task_id}) con un plazo acotado. Un tiempo de espera agotado en el cliente no demuestra que la tarea upstream haya fallado.
2. Patrones de prompt para movimiento humano
El catálogo público de ToAPIs describe MiniMax Hailuo 2.3 como un modelo de vídeo para movimiento de personajes, expresiones y estilo en historias expresivas y clips de personajes. Ese es posicionamiento de producto, no una comparativa independiente de «cero deformación de extremidades». Para trabajo de producción, escribe prompts que describan un sujeto y una acción principal con lenguaje mecánico claro y luego revisa la toma.
Un prompt útil de movimiento humano nombra la mecánica corporal antes de añadir estilo: quién se mueve, qué extremidad lidera, cómo se desplaza el peso y cómo empieza y termina la acción. Mantén ese núcleo estable cuando hagas pruebas A/B de duración o de resolución; de lo contrario, un cambio de redacción puede explicar una toma distinta.
La referencia de la API de Hailuo 2.3 de ToAPIs documenta las directivas de cámara de abajo. Van dentro de la cadena del prompt, no en un campo de la solicitud aparte. El contrato de solicitud del frontend sigue validando prompt como texto. Combina como máximo tres directivas en un mismo corchete para movimiento simultáneo, o secuéncialas en la frase para movimientos ordenados.
| Categoría | Directivas documentadas |
|---|---|
| Paneo | [Pan left], [Pan right] |
| Inclinación | [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] |
| Otros | [Shake], [Tracking shot], [Static shot] |

Figura 1: trata una pose fija como entrada de primer fotograma, describe la acción posterior en el prompt y envía una sola solicitud de generación a través de la pasarela de ToAPIs.
Una plantilla compacta que sigue siendo comprobable:
SUBJECT and PRIMARY ACTION (lead limb, weight shift, follow-through), ENVIRONMENT, [CAMERA], STYLE NOTES
Ejemplo: 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 imagen a vídeo, envía una URL de primer fotograma accesible públicamente en image_urls. La imagen es el fotograma inicial; el prompt describe el movimiento que sigue. Los límites de imagen documentados actualmente son JPG, JPEG, PNG o WebP; menos de 20 MB; lado corto mayor de 300 px; y una relación de aspecto entre 2:5 y 5:2. No pongas base64 en image_urls: sube primero un archivo local.
MiniMax-Hailuo-2.3-Fast no acepta texto a vídeo: se exige una URL de primer fotograma. Hailuo 2.3 no documenta un campo de último fotograma; la interpolación de primer a último fotograma corresponde a MiniMax-Hailuo-02, no a este ID. No copies campos de H3 como ratio o reference_videos en una solicitud de Hailuo 2.3.
Las etiquetas de las opciones del Playground pueden mostrar 768p / 1080p en minúsculas. Los ejemplos actuales de la API usan 768P y 1080P. Confirma el valor que acepta tu cuenta antes de automatizar un lote. La misma redacción de cámara se puede reutilizar cuando pases un plano a MiniMax H3, pero los contratos de duración, resolución y modo de medios son diferentes: cambia de ID solo después de releer esa guía.
3. Implementación en producción: cURL y Python
Paso 1: envío con 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"
}'
Paso 2: ayuda y sondeo en Python
La documentación oficial registra actualmente el origen público https://toapis.com (y https://toapis.cn para China continental). Otras guías de ToAPIs de esta serie usan https://api.toapis.com. Elige una URL base y mantenla coherente. El fragmento de abajo sigue la ruta de estado de tarea documentada y los estados completed / failed; confirma id, result.data[0].url y el formato de respuesta con la referencia de la API de tu cuenta 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))
Guarda la versión de la plantilla de prompt junto al registro de la tarea para poder distinguir un cambio de modelo de un cambio de redacción. Si necesitas un trabajo con primer fotograma, pasa image_url= a dispatch_motion_clip. Para la SKU Fast, ese argumento es obligatorio.
La duración de Hailuo 2.3 base es de 6 o 10 segundos. No envíes 1080P con duration: 10. Si necesitas clips continuos de 4 a 15 segundos, material de referencia o entradas de último fotograma, ese es otro contrato: consulta la guía de la API de H3 y el tutorial del pipeline R2V.
4. Gestión de errores y matriz de estados
Las categorías de abajo son puntos de partida para el diagnóstico, no una garantía de los códigos de error exactos de ToAPIs. Una consulta HTTP correcta sigue exigiendo leer el status de la tarea.
| Estado HTTP | Categoría habitual | Acción recomendada |
|---|---|---|
400 | Campo inválido, combinación no admitida o conflicto de modo de medios | Revisa el ID de modelo exacto, que la duración sea 6 o 10, que 1080P se combine solo con 6 segundos y que los trabajos Fast incluyan image_urls. No envíes un campo de último fotograma en Hailuo 2.3 |
401 | Clave de API ausente o inválida | Rota la clave en el panel de ToAPIs y confirma la cabecera Authorization |
429 | Límite de frecuencia o de concurrencia | Respeta Retry-After cuando esté presente; retrocede con fluctuación aleatoria; reintenta solo cuando sea seguro |
5xx o tiempo de espera agotado en la red | Problema temporal de la pasarela o del upstream | Comprueba el estado de la tarea antes de reenviar; usa una política de reintentos acotada |
5. Precios y retorno de FinOps
- No reutilices precios unitarios de borradores de planificación. Las tarifas por segundo o por vídeo, las unidades de facturación y el tratamiento de tareas fallidas varían según el modelo, la resolución, la duración, la ruta y la cuenta. Las filas de referencia oficiales del proveedor en la página de precios de ToAPIs son solo informativas y pueden no coincidir con lo que se factura a tu cuenta. Lee el catálogo actual y la cotización de tu cuenta antes de prever una lista de planos.
- Fast es una SKU distinta, no un interruptor de velocidad gratuito sobre el mismo ID.
MiniMax-Hailuo-2.3-Fastestá documentado solo como imagen a vídeo. Confirma su precio actual de cuenta por separado. - Controla el gasto en la capa de prompt: haz borradores en
768Py 6 segundos, mantén una plantilla versionada, cambia una variable cada vez y no reenvíes tras un tiempo de espera agotado del cliente hasta comprobar el estado de la tarea. - Los contratos oficiales de los proveedores suelen añadir compromisos anuales, cuotas por usuario y mínimos de prepago. La facturación de ToAPIs suele ser pago por uso: confirma las condiciones activas de tu cuenta.
6. Preguntas frecuentes
Consulta el bloque de preguntas frecuentes del frontmatter. En resumen: la cadena de modelo de la solicitud es MiniMax-Hailuo-2.3, no un slug con guiones ni un ID de H3; 1080P se limita a 6 segundos; Fast exige una URL de primer fotograma y no admite texto a vídeo; las directivas de cámara documentadas van en el prompt, no como campos separados; Hailuo 2.3 no tiene entrada de último fotograma.
7. Lista de acciones
- Crea una clave en el Portal de desarrolladores de ToAPIs.
- Haz una prueba rápida del fragmento de cURL con
MiniMax-Hailuo-2.3,resolution: "768P"y una duración de 6 segundos. - Confirma si tu cuenta espera
768Po768p, y consultaGET /v1/videos/generations/{id}con un plazo acotado. - Siguiente paso: la guía de movimiento de cámara de H3 si necesitas otra duración u otro contrato de medios, y la guía del modelo Hailuo 2.3 para el estado del catálogo en vivo.







