Guía de la API de Hailuo 2.3: texto a vídeo, imagen a vídeo y versión Fast

TL;DR

• Hailuo 2.3 es el modelo de vídeo de MiniMax. En HiAPI tiene tres endpoints: hailuo-2.3/text-to-video, hailuo-2.3/image-to-video y el más económico hailuo-2.3-fast/image-to-video.
• Se cobra por vídeo, no por segundo: un vídeo de 6 segundos cuesta $0.40 y uno de 10 segundos, $0.80. En Fast imagen a vídeo son $0.27 y $0.46.
• Los parámetros de entrada son pocos: prompt, duration (la cadena "6" o "10"), prompt_optimizer y, en imagen a vídeo, además un image_url. No hay parámetros de resolución, relación de aspecto ni seed. Abre la página del modelo de texto a vídeo para probarlo; las cuentas nuevas reciben 200 créditos gratis.

Qué endpoint usar

	Texto a vídeo	Imagen a vídeo	Fast imagen a vídeo
ID del modelo	hailuo-2.3/text-to-video	hailuo-2.3/image-to-video	hailuo-2.3-fast/image-to-video
Parámetros obligatorios	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 imagen	Ninguna	Un primer fotograma	Un primer fotograma

Precios en tiempo real de HiAPI, verificados el 20 de octubre de 2026. Las tareas fallidas no se cobran.

Para explorar una escena, empieza por texto; cuando el primer fotograma deba ser exacto (por ejemplo, un producto o un personaje ya existentes), empieza por imagen. En los casos de imagen a vídeo, Fast cuesta un tercio menos y la entrada es la misma, así que puedes hacer un borrador con Fast primero y cambiar al modelo estándar cuando una toma concreta necesite más detalle de movimiento.

Texto a vídeo: salida real

Este es el ejemplo de la página del modelo, con una duración de 6 segundos:

un maestro de kung fu practicando formas bajo una lluvia intensa, gotas de agua dispersándose a cámara lenta, movimiento fluido y natural, movimiento de cámara cinematográfico estable, iluminación coherente entre fotogramas, composición cinematográfica, iluminación direccional dramática, etalonaje de color rico y cohesivo, ultradetallado, acabado comercial de primera calidad

Generar con este prompt →

hailuo-2.3/text-to-video, 6 segundos, 1366×768, sin audio, $0.40.

Durante los seis segundos, el maestro encadena varias posturas y golpes con los brazos mientras la lluvia sigue cayendo al fondo. La cámara se mantiene estable. Aunque la solicitud no incluye un campo de relación de aspecto, la salida es horizontal; texto a vídeo no permite especificar vertical.

Imagen a vídeo: salida real

Imagen a vídeo conserva tu imagen y la anima. Los dos ejemplos siguientes usan un primer fotograma en 16:9 y devuelven un resultado de 1364×768.

Primer fotograma:

vapor brotando de la locomotora mientras empieza a moverse lentamente, ruedas girando, movimiento fluido y natural, movimiento de cámara cinematográfico estable, iluminación coherente entre fotogramas, composición cinematográfica, iluminación direccional dramática, etalonaje de color rico y cohesivo, ultradetallado, acabado comercial de primera calidad

Generar con este prompt →

hailuo-2.3/image-to-video, 6 segundos, 1364×768, sin audio, $0.40.

La estación, los vagones y el atardecer se mantienen igual que en la imagen. La locomotora avanza y el vapor se extiende a baja altura por el andén.

La misma idea con Fast, en una escena más tranquila:

barcas meciéndose suavemente, gaviotas planeando entre la niebla matinal, movimiento fluido y natural, movimiento de cámara cinematográfico estable, iluminación coherente entre fotogramas, composición cinematográfica, iluminación direccional dramática, etalonaje de color rico y cohesivo, ultradetallado, acabado comercial de primera calidad

Generar con este prompt →

hailuo-2.3-fast/image-to-video, 6 segundos, 1364×768, sin audio, $0.27.

El movimiento es muy leve: las barcas se mecen despacio, la niebla se desplaza lentamente y hacia el final aparece una gaviota. Para una toma tan tranquila y atmosférica, Fast es suficiente.

Los prompts de imagen a vídeo deben describir lo que ocurre a continuación. El modelo ya ha visto la imagen, así que «una locomotora negra detenida en la estación» no aporta nada; «el vapor brota cuando empieza a moverse» es lo que le indica qué debe hacer.

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": "Un vaso de té helado se vuelca a cámara lenta, el té salpicando sobre una mesa de madera, cubitos de hielo rodando, plano macro",
      "duration": "6",
      "prompt_optimizer": true
    }
  }'

Obtendrás un taskId. Consulta GET https://api.hiapi.ai/v1/tasks/{taskId} hasta que data.status sea success y luego descarga data.output[0].url. Los vídeos tardan minutos, no segundos.

Para imagen a vídeo, cambia el modelo y añade una imagen:

{
  "model": "hailuo-2.3-fast/image-to-video",
  "input": {
    "prompt": "El gato se estira, salta del alféizar y camina hacia la cámara",
    "image_url": "https://your-cdn.example.com/first-frame.jpg",
    "duration": "6"
  }
}

Python: enviar, consultar y descargar

# 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="El vapor brota de la locomotora mientras empieza a moverse lentamente, las ruedas girando",
               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)

Los enlaces de salida caducan unos 7 días después de que finalice la tarea, así que guarda el archivo, no solo el enlace.

Parámetros

Campo	Obligatorio	Valores	Descripción
prompt	Sí	Texto	Describe el movimiento y el movimiento de cámara
image_url	Solo imagen a vídeo	Una URL pública	Una sola cadena, no un array. jpeg, png o webp
duration	No	"6" (predeterminado) o "10"	Debe ser una cadena
prompt_optimizer	No	true (predeterminado) / false	Amplía los prompts cortos antes de generar

El movimiento y el movimiento de cámara se escriben en el prompt. No hay campos motion_strength, camera_movement, resolution, aspect_ratio ni seed.

Errores que encontrarás

Estos errores se devuelven como HTTP 400 en el momento del envío, así que no se crea ninguna tarea ni se genera ningún cobro:

• duration: got number, want string: enviaste 6. Envía "6".
• duration: value must be one of '6', '10': solo hay dos duraciones.
• image_url: missing required field "image_url": imagen a vídeo necesita un primer fotograma. El nombre del campo es image_url, en singular.
• additional properties 'resolution' not allowed (o aspect_ratio, image_urls, seed): elimina ese campo.

Si la tarea termina en fail, lee data.error. En los casos de imagen a vídeo, la causa habitual es que el servidor no puede obtener la URL de la imagen, por ejemplo un bucket privado o un enlace firmado caducado.

Preguntas frecuentes

¿Cuánto cuesta Hailuo 2.3 por segundo?

No se cobra por segundo. Pagas por vídeo: en el modelo estándar, $0.40 por 6 segundos y $0.80 por 10 segundos; en Fast, $0.27 y $0.46. Eso equivale a unos $0.067 por segundo en un vídeo estándar de 6 segundos y unos $0.045 por segundo en Fast.

¿Puedo generar vídeo vertical?

Con texto a vídeo no: no tiene campo de relación de aspecto y devuelve horizontal. Imagen a vídeo tampoco tiene campo de relación de aspecto; la documentación no indica si un primer fotograma vertical produce un vídeo vertical, así que antes de basar un desarrollo en ello, prueba un vídeo Fast de 6 segundos por $0.27.

¿Debería desactivar prompt_optimizer?

Con prompts cortos, déjalo activado. Desactívalo cuando hayas redactado la formulación con cuidado y quieras que el modelo la siga al pie de la letra.

¿Tiene sonido?

Ninguno de los tres vídeos de ejemplo anteriores tiene pista de audio, y tampoco hay ningún campo para activar el sonido.

¿Fast es peor?

Su entrada es la misma y cuesta un tercio menos. En el ejemplo de las barcas de arriba, el movimiento es suave y limpio. Para tomas con mucho movimiento rápido, genera primero un borrador de 6 segundos con cada uno de los dos modelos para compararlos y luego renderiza la versión de 10 segundos.

Para más comparativas de modelos de vídeo: las API de imagen y vídeo más económicas de HiAPI. Si quieres probar Hailuo sin escribir código, abre la página del modelo de imagen a vídeo.