¿Cómo usar la API de Ray 3.2? Consigue tu primer video en 5 minutos

TL;DR

• Qué es: Ray 3.2 de Luma AI, disponible en HiAPI en dos rutas: ray-3.2/text-to-video solo recibe un prompt, y ray-3.2/image-to-video se impulsa con un primer fotograma (y opcionalmente un último fotograma). Ya está disponible en HiAPI; abre la página del modelo de texto a video y podrás generar; los usuarios nuevos reciben 200 créditos al registrarse.
• Cuánto cuesta: se cobra por video, 5 segundos a 540p $0.2145, 720p $0.429, 1080p $1.7145; 10 segundos solo está disponible en texto a video, 540p $0.643, 720p $1.286, 1080p $5.143. Si falla, se reembolsa automáticamente.
• Cómo llamar a la API: POST https://api.hiapi.ai/v1/tasks, en model pon la ruta correspondiente, obtén el taskId y luego consulta en bucle o espera el callback.url; descarga el MP4 sin audio desde data.output[0].url.

La salida de Ray 3.2 es un MP4 sin sonido. En texto a video puedes elegir la duración y la relación de aspecto en la solicitud; en imagen a video la duración es fija de 5 segundos y la relación de aspecto sigue al primer fotograma. A continuación recorremos de una vez la prueba en línea, curl, Python, imagen a video y las consideraciones antes de salir a producción.

¿Qué es Ray 3.2? Cómo elegir entre las dos rutas

• Texto a video: solo envías prompt, opcionalmente duration (5 o 10 segundos), resolution (540p / 720p / 1080p) y aspect_ratio (16:9, 9:16, 1:1, 4:3, 3:4, 21:9). El prompt admite hasta 6000 caracteres.
• Imagen a video: requiere prompt y el primer fotograma image_url, opcionalmente el último fotograma end_image_url y resolution. Cada video dura fijos 5 segundos, la relación de aspecto sigue al primer fotograma y se ajusta automáticamente a la proporción compatible más cercana.
• En común: ambas usan /v1/tasks, se cobran por video y generan un MP4 sin pista de audio.

Texto a video sirve para planos que solo tienes concebidos en texto, que necesitan 10 segundos o una relación de aspecto específica; imagen a video sirve cuando ya tienes una foto de producto, un póster, una imagen conceptual o quieres fijar el fotograma final. Las tres tarifas de 5 segundos son iguales en ambas rutas; los 10 segundos solo existen en texto a video.

Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.

Generar con este prompt →, elige relación de aspecto 21:9, un video de 540p cuesta $0.2145.

Dos rutas para empezar: ¿prueba en línea o API?

Prueba en línea (aprox. 1 minuto)

1. Abre la página del modelo Ray 3.2 de texto a video, o haz clic en el enlace rellenado de arriba.
2. Regístrate o inicia sesión; las cuentas nuevas incluyen 200 créditos; un video de 5 segundos en 540p cuesta 429 créditos, y tras recargar podrás generar.
3. Escribe el prompt, elige duración, resolución y relación de aspecto, y pulsa ejecutar.
4. Si el video te convence, descárgalo; cuando necesites la API, crea una Key en la consola.

Integración de la API (aprox. 5 minutos)

1. Crea una API Key en la consola de HiAPI (sk-...).
2. Haz POST /v1/tasks para crear la tarea y obtén data.taskId de la respuesta.
3. Consulta con GET /v1/tasks/{id}, o incluye callback.url en el nivel superior del cuerpo de la solicitud y espera la notificación.
4. Cuando data.status pase a success, descarga el video desde data.output[0].url.

Un video de 5 segundos en 540p cuesta $0.2145; con $10 puedes generar unos 46, suficiente para probar bien el movimiento de una serie de planos. Ve a la página del modelo y prueba tu primer video →

Primer video: versión curl

Crear una tarea de texto a video:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ray-3.2/text-to-video",
    "input": {
      "prompt": "Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.",
      "duration": 5,
      "resolution": "540p",
      "aspect_ratio": "21:9"
    }
  }'

El ID de tarea devuelto está en data.taskId:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Consultar el resultado:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

El único campo obligatorio es prompt. duration por defecto es 5, resolution por defecto es 540p, aspect_ratio por defecto es 16:9. Los tres campos tienen validación estricta; si pasas un valor incorrecto devuelve 400 directamente, no redondea automáticamente.

Primer video: versión Python

Crear, consultar en bucle y descargar en un solo bloque:

import time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "ray-3.2/text-to-video",
    "input": {
        "prompt": "Slow cinematic dolly-in toward a lone lighthouse keeper standing on a weathered iron balcony, salt spray drifting across the frame. Overcast dawn light, cool blue-grey tones, soft diffused shadows. The camera glides forward at a steady, patient pace, compressing the distance as gulls cross the background. Anamorphic lens look, shallow depth of field, gentle film grain. Negative: no text, no logos, no warping hands, no abrupt cuts.",
        "duration": 5,
        "resolution": "540p",
        "aspect_ratio": "21:9",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]

while True:
    task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if task["status"] in ("success", "fail"):
        break
    time.sleep(5)

if task["status"] == "success":
    video_url = task["output"][0]["url"]
    with open("ray32-clip.mp4", "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
else:
    print(task.get("error"))

Las tareas de video suelen tardar de decenas de segundos a varios minutos; usa un intervalo de consulta de 5 segundos y un tiempo máximo de espera de 10–15 minutos. Los enlaces de salida caducan; descarga en cuanto los recibas y guárdalos en tu propio almacenamiento.

Imagen a video: añade un primer fotograma, o primero y último

Cambia model a ray-3.2/image-to-video y añade el primer fotograma image_url; la misma solicitud se convierte en imagen a video:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ray-3.2/image-to-video",
    "input": {
      "prompt": "The ribbon of milk keeps folding down through the iced espresso, the ice cubes settle and shift slightly, condensation beads slide down the outside of the glass, very slow push-in toward the glass, warm rim light stays steady, vertical product commercial shot",
      "image_url": "https://www.hiapi.ai/images/model-pages/ray-3-2/iced-coffee-first.jpg",
      "resolution": "1080p"
    }
  }'

Para fijar el fotograma final, añade end_image_url. Cuanto más se parezcan el primer y el último fotograma en posición de cámara, iluminación y posición del sujeto, más estable será la transición; si las dos imágenes tienen encuadres distintos, el modelo añadirá por su cuenta un movimiento de cámara para enlazarlas. Ninguno de los dos campos afecta al precio.

Imagen a video no tiene duration ni aspect_ratio: cada video dura fijos 5 segundos y la relación de aspecto se ajusta según el primer fotograma a la más cercana entre 16:9, 9:16, 1:1, 4:3, 3:4 y 21:9; si la proporción no coincide, se recortan los bordes. Si quieres controlar por completo la proporción de salida, recorta primero el primer fotograma a una de estas seis proporciones.

3 cosas a tener en cuenta antes de salir a producción

1. Usa callback en el servidor. Añade en el nivel superior del cuerpo de la solicitud "callback": {"url": "https://yourapp.com/webhook", "when": "final"}; la tarea notificará automáticamente al alcanzar un estado final y te ahorras el polling. Tanto success como fail generan callback; haz idempotencia en el servidor por taskId.
2. No repitas el POST por timeout. Cada POST crea una tarea nueva y se cobra por separado. Guarda primero el taskId y deduplica en tu propio sistema antes de reintentar; si el proceso se cae, continúa consultando desde el id guardado.
3. Escribe los parámetros explícitamente en cada solicitud. resolution determina directamente el precio unitario, duration solo acepta el entero 5 o 10, y en imagen a video no incluyas duration ni aspect_ratio. Fíjalos en la solicitud para que la factura y el comportamiento sean predecibles.

Errores comunes, uno por línea

• 400 INVALID_REQUEST, valor de resolution incorrecto → solo acepta 540p, 720p y 1080p; no hay 2k ni 480p.
• 400, valor de duration incorrecto → solo acepta los enteros 5 y 10; pasar la cadena "5" o el número 7 fallará.
• 400 additional properties 'aspect_ratio' not allowed → imagen a video no tiene este campo, elimínalo; solo lo admite texto a video.
• 401 permission_denied → la Key falta, está mal escrita o fue revocada; revisa Authorization: Bearer sk-....
• La creación devuelve 200, pero la tarea luego pasa a fail → normalmente la image_url de imagen a video no se puede abrir o no es una imagen. Al crear solo se valida la forma de los campos, no si la URL es accesible.
• El enlace deja de abrirse a los pocos días → la URL de salida tiene caducidad; descarga en cuanto la recibas.

El importe preautorizado de las tareas fallidas se reembolsa automáticamente en su totalidad.

Preguntas frecuentes

¿Cuánto dura un video de Ray 3.2? En texto a video puedes elegir 5 o 10 segundos; en imagen a video es fijo de 5 segundos.

¿Cuánto puede medir el prompt? En ambas rutas, de 1 a 6000 caracteres.

¿El video tiene sonido? No; la salida es un MP4 sin pista de audio, la música y los efectos se añaden en posproducción.

¿Puedo elegir la relación de aspecto en imagen a video? No. La relación de aspecto sigue al primer fotograma y se ajusta automáticamente a la proporción compatible más cercana.

¿Puedo enviar una imagen de referencia en texto a video? No. Si quieres que una imagen guíe el resultado, usa ray-3.2/image-to-video.

Artículos de la serie Ray 3.2

• Página del modelo Ray 3.2 de texto a video: genera en línea y ve casos reales
• Página del modelo Ray 3.2 de imagen a video: casos con primer fotograma, último fotograma y vertical
• Cuánto cuesta la API de Ray 3.2: 6 tarifas y presupuesto mensual
• Ray 3.2 vs Runway Gen-4.5: cómo elegir entre texto a video e imagen a video
• Guía completa de prompts de Ray 3.2: 5 casos de texto a video + 3 de imagen a video
• Documentación de integración de Ray 3.2 en chino: todos los parámetros y códigos de error

Pruébalo ahora: haz clic en Generar con este prompt → debajo del video del faro de arriba; el prompt ya está rellenado, elige 5 segundos, 540p y 21:9, y con un clic obtendrás el mismo resultado.