Luma

Ray 3.2

ray-3.2/text-to-video

Modelo de generación de video cinematográfico Luma, compatible de forma nativa con HDR y exportación EXR, ideal para planos de ambiente vacíos y conceptos previos de publicidad, cine y televisión; con instrucciones de cámara estructuradas, el seguimiento de las indicaciones es estable.

ray-3.2/image-to-video ray-3.2/text-to-video

Precios

ray-3.2/text-to-video per video

Especificaciones	Precio unitario
540P	$0.2145
720P	$0.429
1080P	$1.7145

Descripción general

Ray 3.2 es el modelo de texto a vídeo de Luma orientado a cortometrajes con estética cinematográfica. Basta con un mensaje de texto para generar clips de 5 o 10 segundos, con resolución seleccionable entre 540p, 720p y 1080p, y compatible con seis relaciones de aspecto: 16:9, 9:16, 1:1, 4:3, 3:4 y 21:9. Responde de forma bastante estable a descripciones estructuradas y concretas de la toma y del sujeto, y destaca en planos ambientales como tomas de recurso. Está pensado para desarrolladores y equipos creativos que necesitan producir rápidamente vídeos conceptuales, previsualizaciones de storyboard y clips para redes sociales, y puede integrarse en el flujo de generación mediante la interfaz unificada de HiAPI.ai.

Aspectos destacados

Control de la imagen mediante la descripción de la toma: sigue con bastante fidelidad las indicaciones estructuradas y concretas sobre la puesta en escena y el sujeto; con instrucciones vagas o abiertas, el resultado empeora.
Ajuste de estilo cinematográfico: el estilo visual y la representación física realista tienden a lo cinematográfico, lo que lo hace adecuado para tomas de recurso atmosféricas y planos de entorno.
Múltiples relaciones de aspecto y resoluciones: la salida admite seis proporciones entre horizontal, vertical, cuadrada y panorámica, con resolución de hasta 1080p y duración de 5 o 10 segundos.

Capacidades

Generación directa de vídeo a partir de texto: basta con introducir un prompt de hasta 6000 caracteres para producir un clip, sin necesidad de preparar material previo; ideal para validar rápidamente una idea de plano desde cero.

Duración y resolución seleccionables: la duración del clip puede ser de 5 o 10 segundos, y la resolución abarca 540p, 720p y 1080p, de modo que se pueden elegir especificaciones distintas según la fase de borrador o de versión final.

Seis relaciones de aspecto en una sola pasada: compatible con 16:9, 9:16, 1:1, 4:3, 3:4 y 21:9; un mismo prompt puede producir directamente versiones horizontales, verticales o panorámicas, adaptándose a distintos formatos de publicación.

Estética cinematográfica y planos atmosféricos: el estilo visual y la representación física realista tienden a lo cinematográfico, y resulta bastante estable en planos de entorno como tomas de recurso atmosféricas o fondos de escena.

Casos de uso

Equipos de cine o publicidad para vídeos conceptuales y previsualizaciones de storyboard: describir con texto la puesta en escena y la atmósfera de la escena para producir clips de 5 a 10 segundos como referencia visual previa, útiles para la comunicación creativa y con el cliente.
Equipos de contenido para generar tomas de recurso atmosféricas y material de fondo: describir la luz, el entorno y la emoción para producir material de planos de entorno destinado a transiciones, pantallas de fondo y ambientación en el montaje de vídeo.
Profesionales de marketing para producir rápidamente clips para redes sociales: elegir el formato vertical u horizontal según el espacio de publicación y generar directamente clips de 5 a 10 segundos adaptados a cada plataforma para redes sociales y campañas publicitarias.
Desarrolladores para generar material de planos por lotes: enviar tareas de generación por lotes mediante la interfaz unificada de HiAPI.ai a partir de prompts e integrar el material de planos en sus propios flujos de producción de contenido o en su biblioteca de recursos.

Limitaciones y recomendaciones de selección

La duración máxima del clip es de 10 segundos y la resolución máxima es 1080p, por lo que no es adecuado para planos largos ni para generar directamente másteres de alta resolución. Evaluaciones de terceros indican que la coherencia temporal y la calidad del movimiento no son sus puntos más fuertes, y que los planos con movimiento continuo o interacción entre varios sujetos requieren varias rondas de generación y selección. El resultado depende de prompts estructurados y concretos; con instrucciones vagas o abiertas, el rendimiento disminuye. Si la necesidad es narrativa de larga duración, control preciso del movimiento o generación guiada por imagen, conviene evaluar otros modelos o combinarlo con una vía de imagen a vídeo.

Preguntas frecuentes

Ver todas las preguntas →

¿Qué entradas requiere Ray 3.2 para la generación de video a partir de imágenes?

Se requieren dos campos obligatorios: prompt (1–6000 caracteres) y image_url del primer fotograma. Opcionalmente end_image_url como fotograma final, y resolution (540p, 720p, 1080p, por defecto 540p). En el Playground se puede subir directamente una imagen local.
¿Se puede ajustar la duración del vídeo?

No. Cada vídeo generado a partir de una imagen tiene una duración fija de 5 segundos; la solicitud no incluye el parámetro duration. Si necesitas una toma de 10 segundos, puedes usar en su lugar Ray 3.2 de texto a vídeo, que admite 5 y 10 segundos.
¿Qué determina la relación de aspecto de la salida?

La determina el primer fotograma; no hay parámetro aspect_ratio. La salida se ajusta a la más cercana entre 16:9, 9:16, 1:1, 4:3, 3:4 y 21:9; cuando la relación no coincide exactamente, los bordes se recortan. La imagen original del caso del desierto de esta página es de aproximadamente 3:2 (1024×687) y la salida es de 4:3, 1104×832; la imagen original del caso del café helado es 9:16 y la salida es un vídeo vertical 9:16, prácticamente sin recorte. Si quieres que la relación de la salida sea totalmente controlable, recorta primero el primer fotograma a una de estas seis relaciones.
¿Cómo se usan el primer y el último fotograma?

Pasa el primer fotograma en image_url y el último en end_image_url; el video hará la transición del primer fotograma al último, y el prompt solo necesita describir los cambios que ocurren en el intermedio. Cuanto más parecidos sean el encuadre, la iluminación y la posición del sujeto en las dos imágenes, más estable será la transición; cuando el encuadre es distinto, el modelo añade movimiento de cámara para empalmar, que es justo el caso de la peonía en esta página.

Crear una tarea de generación

POST https://api.hiapi.ai/v1/tasks

Encabezados

AuthorizationstringObligatorio

Clave API de la cuenta. Obligatoria en cada solicitud. Ejemplo: Bearer YOUR_HIAPI_API_KEY. Obtener clave API

Content-TypestringOpcional

El cuerpo de la solicitud siempre se analiza como JSON; si se envía, solo se acepta application/json (charset opcional) — cualquier otro valor devuelve 415. Ejemplo: application/json.

Idempotency-KeystringOpcional

Clave de idempotencia, hasta 255 bytes. Los reintentos con la misma clave de la misma cuenta crean la tarea una sola vez; las repeticiones devuelven el taskId original.

Clave de idempotencia

Ante timeouts de red o reintentos automáticos del cliente, la misma clave crea la tarea una sola vez, sin doble cobro (alcance = la cuenta de la clave API). Usa un identificador de negocio único (p. ej. "order-42"); las repeticiones devuelven el taskId original y las claves caducan 24 h después de la primera solicitud. La matriz completa de escenarios está en la introducción de la API asíncrona unificada.

Cuerpo

modelstringObligatorio

Valor fijo actual: ray-3.2/text-to-video

routestringOpcional

Valor fijo actual: default

inputobjectObligatorio

Objeto de parámetros de negocio para ray-3.2/text-to-video y la ruta default; consulta la tabla de parámetros a continuación.

promptstringObligatoriominLength 1maxLength 6000

Indicación de texto que describe el contenido del video que se va a generar; toma un valor de cadena y debe explicar en lenguaje natural elementos como el sujeto de la imagen, la escena y la acción.

durationintegerOpcionalPredeterminado: 5

Controla la duración del video generado; toma un número entero de segundos, puede ser 5 segundos o 10 segundos, y por defecto es 5 segundos.

Opciones:510

resolutionstringOpcionalPredeterminado: "540p"

Controla la resolución del video de salida; toma un valor de cadena y por defecto es 540p.

Opciones:540p720p1080p

aspect_ratiostringOpcionalPredeterminado: "16:9"

Controla la relación de aspecto del video de salida; toma un valor de cadena y por defecto es 16:9.

Opciones:16:99:161:14:33:421:9

callbackobjectOpcional

Configuración de notificación de estado terminal. Si se omite, no hay callback: consulta la tarea por tu cuenta.

Callbacks (Webhook)

Indica callback.url al crear y HiAPI hará POST a tu servicio en el estado terminal, sin necesidad de sondeo. El cuerpo del callback replica la estructura del detalle de la tarea; firma, reintentos e idempotencia se detallan en la introducción de la API asíncrona unificada.

urlstringObligatorio

Obligatorio si se incluye callback. Al estado terminal se envía un POST a esta URL; debe ser una URL http(s) válida.

whenstringOpcionalPredeterminado: "final"

Actualmente solo se admite final: notifica tanto en success como en fail.

Opciones:final

storagestringOpcionalPredeterminado: "temp"

Nivel de almacenamiento de artefactos: temp (por defecto, ~7 días) o persistent (largo plazo, facturado por tamaño). Saldo insuficiente o exceso de límite ⇒ degradación silenciosa a temp; el nivel efectivo se muestra en la respuesta del detalle.

Opciones:temppersistent

Ejemplos de solicitud

# Envía una tarea asíncrona; devuelve un taskId de inmediato (sin esperar la generación)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ray-3.2/text-to-video",
  "input": {
    "prompt": "…",
    "duration": 5,
    "resolution": "540p",
    "aspect_ratio": "16:9"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "ray-3.2/text-to-video",
    input: {
      "prompt": "…",
      "duration": 5,
      "resolution": "540p",
      "aspect_ratio": "16:9"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "ray-3.2/text-to-video",
        "input": {
          "prompt": "…",
          "duration": 5,
          "resolution": "540p",
          "aspect_ratio": "16:9"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

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

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Obtener el detalle de la tarea

GET https://api.hiapi.ai/v1/tasks/:id

Campos de respuesta

taskIdstringObligatorio

ID de tarea, siempre con prefijo tk-hiapi-.

modelstringObligatorio

Nombre completo resuelto del modelo. Las tareas enviadas con el parámetro route devuelven base@route (p. ej. gpt-image-2/text-to-image@ext); si no, coincide con el nombre enviado.

routestringOpcional

Solo aparece si se usó el parámetro route explícito; repite el valor enviado.

statusstringObligatorio

Estado de la tarea.

Valores de estado

queued En cola, sin iniciar. handling Procesando. archiving Proceso terminado, preparando artefactos. success Terminal: completado, artefactos disponibles (se devuelve output). fail Terminal: error (se devuelve error). Tras el envío, guíate por status: success y fail son terminales; el resto, no. Sondea cada 1–3 s hasta el estado terminal. Con éxito, descarga los artefactos desde output[].url y transfiérelos antes de expireAt; para retención larga usa storage: "persistent" al crear.

creatednumberObligatorio

Hora de creación de la tarea (segundos Unix).

completednumberObligatorio

Segundos Unix al alcanzar estado terminal; 0 mientras no sea terminal.

outputarrayOpcional

Solo con status == success. Lista de artefactos — siempre un array; una tarea puede devolver varios types a la vez (p. ej. video + first_frame).

Array [ object ]

Elementos del array

urlstringObligatorio

URL del artefacto, descargable directamente.

typestringObligatorio

Valores posibles actuales: video, image, audio, first_frame, last_frame, thumbnail; podrían ampliarse más adelante.

expireAtnumberObligatorio

Segundos Unix hasta los que el artefacto es accesible; descárgalo o transfiérelo antes.

errorobjectOpcional

Solo con status == fail.

codestringObligatorio

Código de error de negocio.

messagestringObligatorio

Descripción del error.

Ejemplos de respuesta

Éxito

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

En proceso (no terminal)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Fallido

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}