Luma

Ray 3.2

ray-3.2/image-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/image-to-video per video

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

Descripción general

El modelo de imagen a vídeo Ray 3.2 toma una imagen pública como primer fotograma y, junto con una descripción textual, genera un cortometraje con calidad cinematográfica; la relación de aspecto de salida sigue automáticamente la proporción de la imagen del primer fotograma. Admite una imagen de fotograma final opcional, lo que permite que la escena transicione desde el primer fotograma hasta el punto final especificado; la resolución se puede elegir entre 540p, 720p y 1080p, y el resultado es un clip de 5 segundos. Es adecuado para desarrolladores y equipos creativos que necesitan extender una toma a partir de un único fotograma clave, crear previsualizaciones conceptuales o planos de ambiente.

Puntos clave

Control bidireccional de fotogramas inicial y final: se puede proporcionar solo el primer fotograma o añadir una imagen de fotograma final para que el vídeo concluya en el punto final especificado, logrando una trayectoria de cámara más controlable.
La relación de aspecto sigue automáticamente al primer fotograma: la proporción de salida la determina la imagen del primer fotograma, por lo que se ajusta a la composición del material existente sin necesidad de configuración adicional.
Tres niveles de resolución opcionales: 540p, 720p y 1080p según necesidad, lo que facilita distribuir el coste entre la previsualización y el resultado final.

Descripción de capacidades

Imagen a vídeo guiado por el primer fotograma: basta con pasar una URL de imagen pública como primer fotograma y describir el movimiento y la escena con un prompt para obtener un vídeo de 5 segundos que parte de esa imagen.

Restricción de transición al fotograma final: se puede pasar opcionalmente una imagen de fotograma final, y el modelo genera la transición desde el primer fotograma hasta el fotograma final, lo que resulta útil para controlar el punto de llegada de la cámara y el cierre de la escena.

Respuesta a prompts estructurados: responde de forma más estable a descripciones concretas y estructuradas de movimiento y cámara; el prompt admite hasta 6000 caracteres, suficiente para instrucciones de cámara bastante completas.

Control de resolución y relación de aspecto: la resolución de salida se puede elegir entre 540p, 720p y 1080p, y la relación de aspecto hereda la de la imagen del primer fotograma, lo que reduce el recorte posterior.

Casos de uso

Previsualización conceptual: un fotograma clave + descripción de cámara: extender una imagen conceptual o un fotograma clave de un storyboard hasta un plano corto de 5 segundos, para previsualizaciones dinámicas en la fase de propuesta de cine y publicidad.
Planos de ambiente: imagen de escena + descripción del movimiento ambiental: convertir una imagen de escena estática en material de plano ambiental, para usarlo como fondo en pantalla, transición o preparación de atmósfera.
Empalme de fotogramas inicial y final: dos imágenes de inicio y fin: dados los fotogramas inicial y final, generar el fragmento de transición entre ambos, para la continuidad de planos y el control del ritmo.
Cortometrajes de marketing: imagen de producto + prompt de movimiento: generar material dinámico breve tomando la imagen del producto como primer fotograma, para producir rápidamente contenido en redes sociales y marketing.

Limitaciones y recomendaciones de selección

Cada generación es un fragmento fijo de 5 segundos y no admite duraciones mayores; la resolución máxima es 1080p, por lo que no es apto para planos largos ni para la entrega directa de másteres de alta resolución. El resultado depende de descripciones concretas y estructuradas del movimiento y la escena; con instrucciones ambiguas el rendimiento disminuye, y la coherencia temporal y la calidad del movimiento tampoco son sus puntos fuertes. Si se necesita generar vídeo directamente a partir de texto, se puede optar por un modelo de texto a vídeo de la misma serie; si se busca una duración mayor del resultado, habrá que evaluarlo por separado. La facturación es por cada 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/image-to-video

routestringOpcional

Valor fijo actual: default

inputobjectObligatorio

Objeto de parámetros de negocio para ray-3.2/image-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 movimiento dinámico y el contenido de la escena que se desea generar a partir de la imagen de entrada.

image_urlstringObligatorio

URL pública de la imagen que se utiliza como primer fotograma del video; la relación de aspecto del video de salida se mantiene igual a la de esta imagen.

resolutionstringOpcionalPredeterminado: "540p"

Resolución del video de salida; por defecto 540p; cada segmento de video dura 5 segundos.

Opciones:540p720p1080p

end_image_urlstringOpcional

URL pública opcional de una imagen que se usa como fotograma final del video; el video transiciona desde el primer fotograma hasta este fotograma.

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/image-to-video",
  "input": {
    "prompt": "…",
    "image_url": "…",
    "resolution": "540p"
  }
}'

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/image-to-video",
    input: {
      "prompt": "…",
      "image_url": "…",
      "resolution": "540p"
    }
  }),
});
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/image-to-video",
        "input": {
          "prompt": "…",
          "image_url": "…",
          "resolution": "540p"
        }
    },
)
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"
    }
  }
}