API de Runway para texto a video: guía para desarrolladores sobre cómo llamar a Gen-4.5 mediante hiapi

Por qué usar un endpoint alojado de texto a video

La generación de video a partir de texto no es un sustituto del flujo de generación o edición de imágenes: es una capacidad fundamental distinta. Un modelo de imagen te entrega un fotograma fijo que puedes recortar, retocar o componer. Una llamada de texto a video te entrega movimiento: desplazamiento de cámara, acción del sujeto y luz que cambia con el tiempo. Si tu producto necesita un clip de video —una breve pieza de marketing, un bucle de fondo dentro de la app, una vista previa de una escena—, una sola llamada de «solicitud a clip» suele ser el camino más rápido de la idea al material.

El precio es el control. Estás describiendo movimiento con palabras en lugar de definirlo con fotogramas clave, así que el modelo tiene que interpretarlo por su cuenta. Eso hace que la calidad del prompt importe más que en las tareas de imagen, y que el ciclo de iteración importe más que un único intento.

Un endpoint alojado ofrecido a través de hiapi elimina el trabajo de infraestructura en torno a esta capacidad fundamental: obtienes una interfaz coherente, un modelo de credenciales y una estructura de respuesta unificada entre los modelos de video que invoques. Dedicas el tiempo a los prompts y a la integración con el producto, no a la canalización de almacenamiento, al sondeo de tareas ni a los SDK de cada proveedor.

Casos de uso adecuados:

• Clips cortos generados bajo demanda a partir de la entrada del usuario o de plantillas
• Exploración rápida de conceptos antes de invertir en una canalización de producción completa
• Material de fondo y B-roll que sigue siendo utilizable aunque una generación concreta tenga algún defecto

Casos de uso inadecuados: cualquier necesidad que requiera continuidad precisa a nivel de fotograma, resultados deterministas o coherencia narrativa de larga duración. Presupuesta varios clips candidatos por cada resultado utilizable.

Estructura del endpoint runway-gen-4.5/text-to-video

Conceptualmente, una solicitud a runway-gen-4.5/text-to-video consta de tres partes: el prompt, los ajustes a nivel de solicitud y tu identidad/autorización. Solo la primera parte es creativa; las otras dos determinan cómo se ejecuta el modelo y cómo se factura.

Qué envías

• La cadena del prompt. La entrada creativa principal: describe en lenguaje natural el sujeto, la acción, la cámara, la luz y la atmósfera.
• Ajustes a nivel de solicitud. Relación de aspecto, duración y cualquier indicador de generación que exponga el endpoint. Determinan la forma del contenedor de salida, no su contenido.
• Cabecera de autenticación. Tu clave de hiapi, que debe incluirse en cada llamada. Trátala como un secreto; nunca la publiques en el código del cliente.

Qué recibes

La generación de video no es instantánea, así que, según cómo se invoque el endpoint, puedes recibir un identificador de tarea que tendrás que sondear, o una respuesta que se resuelve en una URL de medio. En cualquiera de los dos casos, recibes una referencia al clip generado, no los bytes en bruto en línea. Si necesitas el material después de que caduque la URL devuelta, descárgalo y guárdalo en tu propio almacenamiento.

Un modelo mental útil: el endpoint es una función que asigna (prompt, settings) a un clip más metadatos. Tu integración debe tratarlo como asíncrono, reintentable y no determinista: las mismas entradas no siempre producen el mismo clip, y eso es el comportamiento esperado, no un defecto.

Mantén la construcción de la solicitud simple y aburrida. Escribe un pequeño envoltorio interno que arme el cuerpo de la solicitud, adjunte la autenticación, envíe la llamada y normalice la respuesta a { status, videoUrl, error }. Todas las secciones posteriores de esta guía dan por hecho que ese envoltorio ya existe.

Escribir prompts cinematográficos que funcionen en movimiento

Los adjetivos vagos se desmoronan en movimiento. «A beautiful cinematic shot of a city» no le da al modelo nada que animar, así que genera algo genérico y a la deriva. La solución es especificar los cuatro elementos que necesita un operador de cámara: sujeto, cámara, luz y movimiento.

Nombrar el sujeto y la acción

Indica qué hay en el plano y qué hace a lo largo del clip. Da un punto de partida y un punto final implícito, para que el modelo tenga una trayectoria de movimiento que seguir.

A lone cyclist rides from left to right along a wet coastal road, 
pedaling steadily as spray kicks up from the rear wheel.

Especificar la cámara de forma explícita

Usa lenguaje de cámara que el modelo pueda asignar a movimiento: acercamiento lento, gran angular fijo, seguimiento en mano, travelling bajo en ángulo bajo, panorámica lenta a la derecha, descenso aéreo. Un solo movimiento de cámara por clip resulta más seguro que tres movimientos que se contradicen.

Static wide shot, camera at ground level, no zoom.

Indicar la luz y la hora

La luz determina la mayor parte del nivel de producción percibido. Da la fuente y la textura: luz diurna difusa y nublada, sol fuerte de tarde desde la izquierda de la cámara, neón práctico reflejado en superficies mojadas durante la noche.

Describir movimiento físicamente creíble

El movimiento rápido en clips cortos produce estelas. Prefiere una única acción legible a velocidad moderada antes que muchos eventos rápidos. Si quieres tensión, consíguela con el movimiento de cámara y la luz, no haciendo que una docena de cosas ocurran a la vez.

Mantén un solo párrafo

Un párrafo compacto de una a tres frases supera a una lista de especificaciones con viñetas. Escríbelo como la descripción de un plano, no como una lista de deseos. Evita acumular adjetivos de estilo; elige una estética y mantenla hasta el final.

Una plantilla fiable:

[Subject + action]. [Camera framing and movement]. [Lighting and time of day]. [Environment and atmosphere].

Antes de tocar ningún ajuste, reescribe tu prompt con esta plantilla.

Una solicitud ejecutable, explicada paso a paso

Este recorrido supone Node.js y una función envoltorio, pero la estructura no depende del lenguaje.

Paso 1: escribir el plano

A chef slices vegetables on a wooden board in a small kitchen, 
hands moving steadily. Static medium close-up, camera at counter height, 
no zoom. Warm tungsten light from an overhead lamp, soft shadows, 
light steam in the background.

Paso 2: elegir los ajustes de la solicitud

Elige la relación de aspecto que coincida con el lugar donde se usará el clip, y la duración más corta que cuente la historia. Los clips cortos fallan rápido y exploran a menor coste.

Paso 3: enviar la llamada

const res = await fetch(`${HIAPI_BASE}/runway-gen-4.5/text-to-video`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.HIAPI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: shotPrompt,
    aspect_ratio: '16:9',
    duration: 5,
  }),
});

const data = await res.json();
if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);

Paso 4: obtener el clip

Si la respuesta incluye un identificador de tarea, sondea con intervalos de retroceso pequeños hasta que alcance un estado terminal. Si incluye directamente una URL de medio, salta al paso 5.

Paso 5: persistir el material

Descarga el clip y guárdalo con tus propias claves. Trata la URL devuelta como una dirección temporal.

Paso 6: registrar los puntos de decisión

Registra juntos el prompt, los ajustes y el material generado. Es ese registro el que hace que la siguiente sección —el ajuste— sea accionable en lugar de una conjetura.

Ajustar la salida sin modificar el prompt

Cuando un clip decepciona, el impulso es reescribir el prompt. Resiste una ronda. El prompt y los ajustes son variables independientes; cambiar ambos a la vez destruye tu capacidad de juzgar cuál era la clave.

Aislar variables

Mantén el prompt fijo y cambia exactamente un ajuste a nivel de solicitud: relación de aspecto, duración o algún indicador de generación. Vuelve a ejecutar. Si el clip mejora, el problema era estructural y no creativo. Si no mejora, revierte ese ajuste y cambia el prompt.

Resolver problemas estructurales con ajustes

• ¿La composición no coincide con la ubicación de destino? Cambia la relación de aspecto.
• ¿La acción se corta antes de completarse? Aumenta la duración.
• ¿Todo se desplaza sin puntos de anclaje? Acorta el clip para que no tenga tanto tiempo para derivar.

Resolver problemas de contenido modificando el prompt

• ¿El sujeto es incorrecto o falta? Nómbralo antes y sé específico.
• ¿La cámara vaga? Elimina todas las palabras de cámara salvo el único movimiento que quieres.
• ¿Resulta plano y sin vida? Añade la fuente y la dirección de la luz.

Haz una pequeña prueba A/B

Fija un prompt semilla, genera tres variantes y cambia solo una cláusula en cada una. Compáralas en paralelo, no de memoria. La no determinación significa que un único clip malo no es evidencia; antes de concluir que una cláusula es perjudicial, busca un patrón en dos o tres ejecuciones.

Anota las conclusiones en el registro que ya mantienes. Tras una docena de iteraciones, esto se convierte en un manual de prompts y ajustes específico para tu producto, mucho más valioso que cualquier lista genérica de prompts.

Depurar fallos habituales

La mayoría de los fallos de la primera semana se agrupan en cuatro categorías. Cada una tiene una ruta de investigación distinta.

Solicitud rechazada o bloqueada

Una respuesta no 2xx con información de política significa que el prompt o los ajustes no fueron aceptados. Lee el cuerpo de la respuesta de error en lugar de reintentar a ciegas. Reescribe la descripción problemática, elimina personas reales o marcas nombradas y vuelve a enviar. Registra el prompt rechazado tal cual: los rechazos recurrentes suelen remontarse a un hábito en la plantilla de prompts.

Tiempos de espera agotados

La generación de video es lenta. Si tu cliente HTTP agota el tiempo de espera antes de que el endpoint responda, es posible que la tarea siga en ejecución y se facture. Aumenta el tiempo de espera del cliente para las llamadas de generación y mueve el sondeo a un proceso de trabajo en segundo plano, en lugar de mantener la solicitud colgada.

Clips vacíos o inutilizables

Una respuesta correcta pero un clip sin sujeto reconocible suele significar que el prompt era demasiado abstracto. Vuelve a leerlo con la plantilla sujeto-cámara-luz-movimiento. Si falta uno de los cuatro, ahí está tu punto de corrección.

Errores de autenticación y configuración

401 y 403 significan un problema de clave, no de prompt. Confirma que la clave existe en el entorno de ejecución, no solo en tu shell local, y confirma el formato de las cabeceras. Este tipo de fallo cuesta menos cuanto antes se detecta, y más cuando aparece en producción.

Una regla general: clasifica el error antes de cambiar nada. Los errores de prompt, los de ajustes y los de infraestructura requieren soluciones distintas; mezclarlos desperdicia presupuesto de generación.

Coste, latencia y protecciones para producción

Antes de salir a producción, decide cómo se comportará el endpoint cuando algo falle, porque la generación de video es la llamada más cara y lenta de la mayoría de los productos.

Presupuesta por clip, no por llamada

La facturación de video suele depender de la longitud de salida, así que los clips largos cuestan más que los cortos. Presupuesta por unidad de clip terminado —incluidos reintentos y candidatos rechazados— en lugar de contar llamadas a la API. Establece límites de generación por usuario y por sesión. Consulta las tarifas actuales en el panel de precios; no las codifiques en la lógica de negocio.

Diseña pensando en la latencia

Nunca hagas que una solicitud orientada al usuario se bloquee esperando la generación. Inicia la tarea, devuelve el identificador de inmediato y entrega el clip mediante sondeo, webhook o notificación. Muestra el progreso en la interfaz para que una renderización lenta se lea como trabajo en curso y no como un bloqueo. Almacena en caché los clips ya generados por prompt y ajustes para evitar volver a generarlos en solicitudes repetidas.

Valida antes de generar

Las comprobaciones baratas previas a la llamada ahorran el procesamiento caro posterior:

• Impón una longitud mínima y máxima del prompt en tu envoltorio
• Rechaza prompts a los que les falte sujeto o acción
• Valida la relación de aspecto frente al destino de renderización
• Confirma que el usuario está dentro de su cuota

Modera tanto en la entrada como en la salida

Haz una comprobación de texto del prompt antes de enviarlo. Haz una comprobación ligera del clip devuelto antes de mostrarlo. Ambas salen más baratas que un incidente de soporte.

Conserva un plan de reserva

Si la generación falla o tarda demasiado, ofrece un fotograma de portada estático o un clip de marcador de posición en lugar de un error. La función debe degradarse, no romperse.

Empieza con un endpoint, un envoltorio y un registro; añade protecciones a medida que descubras dónde falla realmente el producto, y mantén el panel de precios como la única fuente de verdad sobre el coste.