Llamar al modelo wan2.7-video/text-to-video a través de la API de HiAPI: un flujo de trabajo práctico para videos cortos

Por qué la generación de video a partir de texto debe ir dentro de un pipeline y no en una sola llamada

El error más común al usar un modelo de texto a video es tratarlo como un generador de imágenes con movimiento: se introduce un prompt y sale un video terminado. Los videos cortos rara vez funcionan así. Un clip de quince segundos que funciona bien suele ser el resultado de varios clips generados, una ronda de selección y un montaje, no de una única renderización afortunada.

Un modelo mental más útil es tratar al modelo como un generador de clips dentro de un pipeline. El pipeline es más o menos así:

1. Entrada de prompt: escribes un prompt que describe un instante claro: el sujeto, la acción, la escena y cómo se mueve la cámara.
2. Generación de clip: el modelo wan2.7-video/text-to-video genera un clip corto a partir de ese prompt.
3. Selección: revisas los clips generados y conservas los que se sostienen por sí mismos.
4. Montaje: unes, recortas y ordenas los clips conservados hasta obtener la pieza final de video corto.

Esta perspectiva tiene dos consecuencias. Primera, cada clip generado debe poder sostenerse por sí solo: si un fragmento solo tiene sentido como parte de una secuencia mayor, es difícil seleccionarlo y reordenarlo. Segunda, el prompt se convierte en la variable principal del flujo de trabajo, y no el código de integración. Escribes la petición una vez y luego cambias el texto del prompt muchas veces.

Esta es también la ventaja de pensar en términos de pipeline desde el principio. Si diseñas la primera llamada como una renderización de un solo uso, luego tendrás que reescribirla para conectar la selección o el montaje. Si la diseñas desde el principio como un generador de clips, el resto del flujo de trabajo crecerá de forma natural a su alrededor.

Qué cubre este artículo

Definiremos qué puede hacer el modelo dentro de un stack basado en HiAPI, cómo organizar el prompt en torno a un único clip utilizable, cómo formular el lenguaje de cámara y movimiento, una forma de petición funcional y cómo convertir una llamada que funciona en un proceso repetible mediante un bucle de iteración.

Qué hace el modelo wan2.7-video/text-to-video en tu stack

El modelo wan2.7-video/text-to-video recibe un prompt de texto y devuelve un clip de video generado. Ese es el contrato sobre el que debe apoyarse tu pipeline: entrada de texto, salida de clip.

En un stack basado en HiAPI, el modelo se encuentra detrás de una única interfaz de API unificada. Tu aplicación no se comunica directamente con el modelo: envía peticiones a HiAPI, y HiAPI gestiona la llamada al modelo y devuelve el recurso del clip generado. Esto tiene varias implicaciones prácticas a la hora de delimitar la integración:

• Una integración, muchas iteraciones. La interfaz de la API se mantiene estable cuando cambia el prompt. La petición se construye una sola vez.
• El modelo es una unidad reutilizable. El texto del prompt es la variable que ajustas; la estructura de la llamada es la constante.
• Todo lo que rodea a la llamada es responsabilidad de tu stack. La subida, el almacenamiento, la lógica de selección, el montaje y la publicación son responsabilidad tuya; el modelo solo genera clips.

Qué debe quedar fuera del alcance

Ten cuidado de no suponer detalles concretos que el modelo no promete. No codifiques en la lógica del pipeline suposiciones como la tasa de fotogramas, los preajustes de resolución, la duración máxima de un clip o el comportamiento temporal exacto. En su lugar, trata el clip devuelto como un recurso opaco: lee sus metadatos de la respuesta, valídalos y haz que la etapa de montaje se adapte a la duración real de cada clip.

Esta disciplina es especialmente importante en el trabajo con videos cortos. La salida de video corto se compone de varios clips, así que un pipeline que se adapta a la duración real de los clips es mucho más robusto que uno que asume una duración fija.

Reparto de responsabilidades

El reparto claro es el siguiente:

• Lado del modelo: interpretación del prompt, movimiento y generación del clip de video.
• Lado de HiAPI: acceso autenticado al modelo a través de una API unificada.
• Tu lado: diseño de prompts, gestión de peticiones, validación de respuestas, almacenamiento de clips, selección, montaje y entrega.

Una vez respetada esta frontera, el resto del flujo de trabajo (estructura del prompt, formulación de cámara, iteración) encaja en su sitio.

Organizar el prompt para clips de video corto

Como cada clip debe poder usarse de forma independiente, cada prompt debe describir un instante único y autocontenido. La forma fiable es construir el prompt con módulos explícitos, en lugar de escribir un párrafo largo y confiar en la suerte.

Los cuatro módulos

Una estructura útil es sujeto, acción, escena, estilo:

• Sujeto: quién o qué aparece en la imagen. Sé concreto: «un ciclista con impermeable rojo» es mejor que «una persona».
• Acción: la única cosa que hace el sujeto durante el clip. Mantenla como una acción continua única.
• Escena: dónde ocurre, incluida la luz y el clima si importan.
• Estilo: el tratamiento visual: realista, animación, cámara en mano con grano, cinematográfico, etc.

Por ejemplo, un prompt estructurado por módulos sería: un ciclista con impermeable rojo, pedaleando de forma constante por calles urbanas mojadas al atardecer, reflejos de neón en los charcos, aspecto realista de cámara en mano.

Escribe una sola acción por clip

Un clip corto no tiene espacio para un arco narrativo. Si describes a un sujeto que entra, se sienta, pide un café y se va, el modelo tendrá que comprimir o descartar parte del contenido, y el resultado será impredecible. Sepáralo: un clip para entrar, otro para sentarse, otro para la barra. Cada clip se puede seleccionar, reordenar y recortar durante el montaje, y si uno falla, es fácil regenerarlo por separado.

Recombina los módulos para generar variantes

Tratar los módulos como campos independientes te da una forma económica de generar variantes. Fija el sujeto y la escena, y varía la acción. Fija la acción y cambia el estilo. Así se producen grupos de clips relacionados que se pueden editar bien juntos, que es justo lo que necesita el montaje de video corto. Puedes generar estas variantes en código recorriendo una pequeña estructura de datos, en lugar de escribir cada prompt a mano.

Mantén el prompt conciso

Cada cláusula adicional en el prompt compite por influencia. Si un detalle no cambia lo que aparece en la imagen de este clip, elimínalo. Un prompt enfocado con cuatro módulos claros suele superar a una descripción larga y atmosférica que acumula cinco ideas.

Escribir formulaciones de cámara y movimiento que realmente se lean

Los verbos de movimiento vagos producen movimientos vagos. Si tu prompt dice «movimiento dinámico de la escena» o «una toma emocionante», el modelo no recibe ninguna instrucción espacial y solo puede improvisar; y el comportamiento improvisado de cámara es la causa más frecuente de que un clip se descarte en la fase de selección.

Sé literal al describir el comportamiento de la cámara

Describe la cámara con la misma concreción con la que darías instrucciones a un operador. Expresiones útiles:

• «la cámara se acerca lentamente al sujeto»
• «la cámara hace un paneo hacia la izquierda siguiendo al sujeto»
• «un plano fijo bloqueado»
• «la cámara sube desde la altura del suelo hasta la altura de los ojos»
• «una órbita lenta alrededor del sujeto»

Todas estas expresiones especifican dirección y magnitud (lento, bloqueado, ascenso), y por eso se pueden leer. En cambio, «cámara dinámica» no especifica ninguna de las dos.

Separa el movimiento del sujeto del movimiento de la cámara

Son dos instrucciones distintas y deben escribirse como dos frases distintas. El sujeto hace algo; la cámara hace algo; se describen de forma independiente. Mezclarlas en una sola cláusula («la cámara sigue al corredor mientras cruza») hace que no quede claro qué elemento impulsa el movimiento.

Ajusta el movimiento a la duración del clip

Un clip corto no puede contener un movimiento de cámara complejo. Hacer zoom, paneo y órbita a la vez en el mismo clip de dos segundos se comprime en una masa borrosa o se descarta por completo. Elige un solo comportamiento de cámara por clip y mantén una magnitud moderada. Si necesitas un movimiento de cámara largo y en evolución, ese es trabajo de la etapa de montaje: genera varios clips con posiciones de cámara progresivas y edítalos juntos.

Usa anclas espaciales

El modelo entiende bien las posiciones relativas. Frases como «en primer plano», «detrás del sujeto», «desde la izquierda» o «hacia la parte superior derecha del encuadre» le dan puntos de referencia. Añadir un ancla al sujeto y otra a la cámara suele estabilizar el plano más que acumular adjetivos.

Relee lo que has escrito

Antes de enviar la petición, haz una comprobación sencilla: lee la frase de movimiento como si dieras instrucciones a alguien que sostiene una cámara. Si esa persona tendría que preguntar algo, el prompt necesita una respuesta más concreta.

Una petición funcional de clip de texto a video en HiAPI

Esta sección explica la forma de la petición de principio a fin. El objetivo es obtener una plantilla que conserves y reutilices, cambiando solo el texto del prompt en cada ejecución.

Paso 1: autenticación

Todas las llamadas se hacen a través de HiAPI con tus credenciales de API. Guarda la clave en una variable de entorno, no en el código fuente:

export HIAPI_API_KEY="your_key_here"

Paso 2: enviar la petición de generación

Especifica el modelo en la petición y pasa el prompt. La forma mínima con curl es la siguiente:

curl -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video/text-to-video",
    "prompt": "un ciclista con impermeable rojo, pedaleando de forma constante por calles urbanas mojadas al atardecer, reflejos de neón en los charcos, la cámara se acerca lentamente, aspecto realista de cámara en mano"
  }'

Fíjate en cómo el prompt contiene los cuatro módulos más una instrucción de cámara explícita. Es la estructura descrita antes, solo que serializada.

Paso 3: gestionar la respuesta

La respuesta devuelve una referencia al recurso del clip generado. Antes de confiar en la respuesta, trátala como datos que hay que validar:

• Analiza el cuerpo de la respuesta como JSON y comprueba si hay campos de error antes de leer cualquier resultado.
• Confirma que existe la referencia del clip; si no existe, registra la respuesta completa y detente, en lugar de continuar con un valor vacío.
• Lee los metadatos del clip de la respuesta y regístralos junto con el prompt que produjo ese clip; esta es la base del bucle de iteración posterior.
• Descarga o transmite el clip a tu propio almacenamiento, porque la persistencia es responsabilidad de tu pipeline.

Paso 4: encapsular en una función

Para cualquier flujo de trabajo real, traslada la petición a una función pequeña que reciba la cadena del prompt y devuelva la referencia del clip y sus metadatos. Deja dentro de la función el nombre del modelo, las cabeceras y el manejo de errores. A partir de ahí, cada experimento consiste en cambiar una línea de prompt, no en hacer una tarea de integración.

import os, requests

def generate_clip(prompt: str) -> dict:
    resp = requests.post(
        "https://api.hiapi.ai/v1/video/generations",
        headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
        json={"model": "wan2.7-video/text-to-video", "prompt": prompt},
        timeout=120,
    )
    resp.raise_for_status()
    data = resp.json()
    if not data.get("clip"):
        raise ValueError(f"No clip in response: {data}")
    return data

Esta función es la unidad reutilizable de tu pipeline. Todo lo demás se construye sobre ella.

Paso 5: validar antes de montar

Antes de que un clip entre en la etapa de montaje, comprueba que el archivo se descarga correctamente y que su duración está dentro de lo que el paso de montaje espera poder manejar. Rechaza pronto, en lugar de descubrir un clip dañado en el momento de publicar.

Iteración: de un buen clip a un flujo de trabajo de video corto repetible

Una vez que la petición funciona, empieza el trabajo interesante: convertir un único clip bueno en un proceso que produzca salidas de video corto de forma fiable.

El bucle de iteración

Este bucle tiene tres fases y se repite continuamente:

1. Transformar el prompt. Cambia solo un módulo a la vez: la acción, la frase de cámara, el estilo. Si cambias varios a la vez, no podrás saber qué cambio fue el responsable.
2. Seleccionar clips. Revisa el conjunto de clips generados y conserva los que sirven. Registra tus decisiones de selección; notas como «el acercamiento funciona, la órbita es demasiado rápida» valen más que el propio clip.
3. Montar. Une los clips conservados, recórtalos a la duración que necesitas y comprueba que los segmentos se pueden editar juntos de forma limpia.

La salida del montaje retroalimenta la siguiente ronda de transformación de prompts. Si dos clips no se pueden editar juntos, eso es información: indica en qué aspectos deben coincidir tus prompts (encuadre del sujeto, luz o dirección del movimiento).

Crear una biblioteca de prompts

Conserva cada prompt que haya producido un clip que hayas retenido, junto con la referencia del clip y tus notas. Tras varias rondas, esto se convierte en una pequeña biblioteca de patrones que puedes recombinar: descripciones de sujeto validadas, frases de cámara validadas, módulos de estilo validados. Así los nuevos videos se ensamblan a partir de piezas que ya sabes que funcionan, en lugar de empezar desde un prompt en blanco.

Generar por lotes desde estructuras de datos

Como tu función de petición recibe una cadena de prompt, generar variantes es recorrer una lista o un pequeño objeto de configuración. Define el sujeto y la escena una vez, y luego recorre listas de acciones y de frases de cámara para generar un conjunto de candidatos. Aquí es donde se rentabiliza la perspectiva de pipeline: el modelo es la constante, el prompt es la variable y tu código solo tiene que enumerar las variaciones.

Mantener bajo el costo de la selección

No es necesario revisar por completo cada clip generado. Define de antemano criterios de rechazo sencillos (sujeto equivocado, falta de movimiento, encuadre inutilizable) y descarta rápido. Dedica el tiempo de revisión a los casos límite, es decir, a los clips que podrían ser utilizables después de recortarlos.

Versionar el flujo de trabajo

Para cada clip que conserves, almacena el prompt, el nombre del modelo y los metadatos de la respuesta juntos. Cuando cambie el estilo visual de tu canal, podrás rastrear exactamente qué patrones de prompt produjeron el estilo actual y ajustar desde una base conocida, en lugar de adivinar.

Errores comunes y cómo evitarlos

En los pipelines de texto a video se repiten varios modos de fallo. Cada uno tiene una solución directa.

Verbos de movimiento vagos

Síntoma: el movimiento de cámara del clip devuelto parece aleatorio, o el sujeto apenas se mueve. Solución: sustituye cada palabra de movimiento abstracta por una instrucción literal y direccional. Especifica por clip un comportamiento de cámara y una acción del sujeto, cada uno con una magnitud: lento, constante, bloqueado.

Prompt sobrecargado

Síntoma: parte de la descripción falta en la salida, o el resultado parece un compromiso entre varias ideas. Solución: impón una sola acción por clip y elimina los detalles que no cambian lo que aparece en la imagen. Divide las ideas de varias tomas en clips independientes y deja que la etapa de montaje haga el ordenamiento.

Saltarse la validación de la respuesta

Síntoma: respuestas fallidas o mal formadas llegan al almacenamiento y al montaje, y solo se detectan al publicar. Solución: comprueba inmediatamente después de cada llamada si hay errores y si existe la referencia del clip, registra la respuesta completa cuando falle y valida los recursos descargados antes de que entren en la selección.

Suponer propiedades fijas del clip

Síntoma: la lógica de montaje falla cuando la duración o el formato del clip devuelto no coinciden con lo esperado. Solución: lee los metadatos de la respuesta y adáptate a ellos en el montaje. No codifiques la duración del clip en el pipeline.

Cambiar demasiadas variables a la vez

Síntoma: no puedes determinar qué cambio del prompt mejoró o rompió la salida. Solución: cambia solo un módulo por ronda de iteración y conserva notas. La ingeniería de prompts aquí es un ciclo experimental, no una reescritura.

Tratar la llamada a la API como el producto completo

Síntoma: la petición funciona pero no hay salida fiable, porque la selección y el montaje nunca se construyeron. Solución: recuerda que la generación es solo una etapa. Dedica esfuerzo real a la revisión, el almacenamiento y el montaje de clips; la calidad del video corto se decide ahí.

Si guardas la petición en una función reutilizable e iteras sobre el texto del prompt, la mayoría de los errores anteriores desaparecen por sí solos.