Flujo de trabajo de video corto con referencia a video usando vidu-q4-preview en la API de HiAPI

Por qué la generación de video a partir de referencias transforma el flujo de trabajo de video corto

La generación basada solo en prompts exige que el modelo cree todo por sí mismo: apariencia del sujeto, vestuario, composición, movimiento y audio. Para un experimento puntual, esto está bien. Para la producción de video corto —donde el mismo personaje o presentador debe aparecer en docenas de clips— el control basado únicamente en prompts falla rápidamente. Pequeños cambios en la redacción producen una enorme deriva visual, y ninguna cantidad de ingeniería de prompts puede fijar de forma fiable un rostro, un vestuario o una voz.

La generación de video a partir de referencias cambia ese contrato. En lugar de describir al sujeto con texto, entregas al modelo un conjunto de materiales de referencia —varias imágenes que establecen la identidad, más una referencia de voz que establece la voz del sujeto— y dejas que el prompt describa lo que debe suceder, no quién está dentro. El control creativo pasa de la redacción a nivel de token a la curaduría a nivel de material, y la preparación del material se convierte en el primer paso de ingeniería del flujo de trabajo, no en un añadido posterior.

Este cambio encaja perfectamente con la forma en que realmente se produce el contenido de video corto:

• Identidad reutilizable. Un conjunto de referencias aprobado puede reutilizarse en varios clips, de modo que una serie mantiene la consistencia visual sin necesidad de volver a escribir prompts.
• Separación de responsabilidades. El guionista se encarga de la acción y el ritmo en el prompt; el responsable de materiales se encarga de la apariencia y la voz en el conjunto de referencias.
• Entradas auditables. Cuando la salida no parece correcta, puedes comparar los conjuntos de referencias entre distintas ejecuciones en lugar de adivinar qué adjetivo cambió el resultado.

El video corto también eleva el umbral del coste del fallo. Distribuir un clip es barato, volver a rodarlo es caro, por lo que una tubería que produce variaciones predecibles a partir de una biblioteca de referencias fija vale más que una que ocasionalmente produce resultados excepcionales de un solo uso. La generación de video a partir de referencias es precisamente el mecanismo que hace posible esa previsibilidad.

Lo que no cambia

Sigue siendo necesario escribir prompts, seguir enviando solicitudes de estilo asíncrono y seguir posprocesando el video devuelto. La diferencia es que los materiales de referencia se convierten en una entrada de primera clase, y debes versionarlos, validarlos y almacenarlos igual que los prompts.

Cómo encaja el modelo de referencia vidu-q4-preview en HiAPI

En HiAPI, vidu-q4-preview/reference-to-video actúa como identificador de modelo, direccionable dentro de la misma interfaz de solicitudes que usas para otras tareas de generación. No necesitas integrar un SDK de proveedor independiente ni gestionar un segundo conjunto de credenciales. Tu aplicación llama a la API de HiAPI, la plataforma enruta la solicitud al modelo de referencia a video y la respuesta devuelve el material de video generado.

Esta capa tiene relevancia práctica en dos aspectos:

1. Interfaz de integración única. La autenticación, la estructura de solicitudes y el manejo de errores se mantienen coherentes entre los modelos que uses, por lo que añadir o cambiar de modelo es un cambio de configuración, no un cliente nuevo.
2. Herramientas operativas unificadas. El registro, los reintentos, la gestión de tasas y el análisis de respuestas se centralizan en un solo lugar, evitando que la ruta de referencia a video se convierta en una base de código paralela.

Para qué sirve este endpoint

El modelo de referencia a video es adecuado para clips donde la identidad del sujeto debe estar anclada por los materiales proporcionados en lugar de inventarse a partir del texto: clips promocionales cortos, segmentos de presentador fijo, tomas de producto con modelos consistentes y contenidos similares que requieren consistencia de serie. No es un editor de video genérico; genera nuevos clips a partir de tus referencias y prompts.

Trata el identificador de modelo como configuración

El identificador de modelo y los parámetros que admite cambian con el tiempo a medida que los modelos se añaden, se previsualizan y se retiran. No codifiques vidu-q4-preview/reference-to-video en una docena de lugares de la lógica de negocio. Mantenlo en una capa de configuración y verifica el identificador actual, los parámetros admitidos y la forma de entrada esperada contra la documentación pública de HiAPI antes de publicar. Cualquier afirmación en esta guía sobre la estructura de la solicitud es un resumen de la forma; la documentación es la fuente autoritativa de los nombres exactos de los campos.

Lo que no cubre esta guía

Los precios quedan deliberadamente fuera del alcance. La facturación en HiAPI se mide por tarea según el modelo y los parámetros que envíes, y las cifras en tiempo real pertenecen al panel de precios de la plataforma, no a un tutorial que quedará obsoleto. Lo mismo ocurre con cualquier declaración sobre latencia o rendimiento de un modelo concreto: mídela en tu propia carga de trabajo en lugar de confiar en cifras copiadas de una entrada de blog.

Preparar referencias de múltiples imágenes y voz

La calidad de las referencias domina la calidad de la salida. Dedica tiempo de ingeniería real a la preparación de materiales, porque la consistencia del modelo solo puede ser tan buena como las referencias que proporciones.

Elegir referencias de múltiples imágenes

Usa varias imágenes que muestren al mismo sujeto en condiciones diferentes pero compatibles: distintos ángulos, iluminación ligeramente distinta, una mezcla de primeros planos y planos medios. El objetivo es dar al modelo suficiente cobertura para resolver la identidad desde múltiples puntos de vista sin introducir contradicciones.

Reglas prácticas de selección:

• Mismo sujeto, mismo periodo. Evita mezclar referencias de apariencia con diferencias de peinado, barba o estilismo, a menos que quieras que el modelo haga un promedio.
• Tratamiento de color consistente. Diferencias grandes de balance de blancos o etalonaje entre referencias empujan al modelo hacia una paleta inestable.
• Sin sujetos competidores. Un conjunto de referencias con dos rostros prominentes tiende a provocar mezclas. Un sujeto por conjunto.
• Resolución suficiente. Las referencias reducidas o muy comprimidas pierden el detalle fino que el modelo necesita.

Preparar la referencia de voz

La referencia de voz establece el timbre y la forma de expresarse. Proporciona audio limpio: bajo ruido de fondo, sin música de fondo, sin hablantes superpuestos. Recorta al fragmento que mejor represente la forma de expresarse prevista y mantenlo suficientemente corto para ser representativo, no un monólogo completo. Si planeas hacer una serie con la misma voz, fija una referencia de voz y reutilízala.

Normalizar los materiales

Antes de que cualquier material llegue al constructor de solicitudes, hazlo pasar por un paso de normalización: formato y dimensiones de imagen consistentes dentro de un conjunto, formato y frecuencia de muestreo de audio consistentes. La normalización elimina toda una clase de fallos del tipo «ayer funcionaba» y hace que las claves de caché tengan sentido.

Versionar los conjuntos de referencias

Trata los conjuntos de referencias como artefactos con identificadores:

refsets/
  presenter-a/
    v1/  images/  voice.wav  manifest.json
    v2/  images/  voice.wav  manifest.json

El manifiesto debe registrar la procedencia de los materiales, qué normalización se aplicó y el hash de cada archivo. Cuando la salida derive, puedes determinar de inmediato si el conjunto de referencias cambió. Cuando derive sin que el conjunto de referencias haya cambiado, sabes que debes revisar el prompt o la versión del modelo. Mantén los conjuntos de referencias pequeños —unas pocas imágenes bien elegidas superan a un montón grande e inconsistente— y versionados, porque la reproducibilidad es lo que importa.

Ensamblar la solicitud en el código base

La solicitud de una llamada de referencia a video tiene tres partes conceptuales: la selección del modelo, el prompt que describe la acción y la carga de referencias que contiene los materiales de múltiples imágenes y voz. Mantén cada parte en su propia capa, de modo que cambiar una no te obligue a tocar las demás.

Una estructura viable

config/          id de modelo, endpoint, parámetros por defecto
refsets/         materiales de referencia versionados + manifiestos
builder/         ensambla prompt + conjunto de referencias + parámetros en una solicitud
client/          llamadas a HiAPI, reintentos, mapeo de errores
handler/         valida y almacena el video devuelto

Un constructor de solicitudes con esta forma hace aproximadamente lo siguiente:

1. Carga el identificador de modelo desde la configuración (por ejemplo, vidu-q4-preview/reference-to-video), nunca desde un literal incrustado en el llamador.
2. Carga el conjunto de referencias por versión desde el manifiesto, de modo que los materiales exactos usados queden registrados con la ejecución.
3. Adjunta el texto del prompt que describe la escena, la acción y el ritmo.
4. Combina los parámetros por defecto con cualquier sobrescritura de la ejecución.
5. Produce un objeto de solicitud que la capa de cliente envía a la API de HiAPI.

Mantener limpias las costuras

El constructor es el único lugar que conoce la forma de la solicitud. Si cambia un nombre de campo o si el modelo de referencia a video añade un parámetro, el cambio recae en el constructor, no en otros lugares. El texto del prompt debe ser una plantilla con huecos de contenido variable (nombre del producto, beat de escena, llamada a la acción) en lugar de concatenación de cadenas dispersa por el código de llamada.

Validar antes de enviar

Falla rápido en el constructor: comprueba que el conjunto de referencias se puede analizar, que existe el número esperado de imágenes, que el audio no está vacío y que el prompt está dentro de los límites. Una solicitud mal formada rechazada localmente cuesta milisegundos; la misma solicitud rechazada de forma remota cuesta un viaje de ida y vuelta y, según cómo midas, puede generar una tarea fallida.

Registrar la procedencia

Para cada trabajo enviado, registra el identificador de modelo, la versión del conjunto de referencias, la versión de la plantilla de prompt y cualquier sobrescritura de parámetros. Esa línea de registro es la clave que convierte «la salida ha empeorado» en una pregunta respondible. Al integrarte, verifica el identificador y los nombres de parámetros actuales contra la documentación pública de HiAPI, y vuelve a comprobarlo al actualizar el modelo.

Manejar la respuesta y el posprocesamiento de video corto

El material devuelto es el punto de partida, no el entregable final. Las plataformas de video corto imponen su propia relación de aspecto, duración, normas de sonoridad y convenciones de subtítulos, y el video devuelto con su audio nativo debe moldearse para cumplirlas.

Primero almacenar, luego transformar

Antes de tocar el video crudo devuelto, escríbelo en almacenamiento persistente. La transformación es con pérdida y ocasionalmente defectuosa; si la única copia es la recortada, un recorte malo significa regenerar. Usa el id de trabajo más la versión del conjunto de referencias como clave del objeto almacenado, para que puedas rastrear cualquier clip publicado hasta sus entradas.

Cadena de posprocesamiento

Una cadena típica de video corto se ve así:

• Inspección. Lee la duración, las dimensiones, la tasa de fotogramas y la sonoridad del audio del material devuelto, y regístralos en los metadatos de tu trabajo.
• Recorte. Corta a la duración objetivo, eligiendo deliberadamente los puntos de entrada y salida en lugar de cortar en un desplazamiento fijo; la generación a menudo deja un momento de inestabilidad al principio.
• Reencuadre. Escala y recorta a la relación de aspecto de la plataforma. Si el sujeto no está centrado, usa un recorte consciente del sujeto en lugar de un corte ciego al centro.
• Normalización de audio. Aplica normalización de sonoridad a la pista nativa y verifica que la referencia de voz se mantiene como se espera.
• Subtítulos y marca. Añade subtítulos quemados o superposiciones como un paso separado, para que puedan cambiarse sin recodificar el video base.
• Codificación. Genera los perfiles finales para cada plataforma de destino, conservando el máster intermedio.

Tratar el audio de forma explícita

Si el modelo devuelve audio nativo, trata la pista como un artefacto independiente. Extráela, mídela, normalízala y vuelve a encapsularla. Esto permite corregir pistas silenciosas sin volver a ejecutar la generación y hace visibles los problemas de sincronización desde el principio.

Fallar ruidosamente cuando la validación falla

Tras el procesamiento, ejecuta comprobaciones automáticas: duración dentro de rango, relación de aspecto correcta, audio presente y por encima del umbral de sonoridad, sin fotogramas negros al inicio. Todo lo que falle pasa a una cola de revisión en lugar de distribuirse. El volumen del video corto hace imposible la revisión humana de cada clip, por lo que la puerta de validación es clave para evitar que salidas defectuosas lleguen al público.

Lista de comprobación de costes, latencia y modos de fallo

La generación se mide por tarea y consume tiempo real, por lo que los problemas operativos son los mismos que en cualquier trabajo asíncrono costoso: cómo evitar ejecuciones desperdiciadas y cómo diagnosticar ejecuciones fallidas. Usa la siguiente lista de comprobación al solucionar problemas de ejecuciones fallidas de referencia a video.

Causas de entrada

• ¿El conjunto de referencias se puede analizar y es la versión que querías?
• ¿Las imágenes son consistentes en sujeto, estilismo y tratamiento de color?
• ¿La referencia de voz está limpia, sin música ni voz superpuesta, y no está vacía?
• ¿Las dimensiones, formatos y frecuencias de muestreo están dentro de los límites de la documentación?

Causas de la solicitud

• ¿El identificador de modelo está escrito exactamente como en la documentación y sigue siendo válido?
• ¿Los nombres de parámetros y los tipos de valor son válidos para este modelo?
• ¿El prompt está dentro del límite de longitud y describe la acción en lugar de volver a describir la identidad que ya cubren las referencias?
• ¿Has superado algún límite de concurrencia o de tasa impuesto por tu propia capa de cliente?

Causas de la respuesta

• ¿La solicitud tuvo éxito pero devolvió material que no pasó la puerta de validación? Revisa primero el recorte y la estabilidad del inicio del clip; ventanas de generación más largas suelen corregir clips que empiezan a mitad de una acción.
• ¿La salida se desvía del modelo respecto a las referencias? Casi siempre es un problema de consistencia de las referencias, no del prompt.
• ¿Ves tiempos de espera esporádicos? Añade seguimiento idempotente de trabajos para que los reintentos no se conviertan en facturación duplicada.

Higiene de costes y latencia

• No reintentes a ciegas. Reintenta solo ante errores de transporte o estados explícitamente reintentables. Un fallo de contenido volverá a fallar.
• Valida las entradas localmente. Cada error capturado localmente es una ejecución que no pagas.
• Mide la latencia tú mismo. Registra el tiempo desde el envío hasta la disponibilidad por modelo y configuración de parámetros en tu propia carga de trabajo, en lugar de asumir una cifra.
• Cachea activamente. Una salida aprobada puede servir muchas variantes posteriores; regenera la base solo cuando la referencia o la escena cambien realmente.
• Limita el radio de impacto. Los trabajos por lotes deben tener un umbral máximo de fallos que detenga la cola ante un fallo sistémico.

Coloca esta lista junto a los registros. La mayoría de las ejecuciones fallidas se clasifican en una de las tres ramas anteriores en menos de un minuto.

Integrarlo todo en una tubería repetible

El último paso es convertir el flujo de trabajo en un ciclo que genere clips de video corto bajo demanda a partir de plantillas y una biblioteca de referencias, con cada salida revisada realimentando la biblioteca.

El ciclo

La tubería tiene cuatro fases que se repiten:

1. Selección de plantilla + referencia. La plantilla guarda el esqueleto del prompt, los valores por defecto de los parámetros y la configuración de posprocesamiento. La biblioteca de referencias guarda los conjuntos de materiales versionados. Un trabajo empareja una de cada.
2. Generación. El constructor de solicitudes ensambla la llamada, el cliente la envía y el material devuelto llega al almacenamiento con metadatos de procedencia.
3. Revisión y posprocesamiento. Los clips pasan automáticamente la puerta de validación; cualquiera marcado pasa a revisión humana. Los clips aprobados continúan por recorte, reencuadre, normalización de audio y codificación.
4. Realimentación. Las notas estructuradas de la revisión —«deriva de voz», «iluminación inconsistente»— se convierten en cambios de la biblioteca de referencias o de la plantilla, no en ediciones ad hoc del prompt. Incrementa el número de versión para que los cambios sean rastreables.

Qué lo hace repetible

• Plantillas antes que prompts. Todo lo que se repite entre trabajos pertenece a una plantilla, no al código de cada ejecución.
• Versionar todo. Conjuntos de referencias, plantillas, identificadores de modelo, configuración de posprocesamiento. El registro de trabajos debe permitirte reconstruir con precisión lo que se ejecutó.
• Empaquetado determinista. Construye colas a partir de datos —hojas de cálculo de escenas, calendarios de contenido— y deja que la tubería las expanda en trabajos.
• La revisión como dato. Captura los resultados de revisión en almacenamiento estructurado para que puedas medir qué plantillas y conjuntos de referencias producen más clips aprobados.

Por dónde empezar

Empieza con una plantilla y un conjunto de referencias, ejecuta un lote pequeño y ajusta el conjunto de referencias antes de escalar. El valor de la tubería proviene del interés compuesto de la biblioteca de referencias con el tiempo: cada clip aprobado valida los materiales que lo sustentan, y cada clip rechazado señala con precisión qué hay que corregir.

Cuando estés listo para integrarte, consulta el identificador de modelo y la forma de la solicitud actuales en la documentación de HiAPI sobre vidu-q4-preview/reference-to-video, y mantén la selección de modelo en la configuración para que el resto de la tubería sobreviva al lanzamiento del próximo modelo.