Guía de uso
Crear videos cortos con veo-3.1-lite/text-to-video en la API de HiAPI
Un flujo de trabajo práctico para desarrolladores: guion gráfico de texto a video, audio nativo y elección de relación de aspecto
En esta página
Por qué los videos cortos hacen fracasar los prompts ingenuos de texto a video
Al entrar por primera vez en contacto con un modelo de texto a video, el instinto es escribir un prompt cinematográfico largo y esperar recibir un video terminado. Para una pieza corta de 30 segundos, este enfoque casi siempre decepciona, y la razón es estructural, no el grado de refinamiento del prompt.
Un único prompt exige al modelo mantener la continuidad a lo largo de todo el arco narrativo: la consistencia de los personajes, el movimiento de cámara, el ritmo y el audio deben permanecer coherentes durante toda la duración. Sin embargo, un video corto no es un plano secuencia continuo: es una serie de beats. Gancho, planteamiento, giro, cierre. Cada beat requiere una composición distinta, una energía distinta y, a menudo, una posición distinta del sujeto. Meterlos todos en un solo prompt hace que el modelo los promedie, y promediar es precisamente lo que destruye la retención de los videos cortos.
Otro modo de fracaso es el costo de iteración. Cuando un prompt genera un video largo y el tercer beat sale mal, solo puedes regenerar todo y rezar para que se conserve la parte que te gustaba. Es un ciclo lento y sin controles fiables.
El flujo de trabajo que adopta esta guía se basa en planos: descomponer el guion en planos discretos, enviar una solicitud de generación independiente por cada plano y mantener la continuidad en tus propios metadatos, no en el prompt. Cada sección posterior se apoya en esta descomposición: la estructura de la solicitud, la relación de aspecto, el audio y la iteración asumen que trabajas plano por plano.
Y aquí es donde veo-3.1-lite/text-to-video encaja de forma natural. Un modelo de texto a video más ligero es idóneo para generar muchos clips cortos y regenerables por separado, que es justo la forma de una línea de producción de videos cortos.
El cambio de modelo mental
Deja de tratar al modelo como un director que devuelve una película terminada. Trátalo como un renderizador de planos: tú aportas descripciones de plano con un alcance bien definido, él devuelve un clip, y tu línea de producción se encarga del orden, la mezcla de audio y el ritmo. Una vez clara esta división del trabajo, la mayoría de las decisiones restantes pasan a ser decisiones de ingeniería, no de escritura de prompts.
Planificar la lista de planos antes de llamar a la API
La lista de planos es el contrato entre el guion y las llamadas de generación. Escríbela como datos, no como prosa, para que tu línea de producción pueda recorrerla.
Parte del guion y divídelo en beats. Para videos cortos, una regla práctica es: un plano por cada frase o por cada idea visual, el que sea más corto. Si una frase necesita dos encuadres para expresarse con claridad, son dos planos. Si tres frases comparten un mismo visual continuo, pueden ser un solo plano, pero solo si la duración sigue cabiendo cómodamente en una generación.
Para cada plano, registra como mínimo:
- ID de plano: estable y legible por humanos, para el almacenamiento en caché y los reintentos.
- Prompt: la descripción visual, lo bastante autocontenida como para que el plano se sostenga de forma aislada.
- Duración: cuánto debe durar el plano en el montaje final.
- Relación de aspecto: decidida por canal y fijada antes de generar.
- Intención de audio: ambiente nativo, silencio que se sustituirá, o marcador de posición para la locución.
- Notas de continuidad: vestuario de los personajes, iluminación, ubicación y dirección en pantalla.
Sacar la continuidad de los prompts siempre que sea posible
Las notas de continuidad deben vivir en los metadatos, no repetirse palabra por palabra en cada prompt. Los prompts que llevan descripciones reutilizadas y extensas tienden a desviarse en cuanto a qué se enfatiza: un plano exagera el vestuario y el siguiente lo minimiza. Un patrón más limpio es tener un bloque de descripción breve y estable por cada personaje o ubicación, que tú (el autor de la línea de producción) ensamblas en cada prompt, de modo que la redacción sea idéntica entre planos aunque el prompt en sí sea distinto.
Un plano, una solicitud
Cada plano debería poder generarse en una sola llamada. Si un plano necesita más tiempo del que una generación puede cubrir cómodamente, divídelo en un punto de corte natural (una reacción, un movimiento de cámara, un silencio de un beat) en lugar de estirar la solicitud. Los planos más cortos además son más baratos de regenerar si uno sale mal, y ese es precisamente el sentido de la descomposición.
Mantén la lista de planos en control de versiones junto con el guion. Cuando el guion cambie, el diff te dirá exactamente qué planos hay que re-renderizar.
Construir las solicitudes de generación en la línea de producción
Con la lista de planos como datos, la capa de solicitudes se convierte en un envoltorio fino: lee un plano, construye la solicitud para veo-3.1-lite/text-to-video, llama a la API de HiAPI y guarda el resultado indexado por el ID del plano.
A alto nivel, una llamada de generación transporta la misma información que el registro del plano: el texto del prompt, la duración prevista y la relación de aspecto. Los nombres exactos de los parámetros y los valores aceptables los define la referencia de la API del modelo en HiAPI, así que toma la documentación del endpoint como fuente de verdad y haz que los valores predeterminados del envoltorio coincidan con ella, en lugar de codificar supuestos en muchos lugares.
Un envoltorio reutilizable
La forma que sigue es deliberadamente pseudocódigo neutral respecto al lenguaje: el valor está en la estructura, no en la sintaxis:
function renderShot(shot, attempt):
request = {
model: "veo-3.1-lite/text-to-video",
prompt: buildPrompt(shot),
duration: shot.duration,
aspect_ratio: shot.aspectRatio
}
response = hiapi.generate(request)
save(shot.id, attempt, response)
return response
Tres características hacen que valga la pena tener este envoltorio:
- Cada llamada se indexa por ID de plano e intento. Cuando el cuarto plano falla, sabes exactamente qué artefacto sustituir y qué intentos fallaron.
- El prompt se construye, no se pega.
buildPromptcombina la descripción propia del plano con los descriptores estables de personajes y ubicaciones de los metadatos, de modo que la redacción de continuidad sea consistente entre planos. - Las fases posteriores no dependen del éxito de la primera llamada. El envoltorio devuelve una referencia a un artefacto; el ensamblador lee lo que esté aprobado actualmente para cada plano.
En la práctica, la generación es asíncrona
Trata la generación como una tarea de larga duración, no como una llamada síncrona dentro del manejador de solicitudes. Envía la tarea, persiste la referencia y consulta o espera su finalización en un proceso de trabajo. Así, los reintentos, los límites de concurrencia y los fallos parciales quedan bajo tu control, sin enredarse con el ciclo de vida de las solicitudes de la aplicación.
El ensamblaje es una fase independiente
No generes y ensambles en un mismo paso. Renderiza todos los planos aprobados, guárdalos y luego ejecuta un proceso de ensamblaje separado: ordenar por ID de plano, concatenar, aplicar transiciones (si las hay) y mezclar el audio. Mantener el ensamblaje aparte significa que re-renderizar un plano solo requiere volver a ejecutar el ensamblaje, sin regenerar nada.
Elegir la relación de aspecto y la longitud de clip según el canal
La relación de aspecto y la duración deben decidirse desde el canal de distribución hacia dentro, antes de que ocurra cualquier generación, y no ajustarse a posteriori. Recortar clips terminados a encuadres distintos es la forma más habitual de desperdiciar renderizados.
Relación de aspecto
Elige un encuadre principal por canal y mantenlo en toda la pieza. Mezclar relaciones de aspecto dentro de un mismo video corto arruina la experiencia de visualización en cada plataforma.
- Vertical: la opción predeterminada para las interfaces de videos cortos con desplazamiento en el feed. Compón para un encuadre alto: el sujeto centrado o ligeramente elevado, con márgenes de seguridad arriba y abajo para las superposiciones de la interfaz.
- Horizontal: para reproductores incrustados, videos principales del sitio web y presentaciones en las que el espectador está quieto.
- Cuadrado: se usa ocasionalmente en diseños de cuadrícula; trátalo como una elección deliberada, no como un recurso de última instancia.
La implicación práctica para tu lista de planos: componer en vertical cambia lo que cabe en el encuadre. Un plano general de establecimiento que funciona en horizontal puede volverse irreconocible al comprimirse a un encuadre alto. Decide primero la proporción y luego escribe los planos compuestos para ella.
Longitud del clip
La longitud del clip la dicta el ritmo, no cuánto puede generar como máximo el modelo. Algunas pautas:
- El gancho debe ser corto. El primer plano suele decidir si se gana o se pierde la atención; mantenlo compacto y visualmente inequívoco.
- Una idea por clip. Si un plano contiene dos eventos visuales distintos, sepáralos. Los clips más cortos también te dan un control más fino del ritmo final en el montaje.
- Deja margen de recorte. Genera un poco más de lo necesario para el punto de corte objetivo y recorta durante el ensamblaje. Recortar es gratis; regenerar no.
- Contrasta con los totales de la plataforma. La duración total es la suma de los planos. Suma las duraciones previstas antes de generar y comprueba que la secuencia encaja en la ventana de consumo típica de ese canal; reequilibrar la lista de planos es mucho más fácil que volver a renderizar.
Genera una sola vez por proporción
Si de verdad necesitas la misma pieza en dos encuadres, trátalos como dos entregables independientes, cada uno con su propia lista de planos. Compartir prompts está bien; compartir renderizados no, porque la composición es distinta. Codificar la relación de aspecto en los metadatos del plano lo deja explícito y evita reutilizaciones accidentales entre canales.
Combinar el audio nativo con la locución
veo-3.1-lite/text-to-video puede generar audio nativo junto con la imagen, y ese audio es realmente útil: ambientes, texturas ambientales y sonidos diegéticos sencillos dan al clip una presencia que el silencio no tiene. El error está en dejar que tanto el audio nativo como tu propia locución intenten desempeñar el mismo papel.
La división del trabajo que funciona es: el audio nativo aporta el mundo y la locución aporta la información. Si la pista nativa ya contiene algo parecido a voz o una base musical intensa, chocarás con ella al mezclar. Decide plano por plano qué pista domina.
Orden de la mezcla
- Coloca primero la locución. Los tiempos de la narración vienen fijados por el guion; todo lo demás se adapta a ellos.
- Pon el audio nativo debajo. Cuando la pista nativa es ambiente o textura, mantenla audible pero en un papel subordinado.
- Baja el volumen, no lo elimines. Reduce la pista nativa bajo la narración en lugar de cortarla del todo: un silencio repentino entre frases suena antinatural. Suaviza las transiciones de ganancia en cada límite de plano.
- Normaliza al final. Mezclar plano por plano y luego concatenar produce saltos de nivel. Ejecuta un procesamiento final una sola vez sobre la pieza ensamblada.
Cuándo silenciar la pista nativa
Silénciala, o regenera el plano con una intención de audio más clara, en estos casos:
- El audio nativo contiene voz inteligible que compite con tu narración.
- La textura no encaja con la escena (por ejemplo, un ambiente de interior en un plano exterior).
- Musicalizas toda la pieza con una base musical continua y el ritmo propio de la pista nativa choca con ella.
Esto suele detectarse plano por plano, otra razón para mantener los planos independientes: puedes regenerar el audio de un plano sin tocar el resto.
Escribir la intención de audio en la lista de planos
Añade a cada plano un campo de audio explícito: native_ambience, silent o voiceover_covered. Te obliga a tomar la decisión antes de generar e indica a la fase de ensamblaje qué planos necesitan bajar el volumen y cuáles solo necesitan descartar la pista nativa.
Controlar la calidad y el costo a lo largo de varios intentos
La disciplina de iteración es lo que distingue una línea de producción que converge de una que quema renderizados. La buena noticia es que la generación basada en planos hace que los buenos hábitos sean naturales.
Regenera solo planos individuales, nunca la secuencia
Cuando un beat sale mal, sustituye ese plano. Tu envoltorio indexa los resultados por ID de plano e intento, así que la corrección consiste en lanzar un nuevo intento para un ID y volver a ejecutar el ensamblaje. Si te descubres re-renderizando varios planos para arreglar uno, probablemente la lista de planos sea demasiado gruesa: divídela más.
Cachea de forma agresiva los clips aprobados
Una vez aprobado un plano, trátalo como inmutable, guárdalo de forma persistente e indexa por el ID del plano más un hash de su prompt y sus parámetros. Al volver a ejecutar la línea de producción se salta todo lo que no haya cambiado. Esto importa sobre todo durante el trabajo de audio y ritmo, cuando iteras la mezcla con la imagen fija.
Cambia solo una variable por intento
Cuando un plano no cumple lo esperado, ajusta una sola cosa (la especificidad del prompt, la duración o la composición) y vuelve a generar. Cambiar tres variables a la vez no te dirá qué corrección funcionó, y volverás a aprender la misma lección en el siguiente plano.
Fija la receta antes de escalar los intentos
Lleva una secuencia completa a un estado que te satisfaga y úsala como plantilla para variantes: ganchos alternativos, distintas llamadas a la acción. Como la lista de planos son datos, una variante es solo un diff pequeño, no un proyecto nuevo.
Presupuesta por número de planos, no por minutos de metraje final
La unidad de trabajo es el plano, así que la unidad de iteración también es el plano. Antes de generar un lote, calcula el número de planos y los intentos previstos por plano. Esa cifra, junto con la base de facturación del modelo, es tu número de planificación: consulta las tarifas actuales en el panel de precios de HiAPI en lugar de reutilizar supuestos obsoletos.
Revisa al tamaño final
Examina cada plano en la relación de aspecto real y en la pantalla en la que lo verá el espectador. Un problema invisible en horizontal en el escritorio resulta evidente en un feed vertical. Detectarlo en la revisión es mucho más barato que detectarlo después de publicar.
Diagnosticar problemas de generación habituales
Cuando un plano vuelve inservible, ejecuta estas comprobaciones en orden. Cubren la gran mayoría de los fallos, y las dos primeras resuelven la mayor parte.
1. Especificidad del prompt
¿Es autocontenido el prompt? ¿Describe el sujeto, la acción, la composición y la iluminación, o depende del contexto de los planos vecinos? El prompt de un plano debe sostenerse por sí solo: el modelo solo ve lo que le envías. Las descripciones vagas del sujeto provocan deriva; los prompts sobrecargados producen una papilla. El objetivo es un sujeto claro y una acción clara por plano.
2. Longitud del plano
¿Está haciendo demasiadas cosas el plano para su duración? Si un prompt sugiere varios eventos visuales en un clip corto, el modelo los comprime. Divide el plano o alárgalo. A la inversa, los planos con muy poco contenido para su duración tienden a ir sin rumbo: recórtalos.
3. Desajuste de relación de aspecto
¿Escribiste el prompt para el encuadre que realmente solicitas? Una descripción amplia y horizontal en un encuadre vertical produce recortes incómodos y espacio muerto. Comprueba que la descripción visual del plano coincide con su relación de aspecto y que ninguna otra fase de la línea de producción lo esté recortando en silencio.
4. Conflicto de audio
Si la imagen está bien pero el resultado se siente mal, escucha la pista nativa por separado. Una voz que compite, un ambiente equivocado o un ritmo intenso bajo la narración suelen ser un problema de audio, no visual. Soluciónalo silenciando la pista nativa o ajustando la intención de audio del plano y vuelve a mezclar: no hace falta regenerar la imagen.
5. Errores de línea de producción y de parámetros
Si la generación falla directamente o devuelve algo incoherente con la solicitud, valida los parámetros con la documentación del endpoint en HiAPI: identificador del modelo bien escrito, valores de duración y relación de aspecto dentro de los rangos aceptables, prompt no vacío. Son errores aburridos, pero habituales en envoltorios que codifican valores predeterminados en varios lugares; esa es la razón de mantener la construcción de la solicitud en una sola función.
6. Deriva de continuidad entre planos
Si cada plano parece correcto pero la secuencia no mantiene la coherencia, el problema está en los metadatos, no en la generación. Compara el texto ensamblado del prompt de cada plano: si los descriptores de personajes o ubicaciones tienen una redacción distinta, alinéalos en un bloque de descriptores compartido y regenera solo los planos que se desvían.
Recorre la lista en orden y anota qué comprobación resolvió cada fallo. Después de unas cuantas secuencias sabrás qué comprobaciones dominan en tu contenido y el diagnóstico se convertirá en un barrido rápido en lugar de una reconstrucción. Puedes empezar a renderizar planos con veo-3.1-lite/text-to-video a través de la API de HiAPI, dejar que el panel de precios se encargue de los números y centrarte en la secuencia.
Artículos relacionados
Ver todos los artículos →-
Guía de uso
Guía de inicio con gpt-6.2-sol: límites de capacidad, integración vía API y consideraciones sobre el precio por token
Puntos clave de decisión e implementación de la integración para equipos de ingeniería
-
Guía de uso
Guía de inicio de gpt-6.2-astra: límites de capacidad del modelo de texto, puntos clave de integración y control de costes
-
Guía de uso
Guía de inicio de Tripo H3.1: cómo elegir entre tres modos de entrada, parámetros y precios
Guía práctica de decisiones de integración y control de costes de la generación 3D para desarrolladores