Crear videos cortos con flux-3-max/text-to-video en la API de HiAPI

Por qué el video corto es un problema de orquestación de prompts

La mayoría de los equipos que fracasan con la generación de video a partir de texto lo hacen por la misma razón: escriben un prompt enorme que describe toda la escena y esperan que el modelo devuelva un video terminado de treinta segundos. La generación no funciona así. El modelo produce una sola toma continua por llamada, y cada llamada es una pequeña decisión autocontenida sobre sujeto, acción, composición y sonido.

El modelo mental que resiste es el de orquestación. No estás prompteando un video; estás dirigiendo una serie de tomas y luego ensamblándolas. Una pieza de video corto —un avance de producto, un gancho para redes, una explicación con voz en off— suele constar de entre cuatro y ocho tomas. Cada toma asume una sola tarea: establecer, mostrar, transicionar, cerrar. Una vez que aceptas esta descomposición, la API deja de ser una máquina tragamonedas y pasa a ser un paso de renderizado dentro de un pipeline que tú controlas.

Esto importa porque los modos de falla de la generación de video a partir de texto son en su mayoría fallas de continuidad, no de calidad. Una toma individual puede verse hermosa, pero si la siguiente toma tiene un personaje distinto, una dirección de luz diferente o una cámara que de repente se desplaza, esa toma sigue siendo inservible. Estos problemas se resuelven antes de enviar la solicitud, según cómo planifiques y describas las tomas, no añadiendo adjetivos a un prompt gigante.

El resto de esta guía te lleva de extremo a extremo por ese flujo de trabajo, llamando a flux-3-max/text-to-video a través de HiAPI: dividir el guion en tomas, escribir prompts por toma, tratar el movimiento de cámara como una dimensión controlada, usar audio nativo para saltarse un procesamiento de audio separado y envolver todo en un bucle de solicitudes pequeño y reproducible.

Planificar las tomas antes de llamar a la API

Antes de escribir código, convierte el guion en una lista de tomas. Una lista de tomas es una estructura de datos pura: un elemento por llamada de generación, cada uno con un propósito claro. Esta estructura funciona bien como representación intermedia:

[
  {
    "id": "s1",
    "role": "establish",
    "subject": "ceramic pour-over coffee dripper on a wooden counter",
    "framing": "medium close-up, three-quarter angle",
    "durationIntent": "short",
    "camera": "slow push in",
    "audio": "quiet room tone, soft steam"
  },
  {
    "id": "s2",
    "role": "demonstrate",
    "subject": "hot water spiraling over coffee grounds",
    "framing": "tight overhead macro",
    "durationIntent": "short",
    "camera": "locked off",
    "audio": "water pouring, gentle hiss"
  }
]

Algunas reglas de planificación que te ahorrarán reintentos después:

• Una idea por toma. Si tu descripción de toma incluye «y luego», divídela. El modelo maneja mucho mejor una sola acción continua que una cadena de beats.
• Expresa la intención de duración, no los segundos exactos. Decide si una toma es un corte rápido o una pausa más larga y exprésalo como intención. Los puntos temporales exactos pertenecen a tu fase de edición/ensamblaje, donde obtienes control con precisión de fotograma.
• Fija pronto el vocabulario de composición. Elige términos como wide, medium, close-up, overhead, low angle y reutilízalos literalmente en todas las tomas. Un vocabulario consistente produce resultados más consistentes.
• Planifica anclas de continuidad. Decide qué se mantiene constante: descripción del personaje, vestuario, paleta de color, hora del día, dirección de la luz. Escríbelo una vez como prefijo compartido y reutilízalo en cada prompt.
• El orden importa al revisar. Genera en orden de guion para que puedas revisar en el orden de reproducción final, en lugar de ver los clips como fragmentos aislados.

Una vez que existe la lista de tomas, la llamada a la API se vuelve mecánica, que es exactamente lo que quieres, porque hace que las llamadas sean reintentables y reproducibles.

Escribir prompts por toma para flux-3-max/text-to-video

Un buen prompt por toma tiene estructura, no es conversacional. En lugar de escribir una larga cadena de formato libre, compón cada prompt a partir de un pequeño número de secciones etiquetadas. Esto hace que los prompts sean comparables, reutilizables y fáciles de ajustar cuando falla un solo elemento.

La estructura de cinco secciones

1. Sujeto — quién o qué es, con los detalles de continuidad que hayas decidido (apariencia, vestuario, rasgos del producto).
2. Acción — un único movimiento o estado continuo, descrito en presente.
3. Entorno — lugar, hora del día, calidad de la luz, paleta de color.
4. Cámara — composición más movimiento, usando tu vocabulario fijo. La siguiente sección lo desarrolla.
5. Audio — la intención de ambiente y foley de esta toma.

Combínalas en un orden fijo para que tu propia depuración también sea consistente:

CONTINUITY = (
    "a minimalist ceramic pour-over coffee dripper, matte white, "
    "on a warm oak counter, soft morning window light from the left, "
    "muted natural palette"
)

def shot_prompt(subject, action, setting, camera, audio):
    return (
        f"{subject}. {action}. {setting}. "
        f"Camera: {camera}. Audio: {audio}."
    )

prompt = shot_prompt(
    subject=f"{CONTINUITY}",
    action="steam rising steadily as water slowly blooms the coffee grounds",
    setting="kitchen counter at dawn, shallow depth of field",
    camera="medium close-up, slow push in, no shake",
    audio="quiet room tone, soft water pour, faint steam hiss",
)

Mantener las tomas visualmente consistentes

El único hábito con mayor apalancamiento es el bloque de continuidad compartido. Colócalo al principio de cada sección de sujeto y mantenlo idéntico en todas las tomas de la secuencia. Cuando una toma se desvía visualmente, puedes bisecar el problema: ¿es el bloque de continuidad o la acción específica de la toma?

Hay dos hábitos más que reducen la deriva:

• Evita adjetivos contradictorios. «cinematic documentary handheld static» son tres instrucciones en conflicto. Elige una.
• Describe la luz una sola vez. Si el bloque de continuidad dice luz matinal desde la izquierda, no dejes que tomas posteriores introduzcan un fluorescente cenital, a menos que ese cambio sea intencional.

Qué omitir de los prompts

Deja la relación de aspecto, la longitud de salida y otros parámetros técnicos fuera de la descripción textual y pásalos como parámetros de la solicitud cuando la API los exponga. La descripción textual dice qué es la toma; los parámetros dicen cómo se entrega. Mezclar ambos hace que ambos sean más difíciles de modificar.

Controlar el movimiento de cámara

El movimiento de cámara es la dimensión que más fácilmente se deja al azar y la que más afecta a si una secuencia se siente dirigida. Si no lo especificas, el modelo moverá la cámara de alguna manera; el movimiento no especificado se manifiesta como deriva, y la deriva es exactamente lo que hace que el material generado parezca filmado por accidente.

Trata el movimiento como un pequeño vocabulario cerrado

No improvises lenguaje de cámara para cada toma. Define un pequeño conjunto de movimientos y reutilízalos:

• Fijo — sin movimiento. La opción más segura para detalles de producto y primeros planos.
• Acercarse / alejarse — moverse hacia el sujeto o alejarse de él. Adecuado para énfasis y revelación.
• Paneo a la izquierda / paneo a la derecha — rotación horizontal. Útil para establecer el espacio.
• Inclinación hacia arriba / inclinación hacia abajo — rotación vertical. Úsalo con moderación; se lee como dramático.
• Toma de seguimiento — moverse con el sujeto. Requiere un sujeto claramente en movimiento como ancla.

Escríbelos en la sección de cámara, seguidos de una instrucción negativa que suprima el resto del movimiento: Camera: slow push in, no shake, no handheld drift.

La cláusula negativa importa. Decir solo «push in» deja espacio para que el modelo añada temblor; decir «push in, no shake» acota el rango.

Haz que el movimiento sirva al rol de la toma

El movimiento debe servir al montaje. Un mapeo práctico:

• Toma de establecimiento — un movimiento claro (acercamiento lento o paneo suave) que dé a la mirada un punto de aterrizaje.
• Toma de detalle — fija. El detalle ya es visualmente denso; el movimiento competiría con él.
• Transición — movimiento consistente entre tomas adyacentes (ambas se acercan, ambas panean en la misma dirección) para que el corte se sienta intencional incluso sin un efecto de transición.
• Toma principal — un movimiento deliberado, nunca dos combinados.

Un solo movimiento por toma

Los movimientos combinados («paneo a la derecha mientras te acercas y te inclinas hacia arriba») producen resultados turbios. Si un beat necesita un movimiento de cámara complejo, divídelo en dos tomas. Tu fase de ensamblaje puede unirlas y aun así mantienes control con precisión de fotograma sobre el corte.

Consistencia de movimiento en la secuencia

Decide de antemano el movimiento dominante de toda la pieza —por ejemplo, «todas las tomas se acercan lentamente»— y desvíate solo cuando necesites un efecto. Una secuencia con dirección de movimiento consistente se lee como intencionada; una con movimiento aleatorio se lee como generada.

Usar audio nativo en el pipeline

La generación de audio nativo cambia la arquitectura del pipeline de video corto. En un flujo tradicional, generas video mudo y luego ejecutas un procesamiento de audio separado —ya sea un modelo de texto a audio, o una biblioteca con licencia de foley y música— y después alineas ambos en un editor. Cada etapa es otro servicio, otras credenciales, otro modo de falla y otro lugar donde puede ocurrir un desajuste temporal.

Cuando el modelo de video genera audio en línea, el sonido y la imagen se producen en el mismo paso de inferencia, por lo que se alinean de forma natural con lo que ocurre en pantalla. En el momento en que se vierte el agua, el sonido del vertido coincide con la acción de verter. Esto elimina prácticamente todo el trabajo de alineación.

Dos pipelines, una diferencia

Separate audio stage:            Native audio:
  shot -> video (silent)           shot -> video + audio
       -> audio generation              -> assemble
       -> alignment / mixing
       -> assemble

El beneficio práctico es tener menos piezas móviles. La restricción práctica es que necesitas planificar el sonido en el prompt, no añadirlo después.

Planifica las tomas en torno al sonido

Como el audio es parte de la generación, escríbelo como parte de la toma, no como un añadido posterior:

• Nombra el sonido dominante. Audio: water pouring, gentle hiss es mejor que Audio: pleasant kitchen sounds.
• Mantén la escasez. Uno o dos elementos claros por toma. Las descripciones de audio en capas suelen volverse indistinguibles.
• Decide la música a conciencia. Si planeas colocar una pista musical de fondo sobre toda la pieza en el editor, deja que el audio de la toma sea solo ambiente para que no compita con la pista de música.
• Considera la continuidad del sonido. Al igual que la continuidad visual, la continuidad de audio entre cortes ayuda: el mismo tono de sala en tomas adyacentes hace que una secuencia se sienta como si ocurriera en el mismo lugar.

Dónde sigue ganando el editor

El audio nativo no reemplaza al editor. Reemplaza el paso de alineación. Todavía necesitas la normalización final de sonoridad y, si usas música, una etapa de mezcla que baje el diálogo y el foley bajo la pista de fondo. Presupuesta esto en tu pipeline, pero mucho menos que con una etapa de generación separada.

Una solicitud funcional y el flujo de ensamblaje

Con la lista de tomas y el constructor de prompts, la capa de solicitudes es fina. Las decisiones clave son: cómo llamar al modelo, cómo manejar el orden y los reintentos, y cómo entregar los resultados al ensamblaje.

Bucle de orquestación

import time

SHOTS = [
    # your planned shot list from the earlier step
]

def generate_shot(shot, attempt=0):
    payload = {
        "model": "flux-3-max/text-to-video",
        "prompt": build_prompt(shot),
        # pass delivery parameters here, not in the prose:
        # aspect ratio, length, etc. per the API reference
    }
    try:
        return client.generate(payload)
    except TransientError:
        if attempt >= 3:
            raise
        time.sleep(2 ** attempt)
        return generate_shot(shot, attempt + 1)

def run_sequence(shots):
    results = {}
    for shot in shots:
        results[shot["id"]] = generate_shot(shot)
    return [results[s["id"]] for s in shots]

Tres cosas hacen que este bucle sea seguro para producción y no solo una demostración:

• Iteración ordenada. Generar en orden de guion significa que una falla parcial deja un prefijo que puedes revisar, y volver a ejecutar solo las tomas faltantes es directo.
• Resultados almacenados por clave. Guarda las salidas por id de toma, no por posición en la lista. Si la tercera toma falla y se regenera, sobrescribes por clave en lugar de volver a añadir.
• Reintentos acotados con retroceso. Las fallas transitorias son normales en cualquier API de generación. Limita el número de reintentos para que una sola toma mala no bloquee toda la tarea.

Entrega al ensamblaje

Tu bucle de generación debería producir un manifiesto —la lista de tomas con referencias a las salidas— y detenerse ahí. El ensamblaje es un paso independiente que consume ese manifiesto: recorta cada clip a la duración prevista, aplica transiciones, coloca la pista musical de fondo y normaliza la sonoridad.

{
  "sequence": [
    {"id": "s1", "clip": "out/s1.mp4", "trim": "keep_first_portion"},
    {"id": "s2", "clip": "out/s2.mp4", "trim": "keep_first_portion"}
  ],
  "audioStrategy": "native_bed_plus_music"
}

Separar la generación del ensamblaje es lo que hace que todo el pipeline sea reproducible: puedes regenerar una toma, colocarla en el manifiesto y volver a renderizar el corte final sin tocar nada más.

Lista de verificación de producción y errores comunes

Un pipeline de video corto es fiable cuando la parte aburrida se vuelve aburrida. Antes de escalar el volumen, revisa estas comprobaciones.

Consistencia

• El bloque de continuidad es idéntico en cada toma de una secuencia.
• El vocabulario de cámara es cerrado y se reutiliza, no se improvisa.
• La dirección de la luz y la paleta de color se declaran una vez y no se contradicen después.
• Revisa las tomas en orden: los problemas de continuidad no se ven cuando los clips se miran aislados.

Reintentos e idempotencia

• Los resultados se indexan por id de toma, de modo que regenerar sobrescribe en lugar de duplicar.
• Los reintentos están acotados y usan retroceso; una toma que falla de forma permanente debe fallar de forma visible, no silenciosa.
• El manifiesto de tomas es la única fuente de verdad de lo que se generó; persístelo junto con las salidas.

Control de costos

La generación se factura según el trabajo que produce el modelo, así que tu principal palanca es cuántas tomas generas y cuántas veces las regeneras. Controles prácticos: fija la lista de tomas antes de generar, revisa una toma representativa de cada secuencia antes de renderizar el resto y evita relanzamientos especulativos de tomas que ya pasaron la revisión. Consulta el precio vigente en el panel de precios del sitio al planificar el volumen.

Revisión de salidas

• Mira cada secuencia de principio a fin a velocidad de reproducción real, no clip por clip.
• Comprueba el audio contra la imagen: ¿coincide el sonido con ese momento?
• Revisa especialmente los dos primeros segundos: ahí es donde se gana o se pierde la atención en video corto.
• Mantén un pequeño conjunto de prompts de referencia que sabes que funcionan y compara las salidas nuevas con ellos cuando la calidad parezca bajar.

Errores comunes

• Prompts gigantes. Un prompt que describe toda la escena produce una toma larga y desenfocada. Divídela.
• Escribir la duración en la descripción textual. Expresa los puntos temporales en la fase de edición, no en el texto del prompt.
• Movimiento de cámara aleatorio. El movimiento no especificado deriva; especifica el movimiento y suprime el resto.
• Tratar el audio como una decisión de producto independiente. Planifica el sonido en la toma y mézclalo después en el editor.

El flujo de trabajo de esta guía —planificar tomas, estructurar prompts, controlar el movimiento de cámara, usar audio nativo, orquestar con un manifiesto— convierte a flux-3-max/text-to-video de un generador impredecible en un paso de renderizado fiable dentro de un pipeline que tú posees.