Añadir texto a vídeos mediante API: flujo de trabajo de subtítulos y superposiciones

Por qué el texto en vídeo es un problema de diseño de API, no solo un prompt

Añadir texto a un vídeo generado parece tan simple como cambiar una línea del prompt: describes los subtítulos, envías la solicitud y obtienes un clip con texto. Pero en la práctica, en cuanto necesitas que los subtítulos sean legibles, estén sincronizados en el tiempo, se puedan localizar o reutilizar entre escenas, el prompt deja de ser la parte interesante. La arquitectura lo es.

Hay dos caminos viables, y conducen a bases de código distintas:

• Texto nativo en el momento de la generación. Haces que el modelo de vídeo renderice el texto como parte de la escena. Una solicitud, un recurso, sin posprocesamiento.
• Material limpio más superposiciones. Primero generas el material sin texto (o pides una composición sin texto) y luego sintetizas los subtítulos y las superposiciones en un segundo paso de renderizado.

¿Por qué esto no es solo una cuestión estética? Porque todo lo que ocurre aguas abajo depende de esta elección. Si el texto está en los píxeles generados, no puedes fácilmente rediseñar su estilo, traducirlo, alinear su temporización con la voz ni corregir una errata sin volver a generar el clip. Si el texto está en una superposición separada, controlas el diseño, la tipografía y la temporización, pero ahora tienes que encargarte tú mismo de un renderizador y añadir una solicitud más a la cadena de procesamiento.

El resto de esta guía trata el texto en vídeo como lo que suele acabar siendo en producción: un problema de datos (qué texto, dónde, cuándo) más un problema de renderizado (quién lo dibuja). Una vez separas ambas cosas, la llamada a la API se vuelve directa y puedes cambiar de backend de generación sin reescribir la lógica de subtítulos.

Un modelo mental útil es distinguir siempre tres cosas: el contenido (el texto en sí), la temporización (cuándo aparece) y la presentación (tipografía, posición, estilo). La generación nativa comprime las tres en un paso opaco. Las superposiciones mantienen las tres explícitas y editables. Ninguna es universalmente mejor; el objetivo es saber a cuál te comprometes antes de escribir la integración.

Ruta uno: texto en pantalla nativo mediante prompts en el momento de la generación

El texto nativo significa que el modelo de generación dibuja los caracteres dentro de los fotogramas del vídeo. Obtienes un único recurso de salida con el texto ya incrustado, y la cadena de procesamiento se mantiene corta: construir el prompt, enviar, consultar el estado, entregar.

Qué incluir en el prompt

La tipografía que renderiza el modelo es menos predecible que el texto compuesto, así que trata el prompt como una instrucción estrecha, no como el lugar donde describir todo un sistema de diseño. Consejos prácticos:

• Mantén el texto breve. Unas pocas palabras por plano. Las frases largas tienden a provocar derivas ortográficas y composiciones abarrotadas.
• Entrecomilla las cadenas literales. Si el texto debe aparecer exactamente, ponlo entre comillas y pide ese texto exacto. Las descripciones vagas producen resultados vagos.
• Especifica posición y estilo explícitamente. «Texto blanco grande centrado en el tercio inferior» es ejecutable. «Un título bonito» no lo es.
• Un elemento de texto por plano. Pedir título, subtítulo y marca de agua en el mismo clip multiplica los modos de fallo.
• Indica el idioma. Si el texto no está en inglés, indícalo, porque la cobertura de glifos varía.

Qué esperar de vuelta

Trata la salida como un borrador, no como una especificación. Incluso los buenos resultados pueden presentar glifos deformados, espaciado inconsistente u oclusiones parciales por el movimiento. Revisa siempre los fotogramas renderizados antes de entregar; una comprobación programática barata más un vistazo humano a los fotogramas con texto iniciales y finales atrapa la mayoría de los problemas.

Cuándo gana esta ruta

El texto nativo es la opción predeterminada correcta cuando el texto es incidental y ambiental: rótulos en una calle de fondo, un logotipo estilizado en un producto, una tarjeta de título breve que estás dispuesto a regenerar si sale mal. También gana cuando realmente no puedes permitirte un segundo paso de renderizado, por ejemplo en un flujo de entrega ajustado donde una solicitud por clip es el presupuesto.

El coste es el control. Cualquier cambio en la redacción, el estilo o la temporización implica una nueva solicitud de generación, y los resultados no son deterministas entre reintentos. Diseña tus prompts y tu almacenamiento para que los clips regenerados sustituyan limpiamente a los antiguos.

Ruta dos: generar material limpio y componer el texto tú mismo

La ruta de superposiciones divide el trabajo en dos. Primero generas material deliberadamente sin texto. Luego compones los subtítulos y las superposiciones encima, usando un servicio de renderizado o tu propia cadena de procesamiento multimedia.

Primero genera material limpio

Pide una composición sin texto: describe la escena, el sujeto, el movimiento de cámara y la iluminación, y evita explícitamente solicitar texto en pantalla. Si el modelo tiende a inventar rótulos o texto de interfaz, menciona que la imagen debe contener texto ilegible. La salida aquí es un material base: una entrada estable que puedes reutilizar en muchas variantes de texto.

Composición posterior

El paso de superposición consume dos entradas: el material base y una carga estructurada de subtítulos/superposiciones. Como controlas el renderizador, obtienes propiedades que el prompt no puede garantizar:

• Tipografías y tamaños deterministas. La misma carga se renderiza de forma idéntica cada vez, lo cual importa para la coherencia de marca.
• Temporización precisa. Los subtítulos pueden alinearse con precisión de fotograma a la voz, al ritmo musical o a los cambios de escena.
• Zonas seguras y reglas de composición. Puedes imponer márgenes, evitar rostros y sujetos clave, y mantener el texto dentro de las zonas seguras específicas de cada plataforma.
• Iteración barata. Corregir una errata o traducir los subtítulos es volver a renderizar la superposición, no regenerar el vídeo.
• Componibilidad. Marcas de agua, tercios inferiores y subtítulos pueden apilarse de forma independiente y activarse o desactivarse por salida.

Compensaciones

La ruta de superposiciones cambia dependencia del modelo por complejidad de la cadena de procesamiento. Añades una segunda solicitud, necesitas algún lugar donde almacenar el material intermedio y te haces cargo de la configuración del renderizado. A cambio, el texto se convierte en datos que puedes versionar, probar y sustituir. Para cualquier cosa con necesidades reales de subtítulos —subtítulos de accesibilidad, variantes multilingües, formatos sociales con plantilla—, este intercambio casi siempre merece la pena.

Un patrón práctico es renderizar las superposiciones sin destruir nada: trata el material base y la carga de subtítulos como la única fuente de verdad, y el vídeo compuesto como un derivado que siempre puedes regenerar.

Diseñar una carga de subtítulos que sobreviva a ambas rutas

Si diseñas bien los datos de subtítulos, la elección entre generación nativa y superposiciones se convierte en un detalle de renderizado, no en una reescritura. El objetivo es una única carga que pueda tanto serializarse en un prompt para texto nativo como alimentar un renderizador para superposiciones.

Campos esenciales

Modela cada elemento de texto como un objeto, manteniendo separados contenido, temporización y presentación:

{
  "track": "captions",
  "items": [
    {
      "text": "Everything you need to know",
      "start": 0.0,
      "end": 2.4,
      "style": { "role": "title", "align": "center", "position": "lower_third" },
      "lang": "en"
    }
  ]
}

Decisiones de diseño clave:

• Tiempo en segundos, como flotantes. Usa una única base temporal en todo el proyecto y conviértela a fotogramas solo al renderizar.
• Estiliza por rol, no por valores absolutos. Nombra roles como title, caption y lower_third, y resuélvelos a tipografías y tamaños en el renderizador. Esto hace que la carga sea portable entre formatos.
• Nombres de pista. Separa las pistas captions, titles y watermark para poder activarlas o desactivarlas por salida.
• Etiqueta de idioma por elemento. Tanto la selección de tipografía como los canales de traducción posteriores la necesitan.
• Nada de información de presentación incrustada en el campo de texto. Nunca metas indicaciones de estilo dentro del texto; para eso está el objeto de estilo.

Alimentar ambas rutas desde un solo esquema

Para la generación nativa, escribe un pequeño adaptador que seleccione los elementos más importantes y los convierta en instrucciones del prompt: el texto literal, su posición y un descriptor de estilo. Haz que este adaptador sea deliberadamente con pérdida: el renderizado nativo no puede seguir una pista completa de subtítulos de todos modos.

Para las superposiciones, pasa la carga al renderizador, que resuelve roles y posiciones y dibuja cada elemento dentro de su ventana temporal.

La recompensa: tu código de aplicación construye un objeto de subtítulos, y cambiar de nativo a superposición (o volver atrás para un clip concreto) es un cambio de configuración, no una migración de datos.

Una solicitud de superposición funcional, paso a paso

Aquí está la secuencia de la ruta de superposiciones, expresada como pasos con forma de API. Los nombres exactos de endpoints y parámetros dependen del proveedor, pero la forma es estable, y una capa fina de abstracción la mantiene estable entre backends.

Paso 1: enviar la generación del material limpio

POST /video/generations
{
  "prompt": "A slow dolly shot through a modern office, no on-screen text, natural light",
  "duration_seconds": 6,
  "aspect_ratio": "16:9"
}

Mantén el prompt sin texto y guarda el identificador de tarea devuelto.

Paso 2: consultar hasta que el material esté listo

GET /video/generations/{job_id}

Consulta con retroceso exponencial en lugar de un bucle apretado. Trata estados como queued, running, succeeded y failed como estados de primera clase en el código, y persiste la URL o el ID del material resultante para que un fallo no pierda el resultado de la generación.

Paso 3: enviar el renderizado de la superposición

POST /video/overlays
{
  "source_asset": "asset_abc123",
  "captions": {
    "track": "captions",
    "items": [
      { "text": "Shipping today", "start": 0.4, "end": 2.0, "style": { "role": "title", "position": "lower_third", "align": "center" }, "lang": "en" },
      { "text": "No rebuild required", "start": 2.2, "end": 4.0, "style": { "role": "title", "position": "lower_third", "align": "center" }, "lang": "en" }
    ]
  }
}

Observa que la solicitud de superposición solo lleva el material de origen y los datos de texto. No regenera el material, y eso es precisamente lo que abarata la iteración.

Paso 4: recuperar el resultado compuesto

Consulta la tarea de superposición de la misma forma que consultas la tarea de generación, y luego obtén el material final. Guarda juntos el material base, la carga de subtítulos y la salida, para que la composición sea reproducible.

En el código, envuelve los pasos 1–4 en una función que tome un prompt y una carga de subtítulos y devuelva el material final. Esa función es tu verdadera interfaz; los endpoints individuales son detalles de implementación sustituibles.

Comprobaciones de fiabilidad antes de publicar

Las cadenas de procesamiento de texto en vídeo fallan de forma silenciosa: subtítulos recortados, líneas mal traducidas, regeneraciones que nunca se limpian. Añade comprobaciones antes de que los usuarios las vean.

Validar el texto renderizado

• Ruta nativa: muestrea fotogramas al inicio y al final de cada ventana de texto y revísalos. Automatiza las comprobaciones básicas de legibilidad cuando sea posible, pero mantén un paso de revisión humana para el texto de cara al cliente, porque la tipografía del modelo puede degradarse de forma impredecible.
• Ruta de superposiciones: valida la carga antes de renderizar —que las temporizaciones de cada elemento no se solapen, estén dentro de la duración del clip, y usen idiomas y roles admitidos. Después de renderizar, inspecciona fotogramas en los límites de los elementos para confirmar que nada se ha recortado.

Hacer seguros los reintentos

• Claves de idempotencia en las solicitudes de envío, para que una llamada de red reintentada no cree tareas de generación duplicadas.
• Una máquina de estados por tarea: queued → running → succeeded/failed, persistida, para que un reinicio recupere en lugar de empezar de cero.
• Consulta acotada, con retroceso y tiempo de espera máximos, que presente un fallo claro en lugar de un bucle permanente.
• Almacena los materiales intermedios. Si falla el paso de superposición, no deberías gastar en regenerar un material que ya tienes.

Controlar el coste de toda la cadena

La ruta de superposiciones tiene dos pasos facturables —generación y renderizado—, así que monitoriza ambos. Sigue la frecuencia con la que regeneras material frente a la de solo volver a renderizar superposiciones; si la regeneración de material domina, puede que tu división entre nativo y superposiciones no sea la adecuada para esa carga de trabajo. Cachea los materiales finales por (material base, carga de subtítulos), para que las solicitudes repetidas de la misma salida sean gratuitas.

Observabilidad

Registra juntos el prompt, el hash de la carga de subtítulos, el ID de tarea y el ID del material final. Cuando un usuario informe de un error de subtítulos, querrás poder determinar en segundos si el problema está en la generación, en los datos o en el renderizado. Trata la carga de subtítulos como una única fuente de verdad versionada, para que siempre puedas explicar qué se le pidió dibujar al renderizador.

Elige tu flujo de trabajo predeterminado

Usa esto como regla inicial y revísala a medida que el producto crezca.

Elige texto nativo cuando el texto sea decorativo o incidental, la redacción sea breve, puedas aceptar la regeneración como forma de corregir errores y añadir un segundo paso de renderizado no merezca el tiempo de ingeniería para ese clip.

Elige la ruta de superposiciones cuando el texto deba ser exacto, estar temporizado, traducirse, rediseñarse o reutilizarse en múltiples salidas. Los subtítulos, los subtítulos secundarios, los tercios inferiores y los formatos de marketing con plantilla casi siempre caen aquí. La solicitud adicional es el precio de la determinación.

Mezclar tiene sentido. Muchos equipos generan material limpio por defecto, dependen de las superposiciones para cualquier cosa importante y reservan el texto nativo para planos ambientales de usar y tirar. Como ambas rutas consumen la misma carga de subtítulos, puedes tomar esta decisión por clip sin tratar tus datos de forma especial.

Elijas lo que elijas, mantén la integración detrás de una abstracción fina: una función que tome un prompt y una carga de subtítulos y devuelva el material final. Ese límite es lo que te permite cambiar de backend de generación, añadir opciones de renderizado o mover un clip individual entre flujos de trabajo sin tocar la lógica de subtítulos que tanto te costó acertar.