Parámetros de metadatos de la API de Vídeo de OpenAI

Los metadatos de la API de Vídeo de OpenAI sirven como una herramienta para rastrear y gestionar las solicitudes de generación de vídeo. Mientras que los parámetros principales como prompt, model y seconds determinan la salida visual, los campos de metadatos como id, status y expires_at son clave para supervisar el progreso del trabajo y la organización.

Aspectos destacados:

• Seguimiento de trabajos: Los metadatos rastrean los estados del trabajo (queued, in_progress, completed, failed) y los porcentajes de progreso.
• Metadatos personalizados: Los desarrolladores pueden añadir pares clave-valor personalizados (p. ej., user_id, project_id) para una mejor organización.
• Marcas de tiempo: Campos como created_at y expires_at ayudan a gestionar los plazos de los trabajos y la expiración de los recursos.
• Enlaces relacionales: Los metadatos enlazan activos mediante campos como remixed_from_video_id, garantizando la continuidad entre proyectos.

Para los desarrolladores, comprender y estructurar los metadatos de forma eficaz mejora la eficiencia del flujo de trabajo, desde el seguimiento de trabajos hasta la catalogación de las salidas de vídeo.

Parámetros principales de metadatos en las API compatibles con OpenAI

Metadatos relacionados con el prompt

Un prompt es más que una simple descripción: es un conjunto de instrucciones que influyen en cada decisión visual que toma el modelo. Imagina que estás dando instrucciones a un director de fotografía que no tiene contexto previo de tu guion gráfico. Robin Koenig, de OpenAI, lo explica muy bien:

"Piensa en el prompting como dar instrucciones a un director de fotografía que nunca ha visto tu guion gráfico. Si dejas fuera detalles, improvisarán." ^[6]

Los mejores prompts son estratificados y específicos. Incluyen detalles sobre la composición visual, los momentos de movimiento, la iluminación y la paleta de colores. Por ejemplo, en lugar de decir "una persona camina por una calle", un prompt más eficaz podría ser: "una mujer da cuatro pasos, se detiene en un paso de peatones, mira a la izquierda, con asfalto mojado, reflejos de neón y una suave luz cenital". Este nivel de detalle garantiza una sincronización y un ambiente precisos.

Para la sincronización labial, incluye el diálogo en un bloque Dialogue: separado. De forma similar, si quieres replicar un estilo cinematográfico concreto, utiliza términos precisos como "32mm spherical primes" u "objetivo anamórfico 2.0x, poca profundidad de campo". Para mantener una coloración coherente entre escenas, nombra de tres a cinco colores específicos (p. ej., "ámbar, crema, marrón nogal"). Evita términos vagos como "tonos cálidos", ya que pueden dar lugar a resultados inconsistentes.

A continuación, exploraremos cómo los activos de entrada refinan aún más la generación de vídeo.

Metadatos de activos de entrada

Los activos de entrada se definen mediante dos campos clave: input_reference y characters.

• input_reference: Este campo acepta una URL de imagen o un ID de archivo. El activo proporcionado establece la composición y el estilo del primer fotograma, mientras que el prompt de texto dicta las acciones posteriores. Para evitar problemas como estiramientos o distorsiones, asegúrate de que la imagen de origen coincida con el parámetro size de destino ^[8].
• characters: Este campo recibe un array de IDs de personajes generados a través de la API de Personajes. Cada ID se crea subiendo un clip de referencia corto (de 2 a 4 segundos de duración) con una resolución de entre 720p y 1080p. Una sola generación de vídeo puede incluir hasta dos referencias de personajes. Estos IDs pueden reutilizarse entre proyectos para garantizar la coherencia visual ^[6].

Una vez definidos el prompt y los activos de entrada, los ajustes de renderizado lo unen todo para la salida final.

Metadatos de renderizado y comportamiento de salida

Los parámetros de renderizado determinan las dimensiones, la duración y la calidad del vídeo. Estos ajustes se definen en la llamada a la API y no pueden ajustarse mediante lenguaje natural en el prompt.

El campo model es la principal elección de renderizado. El modelo sora-2 está diseñado para la velocidad y las iteraciones rápidas, mientras que sora-2-pro ofrece una salida de mayor calidad, incluida la resolución 1080p. El parámetro size determina las dimensiones de salida, especificadas como una cadena {width}x{height}. Las resoluciones admitidas dependen del modelo de IA elegido. El parámetro seconds controla la duración del vídeo y acepta los valores "4", "8", "12", "16" o "20", siendo "4" el valor predeterminado ^[6].

Al recuperar un trabajo completado, el parámetro de consulta variant te permite especificar el formato de salida: el vídeo completo, una miniatura (.webp) o una hoja de sprites (.jpg) ^[8]. La velocidad de fotogramas no es un parámetro independiente; en su lugar, los efectos cinematográficos como "180° shutter" o "filmic motion blur" se consiguen mediante instrucciones a nivel de prompt. Para flujos de trabajo a gran escala, la Batch API permite poner en cola múltiples renderizados de vídeo utilizando los mismos parámetros de metadatos que el endpoint estándar POST /videos ^[8].

Estos ajustes de renderizado completan el marco de metadatos, garantizando un proceso de generación de vídeo coherente y consciente del contexto.

Casos de uso prácticos de los metadatos en las API de vídeo

Metadatos para integraciones multimodelo

Los metadatos simplifican el proceso de dirigir las solicitudes al modelo adecuado en función de los requisitos específicos del trabajo. Por ejemplo, podrías usar el parámetro model para elegir sora-2 a 0,10 $/segundo para iteraciones rápidas y borradores en fase inicial. Una vez finalizados tus prompts, podrías cambiar a sora-2-pro a 0,70 $/segundo para salidas en 1080p pulidas y listas para producción ^[9]. Las plataformas que necesitan acceso a una variedad de modelos de vídeo —como Sora, Kling V3 y otros— pueden aprovechar una API unificada como APIMart. Esto permite un enrutamiento multimodelo fluido a través de un único punto de integración. Además, dado que los parámetros de metadatos son coherentes entre los modelos, no hace falta reestructurar la lógica de tus solicitudes al cambiar de uno a otro.

Otra estrategia para ahorrar costes es la limitación por resolución. Por ejemplo, puedes establecer por defecto los renderizados en 720p y ofrecer 1080p como una opción premium, lo que ayuda a gestionar los gastos de renderizado por segundo ^[7].

Este tipo de integración flexible también respalda el seguimiento eficiente de trabajos y el procesamiento asíncrono, que exploraremos a continuación.

Seguimiento de trabajos y solicitudes asíncronas

Los tiempos de renderizado pueden variar mucho, desde tan solo 30 segundos hasta varios minutos, dependiendo del modelo y la resolución seleccionados ^[9]. Cada solicitud de vídeo genera un objeto de trabajo que contiene identificadores clave como id, status, progress y expires_at. Estos campos hacen posible supervisar el proceso de generación de forma asíncrona. El campo expires_at es especialmente útil, ya que indica cuándo expirará la URL de descarga temporal, normalmente en el plazo de una hora para las solicitudes estándar. Esto te da tiempo suficiente para automatizar la transferencia de los archivos completados a soluciones de almacenamiento duradero como S3 o R2 ^[7].

Para los flujos de trabajo de producción, los webhooks son una opción inteligente para reducir las llamadas a la API y la carga del servidor. Al escuchar eventos como video.completed y video.failed, puedes optimizar tus operaciones. Al usar la Batch API, el campo custom_id en tu archivo JSONL puede asignar los resultados de vuelta a registros internos específicos una vez finalizado el lote ^[10]. Combinar esto con una base de datos local que vincule el video_id devuelto a etiquetas internas de proyecto, IDs de usuario o estimaciones de coste crea un rastro de auditoría claro. Esta configuración no solo ayuda en la depuración, sino que también simplifica el seguimiento financiero ^[11]. En conjunto, estas prácticas garantizan que cada trabajo quede registrado y sea recuperable, lo que hace que el proceso de generación de vídeo sea más eficiente.

Más allá del seguimiento, los metadatos también desempeñan un papel clave en la organización y la búsqueda de activos de vídeo.

Catalogación y optimización de búsqueda

Los metadatos son esenciales para crear una biblioteca de vídeo bien organizada y fácil de buscar. Al almacenar detalles estructurados del prompt —como el sujeto, el escenario, el ángulo de cámara y la iluminación— junto con el video_id en una base de datos local, puedes habilitar un filtrado y una recuperación avanzados que van mucho más allá de las búsquedas básicas por palabras clave ^[11]. Para plataformas con necesidades organizativas específicas, como herramientas de e-learning que utilizan campos como lesson_number o difficulty_level, o equipos de marketing que etiquetan activos por campaña, los pares clave-valor personalizados ofrecen un esquema flexible que se integra a la perfección con la lógica de la aplicación ^[12].

El campo remixed_from_video_id añade otra capa de organización al rastrear el linaje creativo de los activos. Esto garantiza que siempre puedas rastrear un vídeo final hasta su origen ^[1]. Además, los metadatos de procedencia C2PA, incluidos automáticamente en cada salida de Sora 2, proporcionan un registro rastreable y auditable desde el borrador inicial hasta el producto final. Estas características ponen de relieve cómo los metadatos son fundamentales para gestionar, organizar y personalizar las salidas de vídeo a lo largo de todo el proceso de generación ^[7].

Buenas prácticas para estructurar y validar metadatos

Diseño de esquemas de metadatos

Cuando se trata de esquemas de metadatos, acertar con la estructura es esencial para una generación de vídeo eficaz. Un buen enfoque es utilizar una estructura de doble capa: un mapa metadata plano (p. ej., usando un BTreeMap en Rust) para las claves estándar y universalmente compatibles, y un mapa extra (o additional_properties) para datos JSON específicos del proveedor o anidados ^[3][14][4]. Esta configuración mantiene el esquema principal limpio y adaptable, al tiempo que permite configuraciones específicas adaptadas a modelos individuales. Este diseño respalda directamente la personalización y el seguimiento de trabajos, como se comentó anteriormente.

Para garantizar la compatibilidad entre diferentes modelos, utiliza nombres de clave simples, planos y descriptivos. Ejemplos como remixed_from_video_id, user_id o project_id son fáciles de indexar, buscar y almacenar en bases de datos ^[1][13]. Reserva las estructuras anidadas para el mapa extra con el fin de gestionar las necesidades específicas del proveedor sin complicar el esquema principal.

Para los parámetros relacionados con el vídeo, como size y seconds, defínelos como enumeraciones de cadena en lugar de dejarlos abiertos ^[1][13]. Esto garantiza la coherencia y evita errores durante las solicitudes al imponer restricciones a nivel de esquema.

Validación de las entradas de metadatos

La validación adecuada de las entradas de metadatos es imprescindible antes de enviar cualquier solicitud. Reduce las probabilidades de fallos en los trabajos y se alinea con las estrategias de seguimiento y depuración comentadas anteriormente:

• Incluye siempre el prompt en cada trabajo de generación de vídeo ^[14].
• Verifica que los valores de seconds y size coincidan con sus enumeraciones admitidas ^[1][5].
• Comprueba que los valores de progress se mantengan dentro del rango entero de 0 a 100 ^[13].

En los lenguajes con tipado fuerte, aprovecha las herramientas integradas del SDK. Por ejemplo, el VideoCreateParams.Builder de Java garantiza los campos obligatorios y los tipos correctos en tiempo de compilación ^[14]. De forma similar, TypeScript utiliza literales VideoSeconds para imponer restricciones ^[2][4]. Estas comprobaciones en tiempo de compilación son más fiables que depender únicamente de validaciones en tiempo de ejecución.

Si una solicitud falla, analiza inmediatamente el objeto VideoCreateError. El campo code proporciona un identificador legible por máquina para el manejo automatizado, mientras que el campo message ofrece una explicación clara para los registros ^[1][13]. Esto facilita determinar si el problema se debe a un parámetro incorrecto, un modelo no admitido o un problema de red.

Más allá de la validación, los metadatos desempeñan un papel clave en la depuración y la supervisión del rendimiento.

Uso de metadatos para depuración y supervisión

Los metadatos pueden ser inestimables para identificar problemas y rastrear el rendimiento. Incluir las marcas de tiempo created_at y completed_at te permite calcular la latencia y detectar regresiones de rendimiento ^[1][13]. Por ejemplo, si un modelo o una resolución concretos tardan sistemáticamente más de lo esperado, estas marcas de tiempo pueden ayudar a identificar el cuello de botella.

En los flujos de trabajo iterativos, el campo remixed_from_video_id puede ser un salvavidas. Ayuda a rastrear los errores hasta su origen cuando se producen ediciones inesperadas ^[1][13]. Combina esto con el sondeo del lado del servidor del campo status —rastreando estados como "queued", "in_progress", "completed" y "failed"— para detectar y resolver rápidamente los trabajos estancados ^[13].

"Trata tu prompt como una lista de deseos creativa, no como un contrato." - Robin Koenig, Joanne Shin y Annika Brundyn ^[6]

Este consejo también se aplica a los metadatos. Si una generación falla, simplifica la solicitud a su forma más básica —congela la cámara o simplifica el fondo— y luego reintroduce gradualmente la complejidad, un parámetro a la vez ^[6]. Un esquema bien organizado hace que este proceso de depuración iterativo sea mucho más sencillo.

Conclusión y puntos clave

Resumen de los beneficios de los metadatos

Los metadatos desempeñan un papel crucial a la hora de convertir una llamada a la API en un proceso bien organizado, rastreable y repetible, desde el momento en que entra en la cola hasta la fase final de descarga ^[1][13]. Características como el seguimiento de la expiración de activos garantizan que se te notifique antes de que las URL de descarga expiren, mientras que los objetos de error con campos code legibles por máquina aceleran la depuración al identificar los problemas al instante. Además, los mapas de metadatos personalizados permiten etiquetar trabajos con identificadores internos, simplificando la catalogación y la organización ^[1][3].

Para los flujos de trabajo que involucran múltiples modelos, los metadatos actúan como el pegamento que lo mantiene todo unido. Vinculan las generaciones mediante referencias id, mantienen la coherencia de los personajes y asignan las salidas de lotes usando custom_id. Estas capacidades dependen de tener implementada una estructura de metadatos robusta ^[1][8]. Con estas ventajas en mente, aquí tienes algunos pasos prácticos para perfeccionar tu enfoque.

Próximos pasos para los desarrolladores

Para sacar el máximo partido a tu marco de metadatos, comienza auditando tu implementación actual frente a los principios clave comentados en este artículo. Asegúrate de que expires_at se rastrea para cada trabajo, ya que las URL de descarga solo siguen siendo válidas durante 1 hora después de la generación ^[8]. Incorpora lógica de sondeo con status y progress, o cambia a los webhooks video.completed para reducir las llamadas innecesarias a la API ^[8].

Si gestionas flujos de trabajo entre múltiples modelos, APIMart ofrece una solución práctica. Proporciona acceso a más de 500 modelos de IA a través de una única API, todos estructurados de forma coherente con los patrones de metadatos descritos aquí. Esto elimina la molestia de gestionar integraciones separadas para cada modelo y puede agilizar tu proceso de desarrollo ^[13].

Preguntas frecuentes

¿Qué campos de metadatos debo almacenar en mi base de datos para cada trabajo de vídeo?

Para tener controlados los trabajos de generación de vídeo, asegúrate de almacenar detalles clave como el ID único, el estado, el prompt, el modelo, el tamaño y la duración. Añade marcas de tiempo como created_at, completed_at y expires_at para un seguimiento preciso. Incluye cualquier información de errores para ayudar con la resolución de problemas. Para los vídeos remezclados, utiliza el campo remixed_from_video_id para rastrear el origen de los activos. Herramientas como APIMart agilizan este proceso al proporcionar una plataforma centralizada para una integración y gestión sencillas.

¿Cómo mantengo la coherencia de personajes y estilo entre múltiples generaciones de vídeo?

Para mantener la coherencia de personajes, aprovecha la API de Personajes creando una referencia a partir de un vídeo subido. Incluye el ID de personaje resultante en el array character_ids de tu solicitud de generación. Puedes incluir hasta dos personajes por generación con este fin.

Para la coherencia de estilo, utiliza el endpoint de extensión de vídeo para continuar clips de forma fluida manteniendo intactos elementos como la iluminación y la profundidad de campo. Para lograr transiciones suaves, asegúrate de especificar detalles como el encuadre de la cámara, el tipo de objetivo y la gradación de color. Estos factores ayudan a garantizar que la salida final se ajuste perfectamente a tu vídeo original.

¿Qué debo hacer antes de que expire la URL de descarga?

Cuando generas activos de vídeo, ten en cuenta que las URL de descarga normalmente expiran en el plazo de una hora. Para evitar perder el acceso, asegúrate de descargar y guardar tus archivos en una ubicación segura antes de la hora de expiración, que puedes rastrear mediante el campo expires_at en el objeto de vídeo. Para una gestión más sencilla de los activos de vídeo en tus flujos de trabajo, APIMart proporciona integración con modelos de IA avanzados, haciendo que tareas como la creación y la producción de vídeo sean más eficientes.