Guía API de Vidu: modelo MoE y serie Q

Si tuviera que resumirlo en una línea: usa Vidu MoE para lógica de prompt más difícil, usa Q3 Pro para la salida final y usa Q3 Turbo para pruebas de menor coste a través de una sola configuración de APIMart.

Aquí va la versión corta sobre la que puedes actuar de inmediato:

• Puedo acceder a Vidu MoE, Vidu Q3 Pro y Vidu Q3 Turbo a través de APIMart con una clave API y un flujo de petición principal.
• El endpoint central es POST https://api.apimart.ai/v1/videos/generations.
• Los trabajos de vídeo son asíncronos, así que primero recibo un task_id y luego sondeo GET /v1/tasks/{task_id} o uso callback_url.
• Vidu admite:
  • texto a vídeo
  • imagen a vídeo
  • vídeo basado en referencias
  • transiciones de primer y último fotograma
• Los modelos Q3 añaden audio integrado como diálogo, efectos de sonido y música.
• Los clips pueden durar hasta 16 segundos, con salida en 540p, 720p o 1080p.
• Los precios de APIMart en el artículo enumeran:
  • Q3 Pro: unos $0.12/seg en 720p
  • Q3 Turbo: unos $0.048/seg en 720p
• Los enlaces de salida caducan a las 24 horas, así que debería descargar los archivos poco después del éxito.

Comparación rápida

Lo que me llama la atención es lo simple que es el cambio: en la mayoría de los casos, solo cambio el campo model y mantengo el resto de la configuración igual. Eso hace que el artículo trate menos del trabajo de configuración y más de elegir el modelo adecuado por coste, tiempo de espera y calidad de salida.

Modelos de Vidu explicados: MoE frente a la serie Q

El modelo MoE de Vidu: qué es y cuándo usarlo

El modelo MoE (Mixture of Experts) envía distintas partes de una tarea de generación a expertos especializados en movimiento, consistencia de escena y control de prompt. Tiene más sentido para prompts multiescena o largos donde la consistencia importa más que la velocidad pura.

Hay un detalle, eso sí. MoE consume más cómputo y tiene un tiempo de respuesta más lento que la serie Q ^[7]. Para prompts simples, a menudo es más de lo que necesitas.

La serie Q de Vidu y Vidu Q3 Pro: rendimiento para uso en producción

Si MoE es el especialista, la serie Q es la opción construida para el trabajo de producción. Vidu Q3 Pro está diseñado para salida cinematográfica pulida y vídeos guiados por storyboard ^[7]. Admite vídeo 1080p, clips de hasta 16 segundos y generación de audio y vídeo con diálogo y efectos de sonido sincronizados ^[1][2][4]. En APIMart, Q3 Pro empieza en $0.12 por segundo ^[2][3].

Vidu Q3 Turbo se inclina más hacia la velocidad y el menor coste, con un cambio de escena más rápido ^[6][7]. En APIMart, Q3 Turbo empieza en $0.048 por segundo ^[3].

Cómo elegir entre MoE y la serie Q para tu flujo de trabajo

Esta elección se reduce sobre todo a la complejidad del prompt, el tiempo de respuesta y el presupuesto. Si tu flujo de trabajo depende de un seguimiento estricto de las instrucciones y de la lógica multiescena, opta por MoE. Si necesitas salida pulida con sincronía audiovisual, Q3 Pro es el mejor encaje. Como alternativa, Kling V3 ofrece otra opción de alta fidelidad para vídeo IA cinematográfico. Si tu objetivo principal es la iteración rápida o un menor coste por clip, Q3 Turbo es la opción práctica.

La tabla siguiente asigna cada modelo al tipo de trabajo que maneja mejor. Para quienes comparan opciones de gama alta, Sora 2 ofrece capacidades cinematográficas similares con audio sincronizado.

A continuación, mira cómo seleccionar un modelo, autenticarte y enviar la petición a través de APIMart.

Cómo acceder a Vidu a través de APIMart

Configuración de cuenta, autenticación y gestión de claves API

Después de elegir un modelo, puedes enviar trabajos a través de APIMart con una clave API. Primero, crea una cuenta de APIMart y genera tu clave desde la página de gestión de claves API en el panel ^[2][3].

Envía cada petición con un token Bearer en la cabecera Authorization:

Authorization: Bearer YOUR_API_KEY

Para el almacenamiento, mantén las claves en variables de entorno o en un gestor de secretos como AWS Secrets Manager o GCP Secret Manager. También ayuda usar claves separadas para desarrollo, staging y producción. Si una clave se expone, rótala de inmediato. Haz lo mismo de forma programada. Y cuando registres las peticiones, guarda solo el task_id, nunca el propio token ^[5].

Encontrar modelos, precios y esquema de entrada de Vidu en APIMart

Una vez que has iniciado sesión, revisa el catálogo antes de enviar nada. Ahí es donde puedes confirmar los nombres de los modelos, las entradas admitidas y los precios actuales. En el catálogo de APIMart, los modelos de Vidu figuran bajo Video Generation. También puedes encontrar otros modelos de alto rendimiento como MiniMax-Hailuo-02 en la misma categoría. Usa esa página para comparar el esquema de entrada, la resolución y el coste por segundo entre MoE, Q3 Pro y Q3 Turbo ^[2][3].

Los campos principales a vigilar son:

• model
• prompt
• duration
• resolution
• aspect_ratio

Para los trabajos de texto a vídeo, usa aspect_ratio. Para los trabajos basados en imagen, el sistema usa en su lugar la relación de la imagen de origen ^[2]. Los prompts de texto están limitados a 2.000 caracteres ^[2][3].

Endpoints, estructura de la petición y manejo de trabajos asíncronos

Después de elegir el modelo, envía la petición de generación y sigue el trabajo asíncrono con el task_id devuelto. Envía una petición POST a https://api.apimart.ai/v1/videos/generations y luego sondea el estado del trabajo con GET https://api.apimart.ai/v1/tasks/{task_id} ^[2][5].

Los trabajos pasan por estos estados:

• submitted
• queueing
• processing
• success o failed

Si quieres que APIMart notifique a tu app cuando el trabajo esté listo, añade callback_url y recibe el resultado por webhook ^[5]. Una vez que el trabajo llega a success, descarga el archivo de inmediato. A partir de ahí, puedes asignar los campos de la petición a un flujo de texto a vídeo o a un flujo basado en referencias.

Integración paso a paso para texto a vídeo y vídeo basado en referencias

Flujo básico de texto a vídeo con selección de modelo

Después de elegir un modelo del catálogo, el flujo de texto a vídeo es bastante simple. Envía tu clave API desde el lado del servidor en la cabecera Authorization como Bearer {your_api_key}.

Aquí tienes un payload mínimo para un trabajo de texto a vídeo con viduq3-pro:

{
  "model": "viduq3-pro",
  "prompt": "A red fox running through a snowy forest at dusk, cinematic slow motion",
  "duration": 8,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "audio": true
}

La respuesta incluye un task_id y un estado como submitted, queueing o processing. Después de eso, puedes sondear GET /v1/tasks/{task_id} con el task_id devuelto, o pasar un callback_url en la petición para que la plataforma pueda notificar a tu app cuando el trabajo alcance success o failed ^[1][7][10]. Si quieres cambiar a viduq3-turbo, en la mayoría de los casos solo cambias el campo model.

El patrón asíncrono se mantiene igual entre modos. Lo que cambia son los campos de entrada.

Añadir entradas de imagen o referencia y controles avanzados

Para imagen a vídeo, pasa una URL de imagen en el array image_urls. Usa 0 imágenes para texto a vídeo, 1 para imagen a vídeo y 2 para el modo de primer y último fotograma ^[2]. En los modos basados en imagen, la relación de aspecto de salida proviene de la imagen de origen, así que puedes omitir aspect_ratio ^[2]. Si subes archivos directamente en lugar de usar URLs, mantén cada imagen en formato PNG, JPEG o WebP, por debajo de 50 MB, y mantén el cuerpo HTTP total por debajo de 20 MB ^[9][8].

Para la generación basada en referencias, usa el endpoint /reference2video con un array subjects. Define cada sujeto con un name y sus images, luego llámalo en el prompt con @subjectname. Los modelos Q3 permiten hasta 7 imágenes de referencia o descripciones de texto en la función subjects ^[6]. Si usas el modo de primer y último fotograma, mantén ambas imágenes cercanas en relación de aspecto, idealmente dentro de una proporción de 0.8 a 1.25, para reducir fallos ^[8]. Cuando hay rostros o manos de por medio, mantén los prompts de movimiento sutiles para reducir los artefactos de distorsión ^[5].

La tabla siguiente muestra los parámetros principales de ambos flujos:

Fija un seed constante mientras pruebas si quieres el mismo resultado visual entre ejecuciones ^[2][9]. Para trabajos por lotes que no son urgentes, fija off_peak en true. Esas tareas suelen completarse en 48 horas y usan menos créditos ^[1][6].

Seguimiento de uso, coste y fiabilidad en producción

Una vez que tu petición funciona, el siguiente trabajo es mantener el coste y la fiabilidad bajo control en producción.

Registra el task_id y la marca de tiempo de cada petición. Eso te da una forma segura de depurar sin almacenar credenciales sensibles ^[5]. También ayuda rastrear por separado el tiempo en cola y el tiempo de generación, para que puedas distinguir entre el retraso de la plataforma y la latencia del modelo.

Para la estimación de costes, Vidu Q3 Pro a 720p cuesta unos $0.12 por segundo en APIMart, y Q3 Turbo cuesta unos $0.048 por segundo ^[3]. Configura alertas automáticas al 50%, 80% y 100% de tu tope de presupuesto mensual para que el gasto no se descontrole ^[5].

Los reintentos también importan. En errores 5xx, usa backoff exponencial: reintenta a los 2 segundos, luego a los 5 segundos y luego a los 15 segundos antes de mostrar un error al usuario ^[5]. Los modelos de la serie Vidu Q3 vienen con un SLA del 99.9% para cargas de trabajo de producción ^[3], pero los fallos de corta duración aún ocurren, así que los reintentos deberían formar parte de cualquier build que entregues.

Lista de verificación para la selección de modelos y puntos clave

Lista de verificación por caso de uso para desarrolladores, creadores y equipos de producto

Elige según tres cosas: complejidad del prompt, velocidad y calidad de salida. La tabla siguiente convierte la comparación de modelos en una elección práctica de envío.

Una vez que hayas elegido una fila, mantén el mismo esquema de petición de la sección de integración. En lenguaje llano: empieza las ideas en Q3 Turbo y luego lleva el render final en 1080p a Q3 Pro. Es un flujo de trabajo simple, y te ayuda a moverte rápido sin gastar más de lo necesario.

Para los clips donde la fidelidad del movimiento importa más, apunta a 5–10 segundos en lugar de estirar hasta el máximo de 16 segundos. Los clips más cortos a menudo te dan un movimiento más ajustado y menos quebraderos de cabeza.

Puntos clave a recordar antes de entregar

MoE es la opción para lógica compleja y multiescena. Q3 Pro te da salida cinematográfica 1080p de alta fidelidad ^[3]. Q3 Turbo es la opción de menor coste a $0.048/seg en 720p ^[3].

En APIMart, cambiar entre estos modelos es solo un cambio del parámetro model. Todo lo demás en la petición se mantiene igual ^[3]. Eso significa que puedes probar un modelo, cambiar a otro y mantener estable tu trabajo de integración.

Usa el mismo flujo asíncrono cada vez:

• Envía la petición
• Captura el task_id
• Sondea el estado o usa callback_url

Además, descarga los vídeos generados poco después de que estén listos. Los enlaces de salida caducan a las 24 horas ^[3][11].

Preguntas frecuentes

¿Con qué modelo de Vidu debería empezar?

Empieza con el modelo que se ajuste a tus necesidades de velocidad, audio y control visual.

• viduq3-pro: mejor para sincronía audiovisual y segmentación de tomas
• viduq3-turbo: generación más rápida que la versión pro
• viduq1 o viduq2: opciones sólidas para producción de vídeo estable y movimiento de cámara fiable

¿Cómo rastreo un trabajo de vídeo después de enviarlo?

Puedes rastrear tu tarea de generación de vídeo de dos maneras.

Para uso en producción, la mejor opción es incluir un callback_url en tu petición inicial. Cuando lo haces, la API de Vidu envía las actualizaciones de la tarea y los metadatos del resultado directamente a tu URL de forma automática. Eso significa que no necesitas estar comprobando el estado de la tarea por tu cuenta.

La otra opción es sondear la API de consulta de estado con el task_id que obtienes tras el envío. Una vez que el estado de la tarea cambia a success, la respuesta incluirá la URL de descarga del vídeo y otros metadatos relacionados.

¿Qué entradas y límites debería conocer antes de integrar?

Antes de integrar la API de Vidu, asegúrate de que tus entradas se mantienen dentro de estos límites:

• Imágenes: solo PNG, JPEG, JPG o WebP; cada archivo debe pesar menos de 50 MB y medir al menos 128×128 píxeles
• Cuerpo total de la petición HTTP: máximo 20 MB
• Prompts de texto: hasta 5.000 caracteres
• Datos de paso del payload: hasta 1.048.576 caracteres

Los límites de duración dependen del modelo que uses. Q3 admite 1–16 segundos, Q2 admite 1–10 segundos y Q1 admite 5 segundos.

Además, mantén tus claves API seguras. No las expongas en código del lado del cliente. Envía las peticiones a través de un intermediario del lado del servidor en su lugar.