Generación de videos
Genere un video con un Model ID compatible: cree una tarea, consulte su estado y descargue el archivo.
La generación de videos es asíncrona: una solicitud crea una tarea y el video solo está disponible cuando la tarea termina correctamente. Antes de empezar, confirme en la página del modelo las resoluciones, duraciones y precios por resolución admitidos.
Endpoints de solicitud
La generación de videos usa un endpoint para crear la tarea y tres para darle seguimiento:
| Método y ruta | Uso |
|---|---|
POST /v1/videos | Crear una tarea de generación de video |
GET /v1/videos/{id} | Consultar el estado de la tarea |
GET /v1/videos/{id}/content | Descargar el video terminado |
DELETE /v1/videos/{id} | Eliminar la tarea, si la interfaz del modelo lo permite |
Todas las rutas usan https://api.vergora.ai y el mismo encabezado Authorization: Bearer YOUR_VERGORA_API_KEY que las demás solicitudes. Solo se factura la creación de tareas.
Ejemplo de solicitud
POST https://api.vergora.ai/v1/videos{
"model": "YOUR_VIDEO_MODEL_ID",
"prompt": "Un barco de papel que flota por una calle lluviosa, con un acercamiento lento de la cámara",
"resolution": "720p",
"ratio": "16:9",
"duration": 5
}La respuesta de creación contiene el id de la tarea y su estado inicial. Guarde el id: lo necesitará en todas las solicitudes posteriores.
Los modelos con la interfaz de video compatible con OpenAI usan seconds y size (por ejemplo, "8" y "1280x720") en lugar de duration, resolution y ratio. La pestaña API de cada página de modelo muestra una solicitud con el formato correcto.
Campos de solicitud
| Campo | Descripción |
|---|---|
model | Un Model ID para generación de videos |
prompt | Sujeto, acción, escena y movimiento de cámara |
content | Entrada estructurada en lugar de prompt, si se admite |
input_reference | URL de una imagen para el primer fotograma |
duration | Duración del video en segundos |
resolution | Resolución de salida, como 720p o 1080p |
ratio | Relación de aspecto, como 16:9 (o aspect_ratio) |
| Otros parámetros | Úselos solo si el modelo los admite |
content puede incluir texto, una imagen de referencia o un video de entrada. Otros parámetros son seed, watermark, generate_audio, camera_fixed y service_tier; envíelos solo a los modelos que los admiten. Seedance 2.0 / 2.5 no aceptan seed ni camera_fixed; la pasarela los descarta para esos modelos. Wan 2.5 / 2.6 y W3.0 usan audio (booleano, activado por defecto) en lugar de generate_audio.
Envíe el cuerpo de la solicitud en JSON. Para usar un video de entrada, indique un enlace público o la clave de un archivo subido (véase Imágenes y videos de referencia más abajo); si es un enlace, debe ser una URL pública http o https (por ejemplo, en un elemento de content de tipo video_url); no se aceptan URI data:. Las solicitudes con video de entrada se cobran con la tarifa con video de entrada del modelo.
Imágenes y videos de referencia
Una imagen o un video de referencia puede indicarse de cualquiera de estas formas. El mismo campo las acepta todas y la pasarela las distingue:
| Forma | Ejemplo | Notas |
|---|---|---|
| Enlace público | https://cdn.example.com/clip.mp4 | Lo descarga el proveedor del modelo, por lo que debe ser accesible desde internet |
| Archivo subido | uploads/u42/20261112/0123…cdef.mp4 | La clave que devuelve POST /v1/uploads (véase más abajo). Se sustituye por un enlace temporal antes de que la solicitud llegue al proveedor |
| Datos en línea | data:image/png;base64,… | Solo imágenes. Los videos no se aceptan en línea |
Coloque la referencia donde la espera la interfaz del modelo: input_reference para una imagen de primer fotograma, o elementos de content de tipo image_url y video_url:
{
"model": "YOUR_VIDEO_MODEL_ID",
"content": [
{
"type": "text",
"text": "La misma escena de noche, con un acercamiento lento de cámara"
},
{
"type": "image_url",
"image_url": { "url": "https://cdn.example.com/frame.png" },
"role": "reference_image"
},
{
"type": "video_url",
"video_url": { "url": "uploads/u42/20261112/0123…cdef.mp4" },
"role": "reference_video"
}
],
"resolution": "720p",
"duration": 5
}Cuántas referencias admite un modelo, y si admite videos, figura en la página del modelo. Cada video de referencia suma su duración al importe facturado.
Suba un archivo de referencia
Cuando el archivo está en su equipo y no tiene un enlace público, súbalo primero y use la clave devuelta.
- Solicite una dirección de subida. Envíe el tipo del archivo y su tamaño exacto en bytes:
POST https://api.vergora.ai/v1/uploads{ "content_type": "video/mp4", "size": 2376873 }- La respuesta contiene
key,upload_url,method(PUT) y losheadersque debe enviar. Suba el archivo aupload_urlcon exactamente esos encabezados. La dirección es válida durante 15 minutos y solo acepta el tipo y el tamaño declarados.
{
"object": "upload",
"key": "uploads/u42/20261112/0123456789abcdef0123456789abcdef.mp4",
"upload_url": "https://…",
"method": "PUT",
"headers": { "Content-Type": "video/mp4" },
"expires_at": 1794500000
}- Use la
keyen cualquier campo que acepte una imagen o un video de referencia.
| Tipo | Formatos aceptados | Límite de tamaño |
|---|---|---|
| Imagen | JPEG, PNG, WebP, GIF | 20 MB |
| Video | MP4, MOV, WebM | 200 MB |
Una clave solo funciona para la cuenta que la creó. El archivo subido debe ser realmente una imagen o un video del tipo declarado; de lo contrario, la solicitud que lo use será rechazada. Los archivos subidos se conservan durante un tiempo limitado; vuelva a subirlos cuando una clave deje de funcionar.
Consulte el estado de la tarea
Las tareas de video suelen tardar entre unas decenas de segundos y varios minutos. Consulte el estado cada pocos segundos:
GET https://api.vergora.ai/v1/videos/{id}| Estado | Significado |
|---|---|
queued | En cola |
running o in_progress | Generándose |
succeeded o completed | Terminada; el video se puede descargar |
failed o cancelled | Terminó sin video; el importe reservado se reembolsa |
La respuesta conserva la estructura de la interfaz del modelo. Los modelos que cobran por token también devuelven un objeto usage con los tokens usados para facturar.
Una tarea creada no significa que el video ya esté generado. Guarde el id de la tarea para diagnosticar fallos y revisar costos.
Descargue el video
GET https://api.vergora.ai/v1/videos/{id}/contentEl cuerpo de la respuesta es el archivo de video, normalmente MP4. Hasta que la tarea termine correctamente, este endpoint devuelve 409 con el código video_not_ready: siga consultando el estado en lugar de reintentar la descarga en bucle. Los archivos generados se conservan solo durante un tiempo limitado; guárdelos en su propio almacenamiento poco después de que la tarea termine.
Costo y reintentos
Los modelos de video tienen precio por resolución, por segundo de video o por millón de tokens; la página del modelo muestra todas las tarifas.
- Al crear una tarea, se reserva de su saldo un importe estimado según la resolución, la relación de aspecto y la duración solicitadas, además del video de entrada, si lo hay. Si la solicitud no las indica, la estimación usa 1080p, 16:9 y 15 segundos.
- Cuando la tarea termina correctamente, el cargo se liquida según el uso real (los tokens que informa el modelo o los segundos completos de video generados), sin superar nunca la reserva: si el uso es menor, la diferencia se reembolsa; si es mayor, el exceso no se cobra.
- Si la tarea falla o se cancela, la reserva se reembolsa por completo. Consultar el estado y descargar el video no tiene costo.
| Respuesta | Significado |
|---|---|
403 insufficient_user_quota | Su saldo no cubre el importe estimado; no se crea ninguna tarea |
503 model_price_not_configured | El modelo aún no tiene precio de video |
409 video_not_ready | Se pidió la descarga antes de que la tarea terminara |
Cada POST /v1/videos crea una tarea nueva que se factura por separado. Si se agota el tiempo de espera, compruebe en sus registros de API si la tarea ya se creó antes de enviar la solicitud de nuevo.