Saltar al contenido principal
POST
Crear vídeo
Este endpoint está en fase Alpha y se activa por espacio de trabajo bajo solicitud. Consulta Trabajos de vídeo y procesamiento por lotes para la configuración, los webhooks y la gestión de resultados.

Autorizaciones

Authorization
string
header
requerido

Autenticación con token Bearer

Cuerpo

application/json
model
string
requerido
prompt
string
requerido
models
string[]

Modelos de respaldo opcionales y ordenados que se prueban después de model. model es obligatorio y siempre es el modelo principal. Cuando un intento falla con 429, 500, 502, 503 o 504, se prueba la siguiente entrada; los demás errores se devuelven sin cambios. Acepta hasta 25 IDs de modelo o presets; se ignoran los duplicados y las entradas iguales a model. Cada intento se valida, registra y factura como una solicitud independiente, y el campo model de la respuesta y la traza de enrutamiento muestran el modelo que atendió la solicitud. Las solicitudes en streaming solo recurren a un respaldo antes del primer byte, y los trabajos de video y música solo al enviarse. Las solicitudes de batch, realtime y council rechazan models. Los respaldos definidos en una ruta dinámica tienen prioridad, y phaseo/auto no se puede combinar con models.

Required array length: 1 - 25 elements
Minimum string length: 1
Ejemplo:
duration
integer

Duración deseada en segundos (depende del proveedor/modelo).

input_video_duration
number<double>

Duración del vídeo de origen en segundos. Obligatoria cuando el proveedor factura la duración del vídeo de origen por separado de la salida generada.

Rango requerido: 0 < x <= 3600
input_audio_duration
number<double>

Duración declarada del audio de origen en segundos, usada para validar el intervalo admitido por el proveedor. Los proveedores que no informan del uso definitivo pueden facturar según el máximo de duración de entrada que admiten.

Rango requerido: 2 <= x <= 20
size
string

Dimensiones explícitas (por ejemplo, 1280x720). No puede combinarse con resolution ni aspect_ratio.

resolution
string

480p, 720p, 1080p, 1K, 2K, 4K. Puede combinarse con aspect_ratio. No puede combinarse con size.

aspect_ratio
string

Relación de aspecto como 16:9, 9:16 o 1:1. Puede combinarse con resolution. No puede combinarse con size.

seed
integer
sample_count
integer
Rango requerido: 1 <= x <= 4
negative_prompt
string
generate_audio
boolean
enhance_prompt
boolean
compression_quality

Compresión de la salida. Vertex Veo acepta optimized o lossless y rechaza un número; los demás proveedores que la admiten aceptan un entero.

person_generation
string
resize_mode
string
input_references
object[]

Entradas HTTPS de imagen, audio o vídeo que condicionan la generación. Los tipos, roles, cantidades y combinaciones admitidos dependen del modelo seleccionado. Consulte GET /videos/models antes de enviar un trabajo. El alias de compatibilidad singular input_reference, omitido en este esquema, acepta una imagen multipart o un objeto con exactamente uno de file_id o image_url. La compatibilidad depende del proveedor.

Entrada multimedia HTTPS tipada. Use image_url para imágenes y media_url para audio o vídeo. Los roles describen cómo debe usar el modelo la entrada; la compatibilidad varía según el proveedor y el modelo.

frame_images
object[]

Imágenes HTTPS del primer/último fotograma. Cada frame_type puede aparecer una vez. No proporcione además input_reference ni roles de fotograma en input_references.

Required array length: 1 - 2 elements
provider_params
object

Solo extensiones específicas del proveedor. Se rechazan el paso completo de la solicitud y los campos duplicados de enrutamiento, prompt, callback o facturación. Por ejemplo, Wan 3.0 acepta smart_duration: true para que el modelo elija la duración (no envíes duration con esta opción); el trabajo reserva 30 segundos y se factura la duración que informa el proveedor.

provider_options
object

Extensiones identificadas por el ID canónico del proveedor (por ejemplo, atlascloud o byteplus). Solo se reenvían las opciones del proveedor seleccionado. No puede combinarse con provider_params. Los campos de enrutamiento, prompt, callback, duración, resolución y cantidad de salidas deben usar campos validados de nivel superior.

output
object
webhook
object
provider
object

Preferencias de enrutamiento de proveedores para la selección de la pasarela.

Respuesta

202 - application/json

Respuesta de vídeo

id
string
polling_url
string
websocket_url
string<uri>

URL de WebSocket para suscribirse a actualizaciones normalizadas del ciclo de vida de trabajos asíncronos.

model
string
request_id
string
session_id
string
status
enum<string>
Opciones disponibles:
queued,
processing,
completed,
failed,
cancelled,
expired
lifecycle_status
enum<string>

Estado normalizado del ciclo de vida asíncrono para consumidores de sondeo, WebSocket y webhooks.

Opciones disponibles:
pending,
running,
completed,
failed,
cancelled,
expired
cancel_url
string<uri> | null

Reservado por compatibilidad; actualmente siempre es null.

output_access
enum<string>
Opciones disponibles:
bytes,
signed_url,
both
generation_id
string | null
native_video_id
string | null

ID de vídeo/trabajo nativo del proveedor cuando difiere del ID propio de la pasarela.

created_at
started_at
completed_at
object
string
Ejemplo:

"video"

poll_after_seconds
integer
Ejemplo:

20

provider
string
seconds
number
size
string
audio
boolean
content_url
string

Presente cuando output_access incluye bytes (endpoint autenticado).

download_url
string | null

URL firmada de primera parte para descarga directa cuando el estado es completed.

expires_at
integer | null

Marca de tiempo Unix (segundos) de caducidad de la download_url firmada.

progress
integer | null
progress_source
string
asset
object | null
outputs
object[]
billing
object
webhook
object

Configuración depurada del webhook asíncrono y estado de entrega. Nunca se devuelven secretos; has_secret indica si las entregas firmadas están habilitadas. Las entregas firmadas incluyen las cabeceras x-phaseo-signature, x-phaseo-timestamp, x-phaseo-event-id, x-phaseo-event-type, x-phaseo-delivery-key, x-phaseo-attempt y x-phaseo-max-attempts.

next_webhook_retry_at
string | null

Marca de tiempo ISO del próximo reintento programado del webhook del usuario, si está en cola.

last_webhook_progress
number | null

Último intervalo aproximado de progreso enviado a los consumidores de webhooks.

last_webhook_progress_at
string | null

Marca de tiempo ISO del envío del intervalo de progreso más reciente del webhook.

last_webhook_dispatched_at
string | null

Marca de tiempo ISO del intento de envío del webhook más reciente.

usage
object
error
unknown
Última modificación el 16 de noviembre de 2026