Obtener estado del video


GET https://api.ofox.ai/v1/videos/{id}

Consulta el estado y resultado de una tarea. Después de crear una tarea, consulta este endpoint hasta que status llegue a un estado terminal: completed, failed, cancelled o expired.

Terminal


curl https://api.ofox.ai/v1/videos/9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718 \
  -H "Authorization: Bearer $OFOX_API_KEY"

Límite de tasa

Este endpoint tiene límite de tasa por API Key (predeterminado 5 req/s con ráfaga de 20). Las solicitudes por encima del límite devuelven 429 rate_limited con un header Retry-After: 1. Crear (POST) y cancelar (DELETE) no están sujetos a este límite.

No consultes más de una vez por segundo, o proporciona un callback_url al crear la tarea para recibir un webhook en lugar de consultar.

Respuesta

Completada


{
  "id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
  "status": "completed",
  "model": "google/veo-3.1",
  "prompt": "A golden retriever running on the beach at sunset",
  "unsigned_urls": ["https://upstream.example/out.mp4"],
  "mirror_urls":   ["https://cdn.ofox.ai/videos/vgen_xxx.mp4?sig=..."],
  "usage": {
    "video_seconds": 5,
    "video_cost": "0.4000000000"
  },
  "created_at": 1776211362,
  "updated_at": 1776211400
}

Un timeout se informa como status: "failed" con error.code establecido en expired. Para la lista completa de códigos de error, consulta Códigos de error.

El objeto Video

Campo	Tipo	Descripción
`id`	string	Identificador único de tarea (UUID)
`status`	enum	Ver Máquina de estados
`model`	string	Slug del modelo
`prompt`	string	Prompt original
`unsigned_urls`	string[]	Presente cuando `completed`. URL de video original upstream (temporal, puede expirar en 24h)
`mirror_urls`	string[]	Presente cuando `completed` y el proveedor del modelo tiene espejado CDN habilitado. URL firmada persistente; ver URLs de video
`error`	object	Presente cuando `failed`: `{code, message}`
`usage`	object	Presente cuando `completed`: `{video_seconds, video_cost}`. `video_seconds` son los segundos facturados (incluye segundos de input v2v); `video_cost` es el cargo real al precio del nivel de plataforma, como string de punto fijo con 10 decimales (evita pérdida de precisión)
`created_at` / `updated_at`	integer	Segundos Unix

Máquina de estados

Siete estados, basados en la nomenclatura de OpenRouter y extendidos con cancelled / expired.

Status	Terminal	Descripción
`pending`	—	Aceptada, aún no enviada upstream
`queued`	—	Enviada upstream, esperando en cola
`in_progress`	—	Generando upstream
`completed`	✓	Éxito, URLs de video disponibles
`failed`	✓	Falló (incluye timeout, `error.code=expired`)
`cancelled`	✓	Cancelada
`expired`	✓	Expirada

Transiciones: pending → queued → in_progress → completed es la ruta de éxito. Cualquier estado no terminal puede pasar a failed, cancelled o expired.

URLs de video

Una tarea exitosa puede devolver dos conjuntos de URLs, según si el proveedor del modelo tiene espejado CDN habilitado.

Campo	Fuente	Características
`unsigned_urls`	Dirección original del proveedor upstream	Temporal: siempre presente · puede expirar en 24h · sin firma
`mirror_urls`	Espejo CDN de ofox	Persistente: solo para proveedores con CDN habilitado · firmada en cada solicitud · tiene TTL

Prefiere mirror_urls (persistentes y estables). Cuando un modelo devuelve solo unsigned_urls, descarga o vuelve a alojar el archivo pronto, antes de que expire la dirección temporal upstream.