Obtenir le statut vidéo


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

Interrogez le statut et le résultat d’une tâche. Après avoir créé une tâche, interrogez cet endpoint jusqu’à ce que status atteigne un état terminal — completed, failed, cancelled ou expired.

Terminal


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

Limite de débit

Cet endpoint est limité par clé API (par défaut 5 req/s avec un burst de 20). Les requêtes au-delà de la limite renvoient 429 rate_limited avec un Header Retry-After: 1. La création (POST) et l’annulation (DELETE) ne sont pas soumises à cette limite.

N’interrogez pas plus d’une fois par seconde, ou fournissez un callback_url à la création de la tâche pour recevoir un webhook au lieu du polling.

Réponse

Terminée


{
  "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 est signalé comme status: "failed" avec error.code défini sur expired. Pour la liste complète des codes d’erreur, consultez Codes d’erreur.

L’objet Video

Champ	Type	Description
`id`	string	Identifiant unique de la tâche (UUID)
`status`	enum	Voir Machine d’états
`model`	string	Slug du modèle
`prompt`	string	Prompt original
`unsigned_urls`	string[]	Présent quand `completed`. URL vidéo originale en amont (temporaire, peut expirer en 24h)
`mirror_urls`	string[]	Présent quand `completed` et que le fournisseur du modèle a le miroir CDN activé. URL signée persistante — voir URL vidéo
`error`	object	Présent quand `failed` : `{code, message}`
`usage`	object	Présent quand `completed` : `{video_seconds, video_cost}`. `video_seconds` correspond aux secondes facturées (inclut les secondes d’entrée v2v) ; `video_cost` est le montant réel au prix du niveau plateforme, sous forme de chaîne décimale fixe à 10 décimales (évite les pertes de précision)
`created_at` / `updated_at`	integer	Secondes Unix

Machine d’états

Sept états, construits sur le nommage OpenRouter et étendus avec cancelled / expired.

Statut	Terminal	Description
`pending`	—	Acceptée, pas encore soumise en amont
`queued`	—	Soumise en amont, en attente dans la file
`in_progress`	—	Génération en amont
`completed`	✓	Succès, URL vidéo disponibles
`failed`	✓	Échec (y compris timeout, `error.code=expired`)
`cancelled`	✓	Annulée
`expired`	✓	Expirée

Transitions : pending → queued → in_progress → completed est le chemin de succès. Tout état non terminal peut passer à failed, cancelled ou expired.

URL vidéo

Une tâche réussie peut renvoyer deux ensembles d’URL, selon que le fournisseur du modèle a le miroir CDN activé.

Champ	Source	Caractéristiques
`unsigned_urls`	Adresse originale du fournisseur en amont	Temporaire — toujours présente · peut expirer en 24h · non signée
`mirror_urls`	Miroir CDN ofox	Persistante — uniquement pour les fournisseurs avec CDN activé · signée à chaque requête · possède une TTL

Préférez mirror_urls (persistantes et stables). Lorsqu’un modèle ne renvoie que unsigned_urls, téléchargez ou réhébergez le fichier rapidement avant l’expiration de l’adresse temporaire en amont.