Endpoint /v1/videos/generations : votre première vidéo

Générer une vidéo à partir d’un texte

L’API xAI expose un point d’entrée dédié à la vidéo, POST /v1/videos/generations, qui transforme une description écrite en séquence animée via le modèle grok-imagine-video. Le principe est celui d’un studio à la demande : vous décrivez une scène, le modèle la met en mouvement, et vous récupérez un fichier MP4 prêt à être monté. Clip promotionnel, visualisation d’un concept, animation d’illustration — tous ces usages passent par ce même endpoint, et c’est donc lui que nous allons disséquer en premier.

L’exemple ci-dessus donne une idée du rendu attendu. Avant d’écrire votre première requête, gardez en tête les quatre bornes qui encadrent tout ce que vous produirez avec ce modèle.

Structure de la requête

Le corps de la requête est un objet JSON d’une simplicité rassurante. Vous déclarez le modèle, vous écrivez votre prompt, et vous cadrez le résultat avec trois paramètres de forme.

{
  "model": "grok-imagine-video",
  "prompt": "Un dauphin sautant dans un coucher de soleil",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}

Voici la signification exacte de chaque champ :

• model : toujours grok-imagine-video, le seul modèle vidéo disponible actuellement
• prompt : votre description textuelle de la scène souhaitée
• duration : durée en secondes, entre 1 et 15
• aspect_ratio : ratio d’image (16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3)
• resolution : 480p (défaut) ou 720p

Deux points méritent d’être soulignés dès maintenant. Le modèle grok-imagine-video est facturé $0.050 par seconde de vidéo générée : une séquence de cinq secondes vous coûte donc $0.25, quel que soit le nombre d’essais qui vous a amené jusque-là. Et la limite de débit est fixée à 60 requêtes par minute (RPM), ce qui laisse une marge confortable pour un usage normal mais devient une contrainte réelle dès que vous industrialisez.

Surtout, la génération est asynchrone. Votre appel POST ne vous rend pas une vidéo : il vous rend un request_id, et c’est ensuite à vous d’interroger le statut jusqu’à ce que le fichier soit prêt. Ce mécanisme de polling fait l’objet d’une leçon entière plus loin dans le cours ; pour l’instant, retenez seulement que la réponse immédiate est un accusé de réception, pas un résultat.

Un premier appel de bout en bout

Passons à la pratique avec curl. La requête suivante commande une séquence de cinq secondes en 720p, format paysage.

curl -X POST "https://api.x.ai/v1/videos/generations" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "Un chat jouant avec une pelote de laine dans un salon lumineux",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

La réponse tient en une ligne :

{
  "request_id": "vid_abc123def456"
}

Conservez précieusement cet identifiant. C’est votre unique moyen de retrouver la vidéo une fois la génération terminée, et une application qui l’égare a payé une génération qu’elle ne récupérera jamais. Dans un service réel, on le journalise avant même d’entamer le polling.

Cadrer autrement qu’avec un ratio

Le paramètre aspect_ratio convient tant que vous restez dans les formats courants. Quand votre chaîne de production impose des dimensions précises — un habillage vidéo devant s’insérer dans un gabarit existant, par exemple — le paramètre size vous laisse fixer directement les pixels. Les valeurs suivantes sont disponibles :

• 848x480 (équivalent 480p 16:9)
• 1280x720 (équivalent 720p 16:9)
• 1696x960
• 1920x1080

C’est un contrôle plus fin, utile notamment pour les formats non standards, mais il demande de vérifier que la combinaison choisie est bien acceptée avant d’en dépendre en production.

Tarifs relevés le 5 août 2026 — les prix évoluent régulièrement : avant tout calcul de budget, vérifiez la grille en vigueur sur la page officielle des modèles et tarifs xAI.

Points clés à retenir

• L’endpoint est POST /v1/videos/generations avec le modèle grok-imagine-video
• La durée va de 1 à 15 secondes, la résolution de 480p à 720p
• La tarification est de $0.050 par seconde générée
• La génération est asynchrone : vous recevez un request_id à interroger ensuite
• Sept ratios d’aspect sont disponibles pour s’adapter à tous les formats