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

Leçon corrigée le 3 novembre 2026 d’après la documentation vidéo de xAI : trois modèles vidéo sont disponibles (grok-imagine-video-1.5, sa version -lite et grok-imagine-video), la définition monte à 1080p sur les modèles 1.5, les vidéos ont une piste audio par défaut (generate_audio), les limites de débit se comptent en requêtes par seconde, et le paramètre size présenté par l’ancienne version ne figure pas dans la référence de l’API. Sources : Video Generation · Tarifs.

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, avec l’un des trois modèles 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 ces modèles.

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 : grok-imagine-video-1.5, le plus récent, sa version économique grok-imagine-video-1.5-lite, recommandée par xAI pour les vidéos simples, ou grok-imagine-video, la génération précédente, encore utilisée dans les exemples de ce cours
• prompt : votre description textuelle de la scène souhaitée
• duration : durée en secondes, entre 1 et 15 (8 par défaut)
• aspect_ratio : ratio d’image (16:9 par défaut, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9, 5:2)
• resolution : 480p (défaut), 720p ou 1080p — ce dernier rendu nativement par grok-imagine-video-1.5 en text-to-video et image-to-video, obtenu par suréchantillonnage du 720p sur la version -lite, et absent de grok-imagine-video, qui s’arrête à 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 (0,08 $ pour grok-imagine-video-1.5, 0,02 $ pour sa version -lite, au 3 novembre 2026) : une séquence de cinq secondes vous coûte donc $0.25 avec le premier, quel que soit le nombre d’essais qui vous a amené jusque-là. Et la limite de débit se compte en requêtes par seconde, selon le palier de votre équipe : 10 au palier d’entrée pour les modèles vidéo, une marge confortable pour un usage normal, qui devient une contrainte quand vous lancez des lots massifs.

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.

Le son, par défaut

Une vidéo générée comporte une piste audio par défaut — avec, sur grok-imagine-video-1.5 et sa version -lite, une parole synchronisée sur les lèvres. Pour une vidéo muette, destinée par exemple à un fond de site ou à un montage où vous poserez votre propre musique, ajoutez "generate_audio": false à la requête.

Pour cadrer, en revanche, l’API ne connaît que le ratio (aspect_ratio) et la définition (resolution) : la référence de l’API ne prévoit aucun paramètre de taille en pixels. En image-to-video, le ratio de sortie suit toujours celui de l’image source.

Points clés à retenir

• L’endpoint est POST /v1/videos/generations, avec grok-imagine-video-1.5, sa version -lite ou grok-imagine-video
• La durée va de 1 à 15 secondes (8 par défaut), la résolution de 480p à 1080p (720p au plus avec grok-imagine-video)
• Le prix se compte à la seconde générée : $0.020 (-lite), $0.050 (grok-imagine-video) ou $0.080 (grok-imagine-video-1.5)
• La génération est asynchrone : vous recevez un request_id à interroger ensuite
• Neuf ratios d’aspect sont disponibles pour s’adapter à tous les formats
• Une piste audio est générée par défaut ; "generate_audio": false donne une vidéo muette