TL;DR
L'API Grok de conversion texte-vidéo génère des vidéos à partir d'une invite textuelle. Vous appelez POST /v1/videos/generations, recevez immédiatement un request_id, puis interrogez GET /v1/videos/{request_id} jusqu'à ce que le statut soit "done". Le modèle est grok-imagine-video, la tarification commence à 0,05 $ par seconde en 480p. Le SDK Python xAI gère automatiquement l'interrogation.
Introduction
xAI a généré 1,2 milliard de vidéos en janvier 2026 seulement. Ce fut le premier mois après le lancement de l'API Grok texte-vidéo le 28 janvier 2026. Le modèle s'est également classé numéro un sur le classement texte-vidéo d'Artificial Analysis ce même mois. Ces chiffres sont importants car ils indiquent que l'infrastructure a fait ses preuves à grande échelle.
Ce guide vous accompagne à travers chaque étape : faire votre première requête, interroger le résultat, ajuster les paramètres et rédiger de meilleures invites. Vous apprendrez également comment utiliser des images de référence, étendre ou modifier des vidéos existantes, et comprendre quand le texte-vidéo est le bon choix.
Qu'est-ce que l'API Grok de conversion texte-vidéo ?
L'API Grok de conversion texte-vidéo fait partie de la suite de génération de médias de xAI à l'adresse https://api.x.ai. Vous envoyez une invite textuelle et le modèle grok-imagine-video génère un court clip vidéo à partir de zéro. Aucune image source n'est requise.
L'API se situe à côté d'un point de terminaison de génération d'images synchrone (POST /v1/images/generations, modèle grok-imagine-image, 0,02 $ par image). Elle comprend également des points de terminaison pour étendre ou modifier des vidéos.
Le point de terminaison texte-vidéo diffère fondamentalement du point de terminaison image-vidéo : vous ne fournissez que des mots. Le modèle crée la scène, le mouvement et le style visuel entièrement à partir de votre description. Consultez le guide de l'API Grok d'image-vidéo si vous avez une image source et que vous souhaitez que le modèle l'anime à la place.
Comment fonctionne la génération de texte-vidéo (le modèle asynchrone expliqué simplement)
La plupart des appels d'API sont synchrones. Vous envoyez une requête, attendez un instant, obtenez votre réponse. La génération vidéo prend de quelques secondes à plusieurs minutes, l'API utilise donc un modèle asynchrone à la place.
Voici le flux :
- Vous envoyez une requête POST avec votre invite.
- L'API renvoie immédiatement un
request_id(en moins d'une seconde). - La vidéo est générée sur les serveurs de xAI.
- Vous interrogez un point de terminaison GET avec ce
request_idde manière répétée. - Lorsque le statut passe de
"processing"à"done", la réponse inclut une URL vidéo.
Ce modèle est courant dans les API de médias IA. Il maintient vos connexions HTTP courtes et vous permet de vérifier la progression à votre propre rythme. La difficulté est que votre frontend doit gérer l'état intermédiaire, affichant un indicateur de chargement jusqu'à l'arrivée de l'URL vidéo.
Prérequis
Avant d'écrire du code, vous avez besoin de deux choses :
Un compte xAI. Créez-en un sur console.x.ai. Vous y ajouterez également la facturation avant que votre clé API n'ait accès à la génération.
Une clé API. Dans la console xAI, naviguez vers Clés API et créez une nouvelle clé. Copiez-la en lieu sûr. Vous la passerez comme jeton Bearer dans l'en-tête de chaque requête.
Définissez-la comme variable d'environnement pour ne pas la coder en dur :
export XAI_API_KEY="votre_clé_api_ici"
Facultativement, installez le SDK Python xAI pour l'intégration la plus simple :
pip install xai-sdk
Votre première requête texte-vidéo
Le point de terminaison est POST https://api.x.ai/v1/videos/generations. Les seuls champs requis sont model et prompt.
Utilisation de curl
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 golden retriever courant à travers les feuilles d'automne au ralenti, éclairage cinématographique"
}'
La réponse arrive immédiatement :
{
"request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}
Cet UUID est votre ticket pour récupérer la vidéo une fois qu'elle est prête.
Utilisation de Python avec la bibliothèque requests
import requests
import os
API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
payload = {
"model": "grok-imagine-video",
"prompt": "Un golden retriever courant à travers les feuilles d'automne au ralenti, éclairage cinématographique"
}
response = requests.post(
f"{BASE_URL}/v1/videos/generations",
headers=headers,
json=payload
)
data = response.json()
request_id = data["request_id"]
print(f"Génération démarrée. ID de requête : {request_id}")
Interrogation pour le résultat vidéo
Une fois que vous avez un request_id, interrogez GET /v1/videos/{request_id} jusqu'à ce que le champ de statut soit égal à "done".
Le champ de statut a trois valeurs possibles : - "processing" : toujours en cours de génération - "done" : terminée, l'URL vidéo est disponible - "failed" : quelque chose s'est mal passé
Voici une boucle d'interrogation Python complète :
import requests
import time
import os
API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"
headers = {
"Authorization": f"Bearer {API_KEY}"
}
def poll_video(request_id: str, interval: int = 5, max_attempts: int = 60) -> dict:
"""Interroge jusqu'à ce que la génération vidéo soit terminée."""
url = f"{BASE_URL}/v1/videos/{request_id}"
for attempt in range(max_attempts):
response = requests.get(url, headers=headers)
data = response.json()
status = data.get("status")
progress = data.get("progress", 0)
print(f"Tentative {attempt + 1}: statut={status}, progression={progress}%")
if status == "done":
return data
elif status == "failed":
raise RuntimeError(f"La génération vidéo a échoué : {data}")
time.sleep(interval)
raise TimeoutError(f"Vidéo non prête après {max_attempts} tentatives")
# Flux de travail complet : générer puis interroger
def generate_video(prompt: str) -> str:
"""Génère une vidéo et renvoie son URL."""
response = requests.post(
f"{BASE_URL}/v1/videos/generations",
headers={**headers, "Content-Type": "application/json"},
json={"model": "grok-imagine-video", "prompt": prompt}
)
request_id = response.json()["request_id"]
print(f"ID de requête : {request_id}")
result = poll_video(request_id)
video_url = result["video"]["url"]
print(f"Vidéo prête : {video_url}")
return video_url
video_url = generate_video(
"Un timelapse d'une skyline de ville au coucher du soleil passant à la nuit, vue aérienne"
)
Une fois terminée, la réponse complète de l'interrogation ressemble à ceci :
{
"status": "done",
"video": {
"url": "https://vidgen.x.ai/....mp4",
"duration": 8,
"respect_moderation": true
},
"progress": 100,
"usage": {
"cost_in_usd_ticks": 500000000
}
}
Utilisation du SDK Python xAI
Si vous préférez ignorer l'interrogation manuelle, le SDK xAI s'en charge pour vous. La méthode client.video.generate() bloque jusqu'à ce que la vidéo soit prête.
from xai_sdk import Client
import os
client = Client(api_key=os.environ["XAI_API_KEY"])
result = client.video.generate(
model="grok-imagine-video",
prompt="Un golden retriever courant à travers les feuilles d'automne au ralenti",
duration=8,
resolution="720p",
aspect_ratio="16:9"
)
print(f"URL de la vidéo : {result.video.url}")
print(f"Durée : {result.video.duration}s")
Le SDK est le chemin le plus rapide vers un code fonctionnel. Utilisez l'approche des requêtes brutes lorsque vous avez besoin de plus de contrôle sur la logique de réessai, les mises à jour de progression ou les intervalles d'interrogation personnalisés.
Rédiger des invites efficaces pour la génération vidéo
Votre invite est l'entrée la plus importante. Une invite détaillée et structurée produit de bien meilleurs résultats qu'une invite vague.
Description de la scène
Décrivez le sujet et le cadre ensemble. Soyez précis sur ce qui est visible. "Une tasse de café en céramique blanche sur une table en bois à côté d'une fenêtre striée de pluie" génère une scène plus concrète que "une tasse de café."
Mouvement
Dites au modèle ce qui bouge et comment. "La caméra tourne lentement autour de la tasse alors que la vapeur s'élève" ajoute du mouvement avec une direction claire. Sans repères de mouvement explicites, le modèle peut générer un mouvement minimal ou saccadé.
Style de caméra
Utilisez une terminologie de caméra que vous donneriez à un cinéaste : "gros plan", "plan de suivi", "vue de drone aérienne", "caméra à l'épaule", "dolly zoom". Ces indications se traduisent de manière fiable dans les séquences générées.
Éclairage et ambiance
"Heure dorée", "temps couvert", "néons", et "éclairage studio trois points" produisent tous des looks différents. Associez l'éclairage à l'ambiance : "matin brumeux, atmosphère mélancolique" donne au modèle une orientation tonale au-delà de la température de couleur.
Références de style
Nommez un style visuel si vous en avez un en tête : "cinématique", "documentaire", "anime", "stop-motion", "hyperlapse". La combinaison de deux styles produit souvent des résultats intéressants.
Structure d'invite qui fonctionne
Commencez par le sujet, ajoutez le mouvement, décrivez la caméra, terminez par le style et l'ambiance. Comme ceci :
Un astronaute solitaire flotte devant la Station Spatiale Internationale,
la ligne de vie flottant derrière lui. La caméra suit lentement
à ses côtés, montrant la Terre en dessous. Cinématique, qualité IMAX,
lumière chaude du lever du soleil se reflétant sur la visière.
Contrôle de la résolution, de la durée et du rapport d'aspect
Le point de terminaison de génération accepte plusieurs paramètres facultatifs qui vous permettent de contrôler les dimensions de sortie, la longueur et la qualité.
Durée
"duration": 10
Plage : 1 à 15 secondes. La valeur par défaut est 6 secondes. Les vidéos plus longues coûtent plus cher. Un clip de 10 secondes en 480p coûte 0,50 $.
Résolution
"resolution": "720p"
Deux options : "480p" (par défaut) et "720p". Utilisez 480p pour le prototypage et les tests. Utilisez 720p pour la production où la qualité est importante.
Rapport d'aspect
"aspect_ratio": "9:16"
Rapports disponibles :
| Rapport | Idéal pour |
|---|---|
16:9 |
Bureau, YouTube, présentations (par défaut) |
9:16 |
TikTok, Instagram Reels, mobile |
1:1 |
Fil Instagram, cartes sociales |
4:3 |
Vidéo classique, présentations |
3:4 |
Contenu mobile portrait |
3:2 |
Rapport photo standard |
2:3 |
Photographie portrait |
Exemple complet avec tous les paramètres
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": "Une ville côtière à l'aube, des vagues déferlant doucement sur un rivage rocheux",
"duration": 10,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
Utilisation d'images de référence pour guider le style vidéo
Le paramètre reference_images accepte un tableau de jusqu'à 7 URL d'images. Ces images guident le style visuel et le contenu de la vidéo générée sans en devenir le sujet.
{
"model": "grok-imagine-video",
"prompt": "Une ville côtière à l'aube, des vagues déferlant doucement sur un rivage rocheux",
"reference_images": [
{"url": "https://example.com/ma-reference-de-style.jpg"},
{"url": "https://example.com/reference-palette-de-couleurs.jpg"}
]
}
Les images de référence fonctionnent mieux lorsqu'elles partagent une esthétique cohérente. Si vous fournissez trois images de styles visuels différents, le modèle essaie de les concilier et le résultat peut paraître incohérent. Utilisez un ensemble restreint d'images avec un look unifié pour la meilleure orientation.
Les images de référence sont différentes du point de terminaison image-vidéo. Avec les images de référence, votre invite pilote toujours la scène. Les images influencent l'étalonnage des couleurs, le style de composition et la texture visuelle. Avec l'image-vidéo, l'image source devient la première image.
Extension et édition de vidéos générées
xAI fournit deux points de terminaison supplémentaires pour travailler avec les vidéos que vous avez déjà générées.
Étendre une vidéo
POST /v1/videos/extensions ajoute plus de séquences à une vidéo générée existante. Vous passez le request_id de la vidéo originale et une nouvelle invite pour l'extension. Ceci est utile pour créer des séquences plus longues sans atteindre la limite de 15 secondes en un seul appel.
Modifier une vidéo
POST /v1/videos/edits modifie une vidéo existante en fonction d'une instruction textuelle. Vous pouvez modifier le style, altérer la scène ou appliquer des effets à un clip que vous avez déjà généré.
Les deux points de terminaison suivent le même modèle asynchrone que le point de terminaison de génération principal. Ils renvoient un request_id et vous interrogez GET /v1/videos/{request_id} pour le résultat.
Lecture du coût à partir de la réponse de l'API
La réponse d'interrogation terminée inclut un objet usage :
"usage": {
"cost_in_usd_ticks": 500000000
}
L'unité est en "USD ticks". Divisez par 10 000 000 pour convertir en dollars.
cost_in_usd = result["usage"]["cost_in_usd_ticks"] / 10_000_000
print(f"Coût : ${cost_in_usd:.4f}")
# Sortie : Coût : 0,0500 $
Référence des prix
| Résolution | Prix par seconde | Clip de 10 secondes |
|---|---|---|
| 480p | 0,05 $ | 0,50 $ |
| 720p | 0,07 $ | 0,70 $ |
Une valeur de 500000000 ticks équivaut à 0,50 $. Il s'agit d'un clip de 10 secondes en 480p.
Suivez vos coûts en enregistrant cost_in_usd_ticks de chaque réponse terminée. Cela vous permet de construire des tableaux de bord d'utilisation sans appeler l'API de facturation xAI séparément.
Comment tester votre API vidéo Grok avec Apidog
Le modèle d'interrogation asynchrone crée un défi de test spécifique. Votre code frontend doit gérer trois états : chargement (pendant l'interrogation), succès (URL vidéo reçue) et erreur. Vous ne pouvez pas tester ces trois états en effectuant de vrais appels API, car chaque appel prend du temps et coûte de l'argent. C'est là que la fonction Smart Mock d'Apidog résout directement le problème.
Cas d'utilisation 1 : Smart Mock pour le développement frontend
Avec Smart Mock d'Apidog, vous définissez le schéma pour les deux points de terminaison et Apidog renvoie instantanément des réponses réalistes simulées.
Simuler le point de terminaison de génération :
Dans Apidog, créez le point de terminaison POST /v1/videos/generations dans votre projet. Définissez le schéma de réponse avec un seul champ de chaîne request_id. Smart Mock renverra automatiquement un faux UUID basé sur le modèle de nom de champ.
Votre réponse simulée :
{
"request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}
Simuler le point de terminaison d'interrogation :
Créez GET /v1/videos/{request_id} dans Apidog. Définissez le schéma de réponse complet incluant status, video.url, video.duration, progress et usage.cost_in_usd_ticks. Définissez une réponse Mock personnalisée qui renvoie "status": "done" avec une URL MP4 de remplacement.
Votre réponse d'interrogation simulée :
{
"status": "done",
"video": {
"url": "https://vidgen.x.ai/mock-video-12345.mp4",
"duration": 8,
"respect_moderation": true
},
"progress": 100,
"usage": {
"cost_in_usd_ticks": 400000000
}
}
Les développeurs frontend peuvent désormais construire et tester l'intégralité de l'interface utilisateur du lecteur vidéo avec ce serveur de maquette. Ils voient l'état de chargement, l'état terminé, et peuvent déclencher l'état d'erreur en modifiant la maquette pour renvoyer "status": "failed". Aucun crédit API réel n'est dépensé pendant le développement.
Cas d'utilisation 2 : Scénarios de test pour la boucle d'interrogation
Une fois votre intégration construite, utilisez les scénarios de test d'Apidog pour valider automatiquement le flux complet générer-puis-interroger.
Étape 1 : Ajouter la requête de génération. Ajoutez POST /v1/videos/generations comme première étape de votre scénario de test. Dans le post-processeur, ajoutez une variable d'extraction pour capturer le request_id du corps de la réponse en utilisant l'expression JSONPath $.request_id. Stockez-la dans une variable nommée videoRequestId.
Étape 2 : Ajouter une boucle d'interrogation. Ajoutez GET /v1/videos/{{videoRequestId}} comme deuxième étape. Enveloppez-la dans une boucle For avec une condition de rupture : response.body.status == "done". Ajoutez un processeur d'attente de 5 secondes entre les itérations pour éviter de surcharger la limite de débit.
Étape 3 : Affirmer le résultat. Après la sortie de la boucle, ajoutez un processeur d'assertion à la dernière requête GET. Affirmez que $.video.url n'est pas vide. Cela confirme que le cycle complet s'est terminé avec succès.
Ce scénario de test vous offre une couverture répétable et automatisée du flux asynchrone. Exécutez-le en CI pour détecter toute régression lorsque votre logique d'interrogation change.
Texte-vers-vidéo ou image-vers-vidéo : quand utiliser quoi
Les deux modes utilisent le même modèle grok-imagine-video, mais ils servent des objectifs différents.
Choisissez le texte-vers-vidéo lorsque :- Vous générez du contenu original à partir d'un concept ou d'un script - Vous voulez que le modèle ait un contrôle créatif total sur la composition - Vous construisez un outil de génération de contenu où les utilisateurs tapent des invites - Vous n'avez pas d'image source pour commencer
Choisissez l'image-vers-vidéo lorsque :- Vous avez une photo de produit, une illustration ou un actif de marque à animer - Vous devez conserver des détails visuels spécifiques d'une image existante - Vous créez des animations cohérentes à partir d'une série d'images liées - Vous voulez animer votre propre œuvre d'art ou photographie
La distinction clé : le texte-vers-vidéo crée une scène à partir de zéro. L'image-vers-vidéo fait bouger une image existante. Pour un aperçu complet de l'approche image-vers-vidéo, consultez le guide de l'API Grok image-vers-vidéo.
Pour les équipes qui construisent des produits offrant les deux modes, vous pouvez détecter le type d'entrée au moment de l'exécution. Si l'utilisateur télécharge une image, routez vers POST /v1/images/generations (image-vers-vidéo). S'il ne tape qu'une invite, routez vers POST /v1/videos/generations.
Erreurs courantes et comment les corriger
401 Non autoriséVotre clé API est manquante, expirée ou mal formatée. Vérifiez que l'en-tête d'autorisation est exactement Bearer VOTRE_CLÉ_API_XAI sans espaces supplémentaires. Confirmez que la clé est active dans la console xAI.
429 Trop de requêtesVous avez atteint une limite de débit. L'API autorise 60 requêtes par minute et 1 requête par seconde. Ajoutez un délai entre les requêtes. Si vous interrogez, espacez vos appels d'au moins 5 secondes.
statut : "failed" dans la réponse d'interrogationLa génération a échoué. Cela signifie généralement que l'invite a été rejetée par la modération de contenu. Le champ respect_moderation dans la réponse sera true si la modération a été appliquée. Révisez votre invite pour qu'elle soit moins ambiguë ou supprimez le langage potentiellement sensible.
L'URL de la vidéo renvoie 404Les URL de vidéo générées expirent après une certaine période. Téléchargez la vidéo sur votre propre stockage immédiatement après avoir récupéré l'URL. Ne stockez pas l'URL et ne comptez pas sur sa disponibilité des jours plus tard.
Vidéo vide ou figéeDes invites vagues ou des invites sans repères de mouvement produisent parfois des vidéos avec un mouvement minimal. Ajoutez un langage de mouvement explicite à votre invite : décrivez ce qui bouge, dans quelle direction et à quelle vitesse.
Temps d'interrogation lentsLes vidéos 720p prennent plus de temps à générer que les 480p. Les durées plus longues prennent également plus de temps. Pour le développement et le prototypage, utilisez "resolution": "480p" et des durées courtes pour accélérer le cycle d'itération.
Conclusion
L'API Grok de conversion texte-vidéo vous offre un chemin direct du texte à la vidéo. Vous envoyez une invite, obtenez un request_id, interrogez jusqu'à ce que ce soit fait, et récupérez votre MP4. Le modèle asynchrone est le concept clé à comprendre. Une fois que la boucle d'interrogation fonctionne, le reste des paramètres (durée, résolution, rapport d'aspect, images de référence) est simple à ajuster.
Pour les versions de production, ajoutez un suivi des coûts en lisant cost_in_usd_ticks de chaque réponse terminée. Simulez les deux points de terminaison dans Apidog pendant le développement afin que votre équipe frontend ne soit pas bloquée en attendant de véritables générations. Utilisez les scénarios de test pour maintenir la fiabilité de votre logique d'interrogation à mesure que votre intégration évolue.
Téléchargez Apidog gratuitement pour configurer votre serveur de maquette et vos scénarios de test pour l'API vidéo Grok.
FAQ
Quel nom de modèle dois-je utiliser pour la génération texte-vidéo ?Utilisez grok-imagine-video. C'est le champ model requis dans votre requête POST vers /v1/videos/generations.
Combien de temps prend la génération vidéo ?Cela varie en fonction de la durée et de la résolution. Les courts clips 480p peuvent se terminer en moins de 30 secondes. Les clips 720p plus longs peuvent prendre quelques minutes. Interrogez toutes les 5 à 10 secondes plutôt que de marteler le point de terminaison en continu.
Puis-je générer une vidéo de plus de 15 secondes ?Pas en une seule requête. La duration maximale est de 15 secondes. Pour créer des vidéos plus longues, générez un clip puis utilisez POST /v1/videos/extensions pour ajouter plus de séquences.
Comment télécharger la vidéo générée ?Utilisez l'URL de result.video.url dans la réponse d'interrogation terminée. Téléchargez le MP4 sur votre stockage immédiatement. L'URL est temporaire et expirera.
Que se passe-t-il si mon invite enfreint la modération de contenu ?La tâche se terminera mais le status sera "failed". Le champ respect_moderation dans la réponse d'interrogation indique que la modération a été appliquée. Révisez votre invite et réessayez.
Existe-t-il un niveau gratuit pour l'API vidéo ?xAI facture par seconde de sortie générée. Il n'y a pas de niveau gratuit pour la génération vidéo spécifiquement. Vérifiez console.x.ai pour les offres de crédits actuelles pour les nouveaux comptes.
En quoi les reference_images diffèrent-elles du démarrage avec une image source ?Les images de référence guident le style visuel d'une génération texte-vidéo. Elles influencent l'apparence sans en devenir le sujet. Une image source pour l'image-vidéo devient la première image réelle de la vidéo.
Quelle est la meilleure façon de tester la boucle d'interrogation sans dépenser de crédits ?Utilisez Smart Mock d'Apidog pour simuler les points de terminaison de génération et d'interrogation. Définissez les schémas, configurez des réponses de maquette pour les états "processing" et "done", et votre code d'interrogation fonctionnera sans toucher la véritable API.