DEV Community

Cover image for Comment utiliser l'API Grok de texte en vidéo : le guide complet
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment utiliser l'API Grok de texte en vidéo : le guide complet

TL;DR

L'API Grok de conversion texte-vidéo permet de générer des vidéos à partir d'une invite textuelle. Appelez POST /v1/videos/generations pour recevoir immédiatement un request_id, puis interrogez GET /v1/videos/{request_id} jusqu'à ce que le statut soit "done". Le modèle utilisé est grok-imagine-video, la tarification commence à 0,05 $ par seconde en 480p. Le SDK Python xAI gère l'interrogation automatiquement.

Essayez Apidog dès aujourd'hui

Introduction

xAI a généré 1,2 milliard de vidéos en janvier 2026, le mois suivant le lancement de l'API Grok texte-vidéo (28 janvier 2026). Le modèle s'est classé numéro un sur le classement texte-vidéo d'Artificial Analysis ce même mois, preuve de la robustesse de l'infrastructure à grande échelle.

Ce guide vous détaille chaque étape d'intégration : première requête, interrogation, réglage des paramètres, rédaction d'invites efficaces, utilisation d'images de référence, extension/édition de vidéos existantes, et choix du mode texte-vidéo. Vous apprendrez aussi à tester sans consommer de crédits grâce à Apidog Smart Mock.

💡 L'API fonctionne en mode asynchrone : votre frontend ne peut pas attendre que la vidéo soit prête pour afficher du contenu. Pour développer une interface utilisateur de génération vidéo sans dépenser de crédits à chaque test, simulez les points de terminaison de génération et d'interrogation avec Smart Mock d'Apidog. Votre équipe frontend peut avancer pendant que le backend se construit.

Qu'est-ce que l'API Grok de conversion texte-vidéo ?

L'API Grok texte-vidéo fait partie de la suite xAI (https://api.x.ai). Envoyez une invite textuelle, le modèle grok-imagine-video génère un clip vidéo à partir de zéro, aucune image source requise.

Elle complète un endpoint de génération d'images synchrone (POST /v1/images/generations, modèle grok-imagine-image, 0,02 $/image) et propose aussi des endpoints d’extension et d’édition vidéo.

Différence clé avec image-vidéo : le texte-vidéo ne prend que des mots, créant entièrement la scène et l’animation. Si vous souhaitez animer une image source, voir le guide de l'API Grok image-vidéo.

Fonctionnement : génération texte-vidéo asynchrone

Le flux d’appel est asynchrone (idéal pour les tâches longues) :

  1. Envoyez une requête POST avec votre invite.
  2. L’API retourne immédiatement un request_id.
  3. La vidéo est générée côté xAI.
  4. Interrogez le endpoint GET avec ce request_id à intervalle régulier.
  5. Quand le statut devient "done", l’URL vidéo est disponible.

Ce modèle est standard pour les API génératives multimédia. Votre frontend doit donc afficher un indicateur de chargement jusqu’à réception de l’URL vidéo.

Prérequis

  • Compte xAI : console.x.ai
  • Clé API : Créez-la dans la console xAI, copiez-la et passez-la dans l’en-tête Authorization de chaque requête.

Exemple d’utilisation comme variable d’environnement :

export XAI_API_KEY="votre_clé_api_ici"
Enter fullscreen mode Exit fullscreen mode

Facultatif : installez le SDK Python xAI pour accélérer l’intégration :

pip install xai-sdk
Enter fullscreen mode Exit fullscreen mode

Une capture d'écran de l'interface de la console xAI montrant la création d'une clé API.

Votre première requête texte-vidéo

Endpoint : POST https://api.x.ai/v1/videos/generations

Champs obligatoires : model, 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"
  }'
Enter fullscreen mode Exit fullscreen mode

Réponse immédiate :

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}
Enter fullscreen mode Exit fullscreen mode

Utilisation de Python (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}")
Enter fullscreen mode Exit fullscreen mode

Interroger pour le résultat vidéo

Une fois le request_id obtenu, interrogez GET /v1/videos/{request_id} jusqu’à ce que status soit "done".

Statuts possibles :

  • "processing" : génération en cours
  • "done" : vidéo prête (URL dans la réponse)
  • "failed" : erreur

Boucle d’interrogation Python :

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:
    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")

def generate_video(prompt: str) -> str:
    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"
)
Enter fullscreen mode Exit fullscreen mode

Réponse d’interrogation terminée :

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 8,
    "respect_moderation": true
  },
  "progress": 100,
  "usage": {
    "cost_in_usd_ticks": 500000000
  }
}
Enter fullscreen mode Exit fullscreen mode

Utilisation du SDK Python xAI

Le SDK xAI gère l’interrogation et attend 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")
Enter fullscreen mode Exit fullscreen mode

Utilisez le SDK pour accélérer l’intégration. Passez à l’approche requests pour un contrôle fin sur la logique d’interrogation.

Rédiger des invites efficaces pour la génération vidéo

  • Description de la scène : Soyez précis sur le sujet et l’environnement.
  • Mouvement : Décrivez ce qui bouge et comment.
  • Style de caméra : Utilisez des termes de cinéma ("gros plan", "dolly zoom", etc.).
  • Éclairage et ambiance : Spécifiez l’ambiance ("heure dorée", "lumière studio").
  • Références de style : Citez un style ("anime", "cinématique", etc.).

Structure recommandée :

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.
Enter fullscreen mode Exit fullscreen mode

Contrôle des paramètres : résolution, durée, rapport d’aspect

  • Durée : 1 à 15 secondes ("duration": 10). Par défaut : 6s.
  • Résolution : "480p" (par défaut) ou "720p" ; 480p pour le prototypage, 720p pour la prod.
  • Aspect ratio : "16:9", "9:16", "1:1", "4:3", "3:4", "3:2", "2:3"
Rapport Idéal pour
16:9 Bureau, YouTube, présentations
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 :

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"
  }'
Enter fullscreen mode Exit fullscreen mode

Utiliser des images de référence

Le paramètre reference_images accepte un tableau de jusqu’à 7 URL. Ces images influencent le style et le contenu visuel sans devenir le sujet principal.

{
  "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"}
  ]
}
Enter fullscreen mode Exit fullscreen mode

Privilégiez des images cohérentes en style pour de meilleurs résultats.

Extension et édition de vidéos générées

  • Étendre une vidéo : POST /v1/videos/extensions (ajoute des séquences, utilise le request_id original et une nouvelle invite).
  • Modifier une vidéo : POST /v1/videos/edits (modifie style, scène ou effets par instruction textuelle).

Ces endpoints sont également asynchrones et renvoient un request_id utilisé pour interroger le résultat.

Suivi du coût depuis la réponse API

L’objet usage contient le coût en "USD ticks" :

"usage": {
  "cost_in_usd_ticks": 500000000
}
Enter fullscreen mode Exit fullscreen mode

Divisez par 10 000 000 pour obtenir le montant 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 $
Enter fullscreen mode Exit fullscreen mode
Résolution Prix/seconde 10s
480p 0,05 $ 0,50 $
720p 0,07 $ 0,70 $

Gardez une trace de cost_in_usd_ticks pour suivre vos coûts sans requêtes supplémentaires.

Tester l’API vidéo Grok avec Apidog

Le modèle asynchrone impose de tester trois états frontend : chargement, succès, erreur. Impossible de tout tester en prod sans dépenser des crédits et du temps. Utilisez la fonction Smart Mock d’Apidog :

Capture d'écran de l'interface d'Apidog montrant la configuration de Smart Mock pour une API.

Cas d’utilisation 1 : Smart Mock pour le développement frontend

  • Simuler le endpoint de génération : Créez POST /v1/videos/generations dans Apidog, schéma de réponse : 
{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}
Enter fullscreen mode Exit fullscreen mode
  • Simuler le endpoint d’interrogation : Créez GET /v1/videos/{request_id} avec schéma complet et Mock personnalisé : 
{
  "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
  }
}
Enter fullscreen mode Exit fullscreen mode

Testez tous les états frontend sans consommer de crédits.

Cas d’utilisation 2 : Scénarios de test pour la boucle d’interrogation

  • Étape 1 : Ajoutez POST /v1/videos/generations dans le scénario de test, extrayez request_id avec JSONPath $.request_id dans une variable videoRequestId.
  • Étape 2 : Ajoutez GET /v1/videos/{{videoRequestId}} dans une boucle For, condition d’arrêt : response.body.status == "done" ; ajoutez un délai entre les itérations.
  • Étape 3 : Assertion finale : $.video.url n’est pas vide.

Automatisez ces tests pour valider votre logique end-to-end à chaque modification.

Texte-vers-vidéo ou image-vers-vidéo : quand utiliser quoi

Les deux modes utilisent grok-imagine-video, mais pour des usages différents.

Utilisez texte-vers-vidéo si :

  • Vous partez d’un concept ou script original
  • Le modèle doit composer la scène entièrement
  • L’utilisateur saisit une invite textuelle
  • Pas d’image source

Utilisez image-vers-vidéo si :

  • Vous animez une photo, illustration ou asset de marque
  • Vous devez préserver des détails visuels d’une image
  • Animation cohérente à partir d’une série d’images
  • Animation d’œuvre d’art/photo existante

Le texte-vidéo crée une scène de zéro ; l’image-vidéo anime une image existante. Pour approfondir le mode image-vidéo, consultez le guide de l'API Grok image-vers-vidéo.

Pour un produit hybride, détectez le type d’entrée à l’exécution et routez vers le bon endpoint.

Erreurs courantes et solutions

  • 401 Non autorisé : Clé API absente, expirée ou mal formatée. Vérifiez l’en-tête Authorization.
  • 429 Trop de requêtes : Limite atteinte (60/min, 1/s). Ajoutez un délai entre les requêtes, interrogez toutes les 5s.
  • statut "failed" : Invite rejetée par la modération. Vérifiez/simplifiez votre invite.
  • URL vidéo 404 : Les URL expirent rapidement. Téléchargez la vidéo dès réception.
  • Vidéo figée/vide : Invite trop vague, manque de mouvement explicite. Ajoutez des indications précises.
  • Interrogation lente : Les vidéos 720p et longues sont plus lentes. Pour le développement, utilisez 480p et des durées courtes.

Conclusion

L’API Grok texte-vidéo offre une génération vidéo asynchrone, pilotée par invite. Maîtrisez la boucle d’interrogation, puis ajustez durée, résolution, aspect et images de référence selon vos besoins.

Pour la production, suivez les coûts via cost_in_usd_ticks. Simulez vos endpoints dans Apidog pour un développement frontend efficace et des tests automatisés fiables.

Téléchargez Apidog gratuitement pour configurer vos mocks et 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 dans le champ model de votre requête POST.

Combien de temps prend la génération vidéo ?

Cela dépend de la durée et de la résolution. Un clip court en 480p peut être prêt en moins de 30 secondes. Pour 720p ou des clips longs, prévoir plusieurs minutes. Interrogez toutes les 5-10s.

Peut-on générer une vidéo de plus de 15 secondes ?

Non, la durée maximale est 15s par requête. Pour des séquences plus longues, générez puis étendez avec POST /v1/videos/extensions.

Comment télécharger la vidéo générée ?

Récupérez l’URL dans result.video.url de la réponse finale et téléchargez immédiatement le MP4 (l’URL est temporaire).

Que se passe-t-il si l’invite enfreint la modération de contenu ?

La tâche sera "failed". Le champ respect_moderation indique l’application de la modération. Révisez et reformulez votre invite.

Existe-t-il un niveau gratuit pour l’API vidéo ?

La facturation se fait à la seconde générée. Consultez console.x.ai pour les éventuelles offres de crédit.

Quelle différence entre reference_images et une image source ?

reference_images guide le style pour le texte-vidéo. Pour que l’image soit l’élément principal animé, utilisez le mode image-vidéo.

Comment tester la boucle d’interrogation sans dépenser des crédits ?

Utilisez Smart Mock d’Apidog pour simuler les endpoints. Configurez des réponses mock pour "processing" et "done" et testez votre code sans toucher à l’API réelle.

Top comments (0)