Comment utiliser l'API image en vidéo de Grok : guide pas à pas

En bref

L'API image-vers-vidéo de Grok utilise le modèle grok-imagine-video pour animer une image statique en un clip vidéo. Vous ENVOYEZ (POST) l'URL de votre image, une invite (prompt) et des paramètres facultatifs à https://api.x.ai/v1/videos/generations. L'API renvoie immédiatement un request_id. Vous interrogez ensuite (poll) GET /v1/videos/{request_id} jusqu'à ce que le status devienne "done". La durée varie de 1 à 15 secondes. La tarification commence à 0,05 $ par seconde pour une sortie en 480p.

Introduction

Le 28 janvier 2026, xAI a lancé le modèle grok-imagine-video pour un accès public via API. Au cours de ce premier mois, le modèle a généré 1,2 milliard de vidéos et s'est classé numéro un du classement "text-to-video" d'Artificial Analysis. L'image-vers-vidéo est l'une de ses capacités phares : vous fournissez à l'API une photographie et une invite descriptive, et elle anime la photographie en un court clip vidéo prêt à être téléchargé au format MP4.

Ce flux asynchrone, où vous soumettez une tâche puis interrogez son achèvement, présente un défi de test que de nombreux développeurs ignorent. Votre intégration n'est pas terminée lorsque le premier POST renvoie 200. Elle est terminée lorsque vous avez confirmé que la boucle d'interrogation gère correctement les états "processing", "done" et "failed" dans des conditions de réseau réelles.

Les Scénarios de Test d'Apidog résolvent ce problème directement. Vous pouvez construire une séquence enchaînée : effectuer un POST vers /v1/videos/generations, extraire le request_id, boucler la requête d'interrogation jusqu'à ce que status == "done", puis affirmer que l'URL de la vidéo est présente. Téléchargez Apidog gratuitement pour suivre les étapes de test plus loin dans ce guide.

Qu'est-ce que l'API Grok image-vers-vidéo ?

L'API Grok image-vers-vidéo fait partie du produit de génération vidéo de xAI. Elle s'appuie sur le modèle grok-imagine-video et accepte une image comme première image de la vidéo de sortie. Le modèle étudie le contenu de l'image et l'invite textuelle, puis génère un mouvement naturel pour animer la scène.

Le point de terminaison de l'API est :

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

L'authentification utilise un jeton Bearer standard :

Authorization: Bearer YOUR_XAI_API_KEY

Vous obtenez votre clé depuis la console xAI. La même surface d'API prend également en charge le texte-vers-vidéo (omettez le paramètre image), les extensions vidéo et les modifications vidéo.

Fonctionnement du processus image-vers-vidéo

Le paramètre image dans le corps de la requête désigne la première image de la vidéo de sortie. Le modèle ne remplace pas l'image. Il en part. Chaque pixel de la première image provient de votre image source. Le modèle prédit ensuite comment cette scène évoluerait dans le temps en fonction de votre invite.

Par exemple : vous fournissez une photographie d'un lac de montagne au lever du soleil. Votre invite dit : « De douces ondulations se propagent à la surface de l'eau tandis que la brume matinale s'élève. » La première image de la vidéo de sortie est votre photographie. Les images suivantes montrent l'eau et la brume s'animant conformément à l'invite.

Ceci est différent du texte-vers-vidéo, où le modèle génère lui-même la première image. L'image-vers-vidéo vous donne un contrôle exact sur la scène de départ.

Vous devriez choisir l'image-vers-vidéo lorsque :

• Vous avez des photos de produits, des paysages ou des portraits existants que vous souhaitez animer.
• Vos ressources de marque nécessitent une identité visuelle cohérente dans la première image.
• Vous souhaitez que le mouvement soit ancré dans une scène réelle ou spécifique.

Vous devriez choisir le texte-vers-vidéo lorsque :

• Vous explorez des idées visuelles sans image de référence.
• Vous voulez que le modèle décide entièrement de la composition de la scène.
• La vitesse d'itération est plus importante que la précision de la première image.

Prérequis

Avant de faire votre premier appel, vous avez besoin de :

1. Un compte xAI sur console.x.ai.
2. Une clé API de la console xAI. Conservez-la dans une variable d'environnement, ne la codez pas en dur.
3. Python 3.8+ ou Node.js 18+ (les exemples de ce guide utilisent les deux).
4. Une URL d'image accessible publiquement, ou une image encodée en base64 sous forme d'URI de données.

Définissez votre clé comme variable d'environnement :

export XAI_API_KEY="votre_clé_ici"

Installez le SDK Python xAI si vous souhaitez utiliser le client de plus haut niveau :

pip install xai-sdk

Pour les appels HTTP bruts, aucun package supplémentaire n'est requis au-delà de requests (Python) ou fetch (Node.js).

Effectuer votre première requête image-vers-vidéo

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": "De douces vagues se déplacent à la surface, la brume matinale s'élève lentement",
    "image": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

La réponse est renvoyée immédiatement avec un request_id :

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}

La vidéo n'est pas encore prête. La génération se produit de manière asynchrone dans l'infrastructure de xAI. Vous devez interroger le résultat.

Utilisation de Python (requêtes brutes)

import os
import requests

api_key = os.environ["XAI_API_KEY"]

payload = {
    "model": "grok-imagine-video",
    "prompt": "De douces vagues se déplacent à la surface, la brume matinale s'élève lentement",
    "image": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    json=payload,
    headers=headers
)

data = response.json()
request_id = data["request_id"]
print(f"Tâche démarrée : {request_id}")

Utilisation d'une image Base64

Si votre image est locale ou non accessible publiquement, encodez-la en tant qu'URI de données :

import base64

with open("my_image.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload["image"] = {
    "url": f"data:image/jpeg;base64,{encoded}"
}

Interrogation du résultat

La génération vidéo est asynchrone. L'API renvoie un request_id pendant que votre vidéo est rendue sur les serveurs de xAI. Vous devez interroger le point de terminaison d'état :

GET https://api.x.ai/v1/videos/{request_id}

Le champ d'état passe par ces valeurs :

Une réponse complète ressemble à ceci :

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 6
  },
  "progress": 100
}

Boucle d'interrogation Python complète

import time

def poll_video(request_id: str, api_key: str, interval: int = 5) -> dict:
    url = f"https://api.x.ai/v1/videos/{request_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    while True:
        response = requests.get(url, headers=headers)
        data = response.json()
        status = data.get("status")

        print(f"Statut : {status} | Progression : {data.get('progress', 0)}%")

        if status == "done":
            return data["video"]
        elif status == "failed":
            raise RuntimeError(f"La génération vidéo a échoué pour {request_id}")

        time.sleep(interval)

# Utilisation
video = poll_video(request_id, api_key)
print(f"URL de la vidéo : {video['url']}")
print(f"Durée : {video['duration']}s")

Maintenez l'intervalle d'interrogation à 5 secondes ou plus. L'API a une limite de débit de 60 requêtes par minute (1 par seconde). Des interrogations trop fréquentes sur plusieurs tâches simultanément peuvent épuiser ce budget rapidement.

Utilisation du SDK Python xAI

La bibliothèque xai-sdk encapsule le modèle asynchrone pour vous. client.video.generate() soumet la tâche et bloque jusqu'à ce que la vidéo soit prête, gérant toute l'interrogation en interne :

from xai_sdk import Client
import os

client = Client(api_key=os.environ["XAI_API_KEY"])

video = client.video.generate(
    model="grok-imagine-video",
    prompt="De douces vagues se déplacent à la surface, la brume matinale s'élève lentement",
    image={"url": "https://example.com/landscape.jpg"},
    duration=6,
    resolution="720p",
    aspect_ratio="16:9"
)

print(f"URL de la vidéo : {video.url}")
print(f"Durée : {video.duration}s")

Le SDK gère la boucle d'interrogation, les vérifications d'état et la propagation des erreurs. Utilisez cette approche lorsque vous souhaitez un code d'application propre sans gérer vous-même l'interrogation HTTP.

Pour un contrôle plus précis des intervalles d'interrogation, des stratégies de nouvelle tentative ou de la journalisation, l'approche des requêtes brutes vous offre plus de flexibilité.

Contrôle de la résolution, de la durée et du rapport d'aspect

L'API vidéo Grok vous donne un contrôle direct sur le format de sortie.

Durée

Le paramètre duration accepte des entiers de 1 à 15 secondes. La valeur par défaut est 6.

"duration": 10

Les vidéos plus longues coûtent plus cher. Un clip de 10 secondes coûte environ 10 fois plus cher qu'un clip de 1 seconde à la même résolution.

Résolution

Deux options sont disponibles :

"resolution": "720p"

Rapport d'aspect

Le paramètre aspect_ratio contrôle les dimensions de l'image de sortie :

Lorsque vous fournissez une image, le rapport d'aspect est par défaut celui des dimensions de l'image source. Définissez-le explicitement pour le remplacer ou le recadrer.

Utilisation d'images de référence pour l'orientation stylistique

Le paramètre reference_images est distinct du paramètre image. Comprendre la différence est important.

image : La photographie source qui devient la première image de la vidéo. Le modèle anime à partir de ce point de départ.

reference_images : Un tableau (array) de jusqu'à 7 images qui guident le style, le contenu ou le contexte visuel de la vidéo générée. Ce ne sont pas des images de la sortie. Elles influencent la façon dont le modèle rend le mouvement et l'apparence.

Utilisez reference_images lorsque vous souhaitez que la vidéo de sortie adopte des caractéristiques visuelles d'actifs existants, mais pas comme première image :

{
  "model": "grok-imagine-video",
  "prompt": "Un produit tournant lentement sur une surface blanche propre",
  "image": {
    "url": "https://example.com/product-shot.jpg"
  },
  "reference_images": [
    {"url": "https://example.com/brand-style-reference-1.jpg"},
    {"url": "https://example.com/lighting-reference.jpg"}
  ],
  "duration": 6,
  "resolution": "720p"
}

Dans cet exemple, product-shot.jpg est la première image. Les images de référence guident l'éclairage et le traitement stylistique.

Vous pouvez fournir des images de référence sans aucune image de première image. Dans ce cas, le modèle génère une sortie texte-vers-vidéo tout en tirant des indications stylistiques des références.

Extension et édition de vidéos

L'API prend en charge deux opérations supplémentaires au-delà de la génération initiale.

Extension d'une vidéo

POST /v1/videos/extensions prend une vidéo existante et génère des secondes supplémentaires à partir de l'endroit où elle s'est arrêtée. Cela est utile pour créer des clips plus longs à partir de plusieurs passes de génération, en respectant la limite de 15 secondes par appel.

curl -X POST https://api.x.ai/v1/videos/extensions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "votre_request_id_original",
    "prompt": "La brume continue de se lever alors que la lumière du soleil perce",
    "duration": 5
  }'

La réponse suit le même modèle asynchrone : interrogez GET /v1/videos/{request_id} pour le clip étendu.

Modification d'une vidéo

POST /v1/videos/edits applique des modifications guidées par une invite à une vidéo existante. Vous pouvez modifier des aspects spécifiques du contenu ou du mouvement sans régénérer à partir de zéro.

curl -X POST https://api.x.ai/v1/videos/edits \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "votre_request_id_original",
    "prompt": "Changer le ciel en un coucher de soleil dramatique avec des tons orange profond"
  }'

Les extensions et les modifications sont asynchrones et utilisent le même modèle d'interrogation.

Détail des prix : ce que coûte une vidéo de 10 secondes

L'API vidéo xAI facture deux composants : le traitement de l'image d'entrée et la durée de la vidéo de sortie.

Exemple : vidéo de 10 secondes en 720p

• Image d'entrée : 0,002 $
• Sortie : 10 secondes × 0,07 $ = 0,70 $
• Total : 0,702 $

Exemple : vidéo de 6 secondes en 480p (paramètres par défaut)

• Image d'entrée : 0,002 $
• Sortie : 6 secondes × 0,05 $ = 0,30 $
• Total : 0,302 $

Le coût de l'image d'entrée s'applique chaque fois que vous soumettez une requête de génération, même si vous réutilisez la même URL d'image. Planifiez vos appels de génération en conséquence si vous itérez sur la même image de base.

Le texte-vers-vidéo (sans paramètre image) omet la charge d'entrée de 0,002 $, mais suit par ailleurs la même tarification par seconde.

Comment tester votre intégration de l'API vidéo Grok avec Apidog

Le modèle asynchrone crée un défi de test que de simples tests de requête uniques ne peuvent pas couvrir. Vous devez vérifier que :

1. La requête de génération renvoie un request_id.
2. La requête d'interrogation gère correctement l'état "processing" pendant l'attente.
3. La réponse finale a status == "done" et une URL vidéo non vide.

Les Scénarios de Test d'Apidog enchaînent ces étapes en un flux automatisé. Voici comment le construire :

Étape 1 : Créer un nouveau Scénario de Test

Dans Apidog, ouvrez le module Tests et cliquez sur le bouton + pour créer un nouveau scénario. Nommez-le « Flux asynchrone Grok image-vers-vidéo ».

Étape 2 : Ajouter la requête de génération

Ajoutez une étape de requête POST personnalisée :

• URL : https://api.x.ai/v1/videos/generations
• Méthode : POST
• En-tête : Authorization: Bearer {{xai_api_key}}
• Corps (JSON) :

{
  "model": "grok-imagine-video",
  "prompt": "Une douce brume s'élève de l'eau tandis que la lumière filtre à travers les arbres",
  "image": {
    "url": "https://example.com/your-test-image.jpg"
  },
  "duration": 6,
  "resolution": "480p"
}

Étape 3 : Extraire le request_id

Après l'étape POST, ajoutez un processeur Extraire Variable. Configurez-le :

• Nom de la variable : video_request_id
• Source : Corps de la réponse
• Méthode d'extraction : JSONPath
• Expression JSONPath : $.request_id

Apidog stocke la valeur extraite dans {{video_request_id}} pour l'utiliser dans les étapes ultérieures.

Étape 4 : Construire la boucle d'interrogation

Ajoutez un processeur de boucle For. À l'intérieur de la boucle, ajoutez la requête d'interrogation :

• URL : https://api.x.ai/v1/videos/{{video_request_id}}
• Méthode : GET
• En-tête : Authorization: Bearer {{xai_api_key}}

Ajoutez un processeur Extraire Variable à l'intérieur de la boucle pour capturer l'état actuel :

• Nom de la variable : video_status
• JSONPath : $.status

Ajoutez un processeur Attendre (5000ms) après l'extraction de l'état pour éviter d'atteindre la limite de débit.

Définissez la condition Arrêter si de la boucle : {{video_status}} == "done".

Étape 5 : Affirmer l'URL de la vidéo

Après la boucle For, ajoutez une dernière étape GET au même point de terminaison d'interrogation. Ajoutez un processeur Assertion :

• Champ : $.video.url
• Condition : N'est pas vide

Cette assertion confirme que l'URL de la vidéo est présente avant que votre test ne réussisse.

Pour un examen plus approfondi de la façon de tester les API asynchrones avec Apidog, y compris des modèles d'interrogation plus complexes et l'intégration CI/CD, consultez ce guide dédié.

Exécution du scénario

Cliquez sur Exécuter dans la vue du scénario de test. Apidog exécute le POST, extrait le request_id, boucle l'interrogation jusqu'à ce que status == "done", puis évalue vos assertions. Le rapport de test affiche l'état et le timing de chaque étape.

Vous pouvez intégrer ce scénario dans votre pipeline CI/CD avec l'interface de ligne de commande (CLI) Apidog :

apidog run --scenario grok-video-async-flow --env production

Erreurs courantes et corrections

401 Non autorisé

Votre clé API est manquante ou invalide. Vérifiez le format de l'en-tête Authorization : Bearer VOTRE_CLE_API_XAI. Confirmez que la clé est active dans la console xAI.

422 Entité non traitable

Le corps de la requête est malformé. Causes courantes : le champ model est manquant, le prompt est vide, ou l'image.url n'est pas accessible. Testez l'URL de l'image dans un navigateur avant de l'utiliser.

URL d'image non accessible

Les serveurs de xAI doivent être capables de récupérer l'URL de l'image au moment de la génération. Les URL privées, les adresses localhost ou les URL derrière une authentification échoueront. Utilisez un CDN public ou un URI de données base64 à la place.

Le statut reste "processing" indéfiniment

Une génération peut prendre de 30 secondes à plusieurs minutes selon la résolution et la durée. Si le statut reste en "processing" au-delà de 10 minutes, la tâche a peut-être échoué. Soumettez une nouvelle requête. L'API xAI n'expose pas actuellement de signal de dépassement de délai distinct de "failed".

Erreurs de limite de débit (429)

L'API autorise 60 requêtes par minute et 1 par seconde. Si vous interrogez plusieurs tâches simultanément, espacez vos requêtes. Ajoutez un time.sleep(1) entre les appels d'interrogation au minimum.

Téléchargement Base64 refusé

Assurez-vous que votre URI de données inclut le préfixe de type MIME correct. Utilisez data:image/jpeg;base64, pour les fichiers JPEG et data:image/png;base64, pour les fichiers PNG.

Inadéquation du rapport d'aspect

Lorsque vous définissez un aspect_ratio explicite qui diffère considérablement des proportions de votre image source, le modèle peut recadrer ou ajouter des bandes noires. Faites correspondre le rapport d'aspect à votre image source pour de meilleurs résultats.

Conclusion

L'API Grok image-vers-vidéo vous offre un chemin direct d'une photographie statique à un court clip animé. Vous ENVOYEZ l'image et l'invite, recevez un request_id, interrogez jusqu'à ce que la tâche soit terminée, et téléchargez le MP4. Le modèle grok-imagine-video s'est classé en tête du classement Artificial Analysis en janvier 2026. Plus d'un milliard de vidéos ont été générées au cours de ce seul mois. Cette ampleur reflète la capacité du modèle sous-jacent.

Le modèle d'interrogation asynchrone est l'endroit où la plupart des intégrations échouent. Un test approprié dans les Scénarios de Test d'Apidog couvre l'étape d'extraction de variable, la boucle d'interrogation avec condition d'arrêt, et une assertion finale d'URL. Cette combinaison détecte les problèmes avant qu'ils n'atteignent la production.

Commencez à construire votre intégration avec Apidog gratuitement. Aucune carte de crédit requise.

FAQ

Quel nom de modèle dois-je utiliser pour l'API Grok image-vers-vidéo ?

Le nom du modèle est grok-imagine-video. Passez-le comme champ model dans le corps de votre requête POST.

Quelle est la différence entre les paramètres image et reference_images ?

Le paramètre image définit la première image de la vidéo de sortie. Le modèle anime à partir de cette image de départ. Le tableau reference_images fournit des indications de style et de contenu sans être utilisé comme image. Vous pouvez combiner les deux dans la même requête.

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

Le temps de génération varie selon la durée et la résolution. Une vidéo de 6 secondes en 480p prend généralement 1 à 3 minutes. Une vidéo de 15 secondes en 720p peut prendre 4 à 8 minutes. Interrogez toutes les 5 secondes pour vérifier l'état sans épuiser votre limite de débit.

Puis-je utiliser un fichier local comme image source ?

Oui. Encodez votre fichier local comme un URI de données base64 : data:image/jpeg;base64,{octets_encodes}. Passez cette chaîne comme valeur url à l'intérieur de l'objet image.

Que se passe-t-il si je ne spécifie pas aspect_ratio ?

Lorsque vous fournissez un paramètre image, le rapport d'aspect est par défaut celui des proportions natives de l'image source. Lors de la génération texte-vers-vidéo sans image, la valeur par défaut est 16:9.

Combien coûte une vidéo de 10 secondes en 720p ?

L'image d'entrée coûte 0,002 $. La sortie coûte 10 × 0,07 $ = 0,70 $. Total : environ 0,702 $ par vidéo.

Quelles sont les limites de débit ?

L'API autorise 60 requêtes par minute et 1 requête par seconde. Cela couvre à la fois les requêtes POST de génération et les requêtes GET d'interrogation combinées.

Puis-je prolonger une vidéo au-delà de 15 secondes ?

Oui, en utilisant le point de terminaison POST /v1/videos/extensions. Vous générez un clip initial de 15 secondes maximum, puis vous l'étendez avec des passes de génération supplémentaires. Chaque extension suit également le modèle d'interrogation asynchrone.