DEV Community

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

Posted on • Originally published at apidog.com

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

En bref

L'API image-vers-vidéo de Grok permet d'animer une image statique en un clip vidéo à l'aide du modèle grok-imagine-video. Pour l'utiliser, envoyez (POST) l’URL de votre image, un prompt et des paramètres optionnels à https://api.x.ai/v1/videos/generations. L’API retourne immédiatement un request_id. Vous devez ensuite interroger (poll) GET /v1/videos/{request_id} jusqu’à ce que le champ status passe à "done". La génération prend entre 1 et 15 secondes de vidéo. Tarification : à partir de 0,05 $/seconde en 480p.

Essayez Apidog dès aujourd'hui

Introduction

Le 28 janvier 2026, xAI a lancé le modèle grok-imagine-video en accès public via API. En un mois, il a généré 1,2 milliard de vidéos et s'est hissé en tête du classement "text-to-video" d’Artificial Analysis. L’animation d’une photo en vidéo est l’une de ses fonctions principales : fournissez une photo et une invite descriptive, et l’API génère un clip MP4 animé à télécharger.

Ce flux asynchrone — soumission d’une tâche puis interrogation de son état — pose un défi de test que beaucoup de développeurs sous-estiment. Une intégration n’est pas terminée après le premier POST 200, mais lorsque la boucle de polling gère correctement les états "processing", "done" et "failed" dans des conditions réelles.

Les Scénarios de Test d’Apidog apportent une solution directe : construisez une séquence chaînée (POST /v1/videos/generations, extraction du request_id, boucle d’interrogation jusqu’à status == "done", puis assertion sur la présence de l’URL vidéo). Suivez ce guide pour mettre en place votre workflow de test.

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

L’API Grok image-vers-vidéo fait partie du produit vidéo de xAI. Elle utilise le modèle grok-imagine-video et prend une image comme première frame de la vidéo générée. Le modèle analyse l’image et le prompt, puis génère un mouvement naturel pour l’animer.

Endpoint API :

POST https://api.x.ai/v1/videos/generations
Enter fullscreen mode Exit fullscreen mode

Authentification :

Authorization: Bearer YOUR_XAI_API_KEY
Enter fullscreen mode Exit fullscreen mode

Obtenez votre clé API sur la console xAI. Cette API supporte également le texte-vers-vidéo (sans paramètre image), l’extension et la modification vidéo.

Fonctionnement du processus image-vers-vidéo

Le paramètre image du body représente la première image de la vidéo. Le modèle anime la scène depuis cette image, chaque pixel initial provient de votre source. Ensuite, selon votre prompt, la scène évolue.

Exemple : une photo d’un lac de montagne au lever du soleil, avec le prompt : « De douces ondulations se propagent à la surface de l’eau tandis que la brume matinale s’élève. » La première frame sera la photo ; les frames suivantes montrent l’animation de l’eau et de la brume.

Différence par rapport au texte-vers-vidéo : le texte-vers-vidéo génère la première image, tandis qu’image-vers-vidéo vous donne un contrôle précis sur la scène initiale.

Utilisez image-vers-vidéo si :

  • Vous souhaitez animer des photos de produits, paysages, portraits existants.
  • Votre branding nécessite une identité visuelle cohérente.
  • Le mouvement doit partir d’une scène réelle.

Utilisez texte-vers-vidéo si :

  • Vous n’avez pas d’image de référence.
  • Vous laissez le modèle choisir la composition.
  • L’itération rapide prime sur la fidélité à une image.

Prérequis

Avant de commencer :

  1. Compte xAI sur console.x.ai.
  2. Clé API depuis la console xAI (stockez-la dans une variable d’environnement).
  3. Python 3.8+ ou Node.js 18+ (exemples pour les deux).
  4. URL d’image publique ou image encodée en base64 (data URI).

image-68.png

Définissez la clé API :

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

Installez le SDK Python xAI (optionnel) :

pip install xai-sdk
Enter fullscreen mode Exit fullscreen mode

Pour les appels HTTP bruts : utilisez 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"
  }'
Enter fullscreen mode Exit fullscreen mode

Réponse immédiate :

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

La génération est asynchrone. Passez à l’étape d’interrogation.

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

Utilisation d'une image Base64

Pour une image locale/non publique :

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

Interrogation du résultat

La génération vidéo étant asynchrone, interrogez :

GET https://api.x.ai/v1/videos/{request_id}
Enter fullscreen mode Exit fullscreen mode

Statuts possibles :

Statut Signification
"processing" Vidéo en cours de rendu
"done" Vidéo prête, URL disponible
"failed" Une erreur est survenue

Réponse complète :

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

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

Gardez un intervalle d’au moins 5 s. Limite d’API : 60 requêtes/minute (1/s).

Utilisation du SDK Python xAI

Le package xai-sdk gère pour vous la logique asynchrone :

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

Le SDK s’occupe du polling, des erreurs, etc. Pour un contrôle granulaire sur la boucle ou les logs, utilisez les requêtes brutes.

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

L’API offre un contrôle précis sur la sortie :

Durée

duration : entier de 1 à 15 secondes (par défaut : 6).

"duration": 10
Enter fullscreen mode Exit fullscreen mode

Plus la vidéo est longue, plus le coût augmente.

Résolution

Valeur Description
"480p" Par défaut. Moins cher, plus rapide.
"720p" Qualité supérieure. 0,07 $/sec vs 0,05 $  
"resolution": "720p"
Enter fullscreen mode Exit fullscreen mode

Rapport d’aspect

Valeur Cas d'utilisation
"16:9" Par défaut, paysage
"9:16" Vertical, stories/mobile
"1:1" Carré, réseaux sociaux/thumbnails
"4:3" Photo/presentation classique
"3:4" Portrait
"3:2" Photo standard
"2:3" Portrait haut

Par défaut, l’aspect ratio suit celui de l’image source. Spécifiez-le pour forcer un recadrage.

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

Le paramètre reference_images est différent de image :

  • image : Première image de la vidéo (point de départ pour l’animation).
  • reference_images : Tableau (max 7) d’images qui guident le style, le contenu ou le contexte. Elles influencent l’apparence, sans être affichées.

Exemple d’usage :

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

Ici, product-shot.jpg est la première image ; les références influencent le style/éclairage.

Vous pouvez utiliser uniquement des images de référence (sans image) pour guider un texte-vers-vidéo.

Extension et édition de vidéos

Deux opérations avancées :

Extension d’une vidéo

POST /v1/videos/extensions : ajoute des secondes à une vidéo existante (max 15 s 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
  }'
Enter fullscreen mode Exit fullscreen mode

Interrogez ensuite GET /v1/videos/{request_id} comme précédemment.

Modification d’une vidéo

POST /v1/videos/edits : modifie le contenu ou le mouvement d’une vidéo existante sur la base d’un nouveau prompt.

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

Extensions et modifications utilisent aussi le modèle asynchrone.

Détail des prix : combien coûte une vidéo de 10 s ?

L’API facture :

  • Le traitement de l’image d’entrée
  • La durée de la vidéo de sortie
Composant Coût
Image d’entrée 0,002 $ / image
Sortie en 480p 0,05 $ / seconde
Sortie en 720p 0,07 $ / seconde

Exemple (10 s en 720p) :

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

Exemple (6 s en 480p) :

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

À chaque génération, le coût de l’image d’entrée s’applique, même avec la même URL.

Le texte-vers-vidéo ne facture pas de coût d’image.

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

Pour tester correctement une API asynchrone, validez :

  1. La génération retourne bien un request_id
  2. Le polling gère 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 permettent d’automatiser ce workflow.

Étape 1 : Créer un nouveau scénario de test

Dans Apidog, module Tests → bouton + → nommer (« Flux asynchrone Grok image-vers-vidéo »).

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

  • URL : https://api.x.ai/v1/videos/generations
  • Méthode : POST
  • En-tête : Authorization: Bearer {{xai_api_key}}
  • Body 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"
}
Enter fullscreen mode Exit fullscreen mode

Étape 3 : Extraire le request_id

  • Processeur "Extraire Variable" :
    • Nom : video_request_id
    • Source : corps de la réponse
    • Méthode : JSONPath : $.request_id

Étape 4 : Boucle d’interrogation

  • Processeur "For" (boucle) ; à l’intérieur :
    • Requête GET : https://api.x.ai/v1/videos/{{video_request_id}}
    • Header : Authorization: Bearer {{xai_api_key}}
    • Extraction "video_status" : JSONPath $.status
    • Attendre 5000ms pour éviter la limite de débit
    • Condition d’arrêt de boucle : {{video_status}} == "done"

Étape 5 : Assertion sur l’URL vidéo

  • Requête GET finale
  • Processeur "Assertion" :
    • Champ : $.video.url
    • Condition : "n’est pas vide"

Vous pouvez intégrer ce scénario dans votre pipeline CI/CD avec la CLI Apidog :

apidog run --scenario grok-video-async-flow --env production
Enter fullscreen mode Exit fullscreen mode

Erreurs courantes et corrections

401 Non autorisé : Clé API manquante/invalide. Vérifiez l’en-tête Authorization.

422 Entité non traitable : Body malformé, champ model ou prompt manquant, ou image non accessible.

URL d’image non accessible : L’URL doit être publique. Les URLs privées ou localhost échouent. Pour les images locales, utilisez un data URI base64.

Statut bloqué sur "processing" : Patientez jusqu’à 10 min. Si bloqué, renvoyez la requête.

Limite de débit (429) : Maximum 60 requêtes/minute (1/s). Ajoutez un time.sleep(1) entre les polls si besoin.

Erreur Base64 : Vérifiez que l’URI commence par le bon préfixe MIME (data:image/jpeg;base64,).

Mauvais aspect ratio : Si le ratio ne correspond pas, le modèle peut recadrer ou ajouter des bandes noires. Idéal : faites correspondre le ratio à l’image source.

Conclusion

L’API Grok image-vers-vidéo transforme une photo statique en clip animé : POST de l’image et du prompt, extraction du request_id, polling jusqu’à complétion, téléchargement du MP4. Le modèle grok-imagine-video domine le classement Artificial Analysis (janvier 2026) avec plus d’un milliard de vidéos générées ce mois-là.

La gestion du polling asynchrone est la principale difficulté d’intégration. Avec Apidog, créez des tests qui extraient les variables, bouclent sur l’état et valident le résultat, pour détecter les problèmes avant la production.

Commencez à construire votre intégration avec Apidog gratuitement. Aucune carte bancaire requise.

FAQ

Quel nom de modèle pour l’API Grok image-vers-vidéo ?

Utilisez grok-imagine-video dans le champ model du POST.

Différence entre image et reference_images ?

image : première image de la vidéo.

reference_images : indications de style et de contenu, non utilisées comme frame de départ. Vous pouvez les combiner.

Temps de génération d’une vidéo ?

6 s en 480p : 1–3 min.

15 s en 720p : 4–8 min.

Interrogez toutes les 5 s pour éviter la limite.

Utiliser un fichier local ?

Oui, encodez-le en base64 : data:image/jpeg;base64,{octets_encodes}.

Que se passe-t-il si je ne précise pas aspect_ratio ?

Avec image, le ratio suit l’image source. Sans image (texte-vers-vidéo), défaut : 16:9.

Tarif d’une vidéo 10 s 720p ?

Image d’entrée : 0,002 $. Sortie : 0,70 $. Total : 0,702 $.

Quelles limites de débit ?

60 requêtes/minute, 1/s. POST + GET combinés.

Prolonger une vidéo >15 s ?

Oui, via POST /v1/videos/extensions en générant plusieurs fragments successifs.

Top comments (0)