Prise en main de l'API Grok-Video-3 : tout savoir sur le moteur vidéo de xAI
Modèles cibles :
grok-video-1.5,grok-video-1.0
Point de terminaison d'inférence :https://api.toapis.com/v1/videos/generations
Articles liés : Accès compatible OpenAI · API du canal officiel Grok Imagine · Guide vidéo Hailuo 2.3 · Référence Grok Video 1.5
1. Résumé et vue d'ensemble des performances
- Le catalogue d'abord : les demandes d'intégration pratique de Grok Video 3 doivent elles aussi partir des IDs que ToAPIs publie réellement. L'instantané public du catalogue de production daté du 2026-11-10 liste
grok-video-1.0etgrok-video-1.5sur le point de terminaisonopenai-video. Une vérification du 2026-11-17 des URL de documentation et de guide de modèlegrok-video-3a renvoyé HTTP 404. - Contrat : soumettez de manière asynchrone à
POST /v1/videos/generations, puis interrogezGET /v1/videos/generations/{id}jusqu'àcompletedoufailed. Les exemples officiels utilisenthttps://toapis.com(ethttps://toapis.cnpour la Chine continentale). D'autres guides de cette série utilisenthttps://api.toapis.com. Choisissez une origine et restez cohérent. - Modes :
grok-video-1.5documentetext_to_video,first_frame_image_to_videoetreference_images_to_video. Définissezvideo_generation_modeexplicitement pour qu'une seule image de référence ne soit pas traitée comme une tâche héritée de première image. - Médias : envoyez uniquement des URL publiques
http://ouhttps://. Téléversez les fichiers locaux avecPOST /v1/uploads/imageset utilisez ledata.urlrenvoyé. N'envoyez pas de base64. - Affirmations non vérifiées à écarter : les brouillons de planification qui citent un ID
grok-video-3, un SLA de 99,95 %, un tarif fixe de$0.030–$0.038par seconde ou une date future de sortie audio ne sont pas la documentation ToAPIs actuelle. Confirmez les tarifs en vigueur et la prise en charge du canal sur votre compte.
2. IDs Grok Video actuels et modes de génération
Utilisez le nom public du modèle dans le champ model. Ne le remplacez pas par un nom natif de fournisseur, un slug d'URL ou une chaîne grok-video-3 non publiée.
| ID de catalogue | Tâches documentées | Durée (docs) | Résolution | Entrées image |
|---|---|---|---|---|
grok-video-1.5 | Texte, première image ou 1 à 7 images de référence, sélectionnés par video_generation_mode | Entier 1–15 secondes | 480p ou 720p en mode référence ; texte et première image peuvent utiliser 1080p lorsque le canal le prend en charge | Première image : exactement une image ou input_reference. Mode référence : 1 à 7 reference_images |
grok-video-1.0 | Texte vers vidéo et image vers vidéo | Référence de génération : 1–15 secondes (par défaut 8). Guide de modèle / playground : un plafond de 6 secondes sur la variante actuellement disponible | 480p, 720p | image facultative plus reference_images ; jusqu'à 8 images au total |
Pour grok-video-1.5, les nouvelles intégrations devraient définir le mode explicitement :
video_generation_mode | Entrée requise | À omettre |
|---|---|---|
text_to_video | prompt non vide | Tout champ image |
first_frame_image_to_video | Exactement une première image dans image ou input_reference | Valeurs contradictoires dans les deux alias ; n'envoyez pas non plus de liste de références sauf si la référence de votre compte indique le contraire |
reference_images_to_video | prompt plus 1 à 7 reference_images (chaînes ou objets {"url":"..."}) | S'appuyer sur une seule entrée reference_images sans ce mode — l'entrée héritée à image unique reste un comportement de première image |
Un devis tarifaire réussi ne garantit pas qu'un canal de génération est ouvert. Les modes ne sont disponibles que s'ils sont activés sur un canal compatible ; les combinaisons non prises en charge peuvent être rejetées avant la création d'une tâche.
Les valeurs de ratio courantes dans les références Grok Video sont 16:9, 9:16, 3:2, 2:3 et 1:1. La disponibilité dépend toujours du canal, donc envoyez une valeur que vous avez confirmée pour cet ID.

Figure 1 : soumettez un prompt (et des URL d'images publiques facultatives) à POST /v1/videos/generations, interrogez le même id de tâche et lisez result.data[0].url seulement lorsque le statut est completed.
Si vous avez besoin de fonctionnalités du canal officiel Grok Imagine comme l'extension vidéo, il s'agit d'une autre famille d'IDs — consultez le guide du canal officiel Imagine. Pour un second contrat vidéo avec une matrice de durée différente, consultez le guide Hailuo 2.3.
3. Implémentation en production : cURL et Python
Les exemples internationaux de cette série utilisent https://api.toapis.com. La documentation officielle indique aux utilisateurs de Chine continentale d'utiliser https://toapis.cn. Gardez une origine par environnement. Les chemins, les IDs de modèle et l'en-tête Bearer restent identiques.
Étape 1 : envoi cURL pour grok-video-1.5
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-video-1.5",
"prompt": "A cinematic product shot with a slow camera push-in",
"video_generation_mode": "text_to_video",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
Une tâche avec première image utilise le même chemin avec "video_generation_mode": "first_frame_image_to_video" et une URL dans image. Une tâche avec images de référence définit "video_generation_mode": "reference_images_to_video" et une liste reference_images, et maintient resolution à 480p ou 720p.
Étape 2 : aide et interrogation en Python
L'extrait suit le chemin de statut de tâche documenté et les états queued / in_progress / completed / failed. Confirmez id, result.data[0].url et l'enveloppe par rapport à la référence API de votre compte avant de livrer.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_grok_video(
prompt: str,
*,
model: str = "grok-video-1.5",
mode: str = "text_to_video",
duration: int = 8,
resolution: str = "720p",
aspect_ratio: str = "16:9",
image_url: str | None = None,
reference_images: list[str] | None = None,
) -> str:
if model == "grok-video-3":
raise ValueError("grok-video-3 is not a current public catalog ID")
if mode == "reference_images_to_video" and resolution not in {"480p", "720p"}:
raise ValueError("reference mode is documented as 480p or 720p")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
}
if model == "grok-video-1.5":
payload["video_generation_mode"] = mode
if mode == "text_to_video" and (image_url or reference_images):
raise ValueError("text_to_video rejects image fields")
if mode == "first_frame_image_to_video":
if not image_url:
raise ValueError("first-frame mode requires exactly one image URL")
payload["image"] = image_url
if mode == "reference_images_to_video":
refs = reference_images or []
if not (1 <= len(refs) <= 7):
raise ValueError("reference mode requires 1-7 image URLs")
payload["reference_images"] = refs
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 600) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
task_id = dispatch_grok_video(
"A cinematic product shot with a slow camera push-in",
mode="text_to_video",
duration=8,
resolution="720p",
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
Conservez la version du modèle de prompt à côté de l'enregistrement de la tâche pour distinguer un changement de modèle ou de mode d'une reformulation. Téléchargez le fichier avant expires_at ; la référence de statut documente une fenêtre de conservation de 30 jours.
4. Gestion des erreurs et matrice des statuts
Les catégories ci-dessous sont des points de départ pour le diagnostic, et non une garantie des codes d'erreur exacts de ToAPIs. Une requête HTTP réussie exige toujours de lire le status de la tâche. Voir la référence des erreurs pour distinguer les erreurs de requête des motifs status: failed comme content_policy_rejected, insufficient_user_balance ou generation_timeout.
| État HTTP ou de tâche | Catégorie courante | Action recommandée |
|---|---|---|
400 | Champ invalide, inadéquation mode/média ou combinaison non prise en charge | Vérifiez l'ID de catalogue exact, que video_generation_mode correspond aux champs image, que le mode référence reste en 480p ou 720p, et que les valeurs d'image sont des URL publiques |
401 | Clé API absente ou invalide | Faites tourner la clé dans le tableau de bord ToAPIs et confirmez l'en-tête Authorization: Bearer |
429 | Limite de débit ou de concurrence | Respectez Retry-After lorsqu'il est présent ; reculez avec du jitter ; ne réessayez que lorsque c'est sûr |
5xx ou expiration côté client | Problème temporaire de gateway ou d'amont | Interrogez l'id de tâche existant avant de resoumettre |
status: queued ou in_progress | Pas une erreur | Attendez et interrogez à nouveau ; ne créez pas de seconde tâche |
status: failed | La génération n'a pas abouti | Lisez error.code et error.message (et error.reason lorsqu'il est présent). Ne réessayez pas une charge utile rejetée par politique sans modification |
5. Tarifs et retour sur investissement FinOps
- Ne réutilisez pas les prix unitaires des brouillons de planification. La référence API de
grok-video-1.5indique que la tarification suit la configuration actuelle du compte et de la SKU et que la page ne garantit pas de prix fixe à la seconde. Les lignes de référence officielles du fournisseur sur la page de tarifs ToAPIs sont purement indicatives et peuvent différer de la facturation de votre compte. - Un devis n'est pas une garantie de canal. La référence 1.5 note qu'un devis tarifaire réussi ne signifie pas qu'un canal de génération est disponible.
- Contrôlez les dépenses au niveau du prompt : travaillez en
720pavec une durée intermédiaire comme 8 secondes, gardez un modèle versionné, ne changez qu'une variable à la fois et ne resoumettez pas après une expiration côté client tant que l'état de la tâche n'est pas vérifié. - Les contrats officiels des fournisseurs ajoutent souvent des engagements annuels, des quotas par siège et des minimums de prépaiement. La facturation ToAPIs est généralement un paiement à l'usage — confirmez les conditions actives de votre compte.
6. Questions fréquentes
Voir le bloc FAQ du frontmatter. En résumé : grok-video-3 n'est pas un ID public de catalogue actuel ; commencez par grok-video-1.5 ou grok-video-1.0 ; traitez le plafond de durée 1.0 comme une vérification propre au canal ; l'audio synchronisé n'est pas documenté ; interrogez toujours le chemin de statut generations et conservez l'id de tâche.
7. Liste d'actions
- Créez une clé sur le portail développeur ToAPIs.
- Confirmez que
grok-video-1.5ougrok-video-1.0apparaît pour votre clé viaGET /v1/models?type=video— n'envoyez pasgrok-video-3sauf s'il apparaît plus tard dans cette liste et dans la référence API. - Testez rapidement l'extrait cURL avec
video_generation_mode: "text_to_video",duration: 8etresolution: "720p". - Interrogez
GET /v1/videos/generations/{id}avec une échéance bornée et téléchargez le résultat avantexpires_at. - Étape suivante : le guide d'accès compatible OpenAI si vous pointez un client existant vers ToAPIs, le guide du modèle Grok Video 1.5 pour l'état du catalogue en production, et le guide du modèle Grok Video 1.0 avant de compter sur une durée supérieure à 6 secondes sur cet ID.







