Accéder à l'API Grok-Video-3 via des endpoints compatibles OpenAI
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 : Guide pratique Grok Video · API du canal officiel Grok Imagine · Configuration Chatbox compatible OpenAI · Lister les modèles
1. Résumé et vue d'ensemble des performances
- Ce que signifie « compatible OpenAI » ici : ToAPIs documente une origine
/v1unique, une authentification Bearer, ainsi qu'une liste de modèles et une API de complétions de chat au style OpenAI. Les IDs publics de Grok Video sont enregistrés dans la famille d'endpointsopenai-videodu catalogue. Cela ne signifie pas qu'un IDgrok-video-3non publié fonctionnera, et cela ne documente pas en soi une méthode du SDK OpenAI Videos. - IDs : utilisez
grok-video-1.5ougrok-video-1.0après qu'ils apparaissent pour votre clé dansGET /v1/models?type=video. L'instantané public du catalogue daté du 2026-11-10 ne liste pasgrok-video-3. - Chemin vidéo : créez avec
POST /v1/videos/generations. Interrogez avecGET /v1/videos/generations/{id}. Les exemples officiels utilisenthttps://toapis.com(ethttps://toapis.cnpour la Chine continentale). Cette série utilise aussihttps://api.toapis.com. - Authentification partagée : une clé API dans
Authorization: Bearer. Il n'existe pas de document public distinct de portées OAuth pour ces appels vidéo. - Choix du client : utilisez le SDK OpenAI avec
base_url="https://api.toapis.com/v1"pour le travail de type chat et pour une configuration familière de clé et d'origine. Pour Grok Video, ce guide utilise le corps JSON REST documenté afin quevideo_generation_modeet les champs d'URL d'image restent explicites.
2. Origine compatible, liste de modèles et chemins vidéo
Gardez ensemble l'origine, le préfixe /v1 et la clé. Mélanger une clé ToAPIs avec https://api.openai.com/v1, ou une origine ToAPIs avec un chemin Grok natif du fournisseur, correspond à une configuration différente — et non documentée.
| Étape | Chemin documenté | Remarques |
|---|---|---|
| Lister les modèles | GET /v1/models?type=video | Le GET /v1/models par défaut ne renvoie que des modèles texte. Utilisez type=video ou type=all |
| Téléverser une image locale | POST /v1/uploads/images (file en multipart) | Lisez data.url. N'envoyez pas de base64 dans l'appel de génération |
| Créer une tâche Grok Video | POST /v1/videos/generations | Le corps inclut model, prompt et les champs de mode et de média du 1.5 |
| Interroger le statut | GET /v1/videos/generations/{id} | Les états terminaux sont completed et failed |
| Chat (pas vidéo) | POST /v1/chat/completions | Partage seulement l'origine et la clé |
Sur grok-video-1.5, définissez video_generation_mode sur text_to_video, first_frame_image_to_video ou reference_images_to_video pour que le JSON corresponde aux médias envoyés. Le contrat champ par champ se trouve dans le guide pratique Grok Video et la référence API Grok Video 1.5.

Figure 1 : pointez le client vers une origine /v1 ToAPIs, découvrez grok-video-1.5 ou grok-video-1.0 avec la liste des modèles, puis soumettez et interrogez sur /v1/videos/generations — pas sur chat/completions.
Si vous configurez un client de bureau plutôt que du code applicatif, le guide de configuration Chatbox couvre le schéma du champ d'hôte pour le chat. N'attendez pas de ce même chemin chat qu'il renvoie un fichier vidéo.
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.
Étape 1 : découvrir l'ID, puis envoyer avec cURL
curl -sS "https://api.toapis.com/v1/models?type=video" \
-H "Authorization: Bearer $TOAPIS_API_KEY"
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"
}'
Inspectez la liste des modèles pour la chaîne id exacte avant de la coder en dur. Si grok-video-3 est absent, ne l'envoyez pas.
Étape 2 : Python — origine partagée, appels vidéo REST
Le SDK OpenAI n'est montré que pour la base_url et la clé API partagées. La création et l'interrogation vidéo restent sur les chemins generations documentés, afin que les champs du corps 1.5 ne se perdent pas dans un mapping client non officiel.
import os
import time
import requests
from openai import OpenAI
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
# Shared origin and key. Use this client for chat completions; do not assume
# a videos.create mapping unless your account docs define one.
client = OpenAI(base_url=f"{BASE}/v1", api_key=API_KEY)
def list_video_model_ids() -> list[str]:
res = requests.get(
f"{BASE}/v1/models",
headers=HEADERS,
params={"type": "video"},
timeout=30,
)
res.raise_for_status()
data = res.json()
items = data.get("data") or data.get("models") or []
return [item.get("id") or item.get("name") for item in items if item]
def dispatch_grok_video(prompt: str, model: str = "grok-video-1.5") -> str:
available = set(list_video_model_ids())
if available and model not in available:
raise ValueError(f"{model} is not in this key's video model list")
res = requests.post(
f"{BASE}/v1/videos/generations",
headers=HEADERS,
json={
"model": model,
"prompt": prompt,
"video_generation_mode": "text_to_video",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9",
},
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__":
print("Video models (excerpt):", list_video_model_ids()[:20])
task_id = dispatch_grok_video("A cinematic product shot with a slow camera push-in")
print("Task:", task_id)
print("Video:", poll_task(task_id))
Si l'appel de liste renvoie une enveloppe inattendue, journalisez le JSON brut et alignez le parseur sur la page Lister les modèles de votre compte. N'inventez pas de repli qui envoie grok-video-3 lorsque l'ID est absent.
4. Gestion des erreurs et matrice des statuts
Les catégories ci-dessous sont des points de départ pour le diagnostic, pas 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.
| État HTTP ou de tâche | Catégorie courante | Action recommandée |
|---|---|---|
400 | ID de modèle inconnu, inadéquation mode/média ou corps vidéo envoyé à un chemin chat | Confirmez l'ID dans GET /v1/models?type=video, que vous avez posté sur /v1/videos/generations et que les tâches 1.5 définissent un video_generation_mode cohérent |
401 | Clé API absente ou invalide | Utilisez une clé ToAPIs, pas une clé de la plateforme OpenAI, et confirmez l'en-tête Bearer |
404 | Mauvaise origine, /v1 manquant ou chemin inventé comme /videos/tasks/{id} | Passez à GET /v1/videos/generations/{id} sur l'origine utilisée pour la soumission |
429 | Limite de débit ou de concurrence | Respectez Retry-After lorsqu'il est présent ; reculez avec du jitter |
5xx ou expiration côté client | Problème temporaire de passerelle ou d'amont | Interrogez l'id de tâche existant avant de resoumettre |
status: failed | La génération n'a pas abouti | Lisez error.code et error.message. Ne réessayez pas une charge utile rejetée par politique sans modification |
5. Tarifs et retour sur investissement FinOps
- La compatibilité ne change pas la SKU facturable. Vous êtes facturé pour l'ID de modèle du catalogue que vous envoyez (
grok-video-1.5ougrok-video-1.0), pas pour « l'utilisation du SDK OpenAI ». - Ne réutilisez pas les prix unitaires des brouillons de planification. La référence Grok Video 1.5 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 ne pas correspondre à la facturation du compte.
- Une découverte ratée coûte peu ; une génération en double non. Mettez en cache la liste des modèles pour une courte période, mais vérifiez toujours l'état de la tâche après une expiration côté client avant de créer une autre tâche.
- 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é : une URL de base compatible ne débloque pas grok-video-3 ; incluez /v1 une seule fois ; interrogez /v1/videos/generations/{id} ; ne supposez pas d'assistant videos.create du SDK ; les complétions de chat ne renverront pas un MP4.
7. Liste d'actions
- Créez une clé sur le portail développeur ToAPIs.
- Pointez votre client vers
https://api.toapis.com/v1(ouhttps://toapis.cn/v1en Chine continentale) avecAuthorization: Bearer. - Appelez
GET /v1/models?type=videoet notez les IDs Grok Video exacts que votre clé peut voir. - Testez rapidement
POST /v1/videos/generationsavecgrok-video-1.5etvideo_generation_mode: "text_to_video", puis interrogez le même id. - Étape suivante : le guide pratique Grok Video pour les détails de mode et de champs image, et le guide du modèle Grok Video 1.5 pour l'état du catalogue en production.







