API de génération vidéo Grok Imagine 1.0 : points de terminaison, scopes d'authentification et gestion des erreurs
Modèles cibles :
grok-imagine-video-official,grok-imagine-video-1.5-official
Point de terminaison d'inférence :https://api.toapis.com/v1/videos/generations
Articles liés : Guide pratique Grok Video · Accès compatible OpenAI · Génération Imagine officielle · Extend Imagine officiel
1. Résumé et vue d'ensemble des performances
- IDs : les requêtes intitulées « Grok Imagine 1.0 » ont besoin des chaînes que ToAPIs publie réellement. L'instantané public du catalogue daté du 2026-11-10 liste
grok-imagine-video-officialetgrok-imagine-video-1.5-official(ces deux apparaissent aussi sous génération d'images ainsi que sousopenai-video). Une vérification du 2026-11-17 d'un chemin de documentationgrok-imagine-1.0a renvoyé HTTP 404. - Auth : envoyez
Authorization: Bearer $TOAPIS_API_KEY. Les pages officielles ne documentent ni scopes OAuth, ni noms de permissions granulaires, ni point de terminaison de découverte de scopes pour ces appels. - Points de terminaison : créez avec
POST /v1/videos/generations. Interrogez avecGET /v1/videos/generations/{id}. Prolongez la sortie du canal officiel avecPOST /v1/videos/{video_id}/extend, ou avecPOST /v1/videos/extendplusvideo_urlslorsque vous n'avez qu'une URL publique de vidéo. Téléversez des images fixes avecPOST /v1/uploads/images. - Capacités :
grok-imagine-video-officialcouvre texte vers vidéo, image vers vidéo et génération multi-référence en480pou720p, durée 1–15 secondes, et extend de 2–10 secondes.grok-imagine-video-1.5-officialest uniquement image vers vidéo avec première image, exige exactement uneimage, autorise1080pet ne prend pas en charge extend. - Forme du prix (aucun prix unitaire fixe sur les pages de référence) : la sortie est facturée à la seconde selon la résolution ; chaque image d'entrée est facturée par image ; extend facture aussi la durée de la vidéo source. Confirmez les tarifs en vigueur de votre compte.
2. Points de terminaison, authentification et contrats de modèle
La documentation officielle utilise https://toapis.com (et https://toapis.cn pour la Chine continentale). D'autres guides de cette série utilisent https://api.toapis.com. Choisissez une origine et restez cohérent. Chaque chemin ci-dessous utilise le même en-tête Bearer.
| Action | Méthode et chemin | Notes de modèle |
|---|---|---|
| Téléverser une image fixe | POST /v1/uploads/images | file multipart. JPEG, PNG, WebP ou GIF, 30 Mo maximum. Lire data.url |
| Créer une vidéo | POST /v1/videos/generations | Les deux IDs Imagine officiels |
| Interroger le statut | GET /v1/videos/generations/{id} | Même chemin pour les tâches de génération et d'extend |
| Prolonger depuis une tâche antérieure | POST /v1/videos/{video_id}/extend | grok-imagine-video-official uniquement. video_id est l'id de la tâche de génération précédente |
| Prolonger depuis une URL publique | POST /v1/videos/extend | Même ID officiel ; video_urls est requis lorsqu'il n'y a pas d'id dans le chemin |
| ID de catalogue | Tâches documentées | Durée | Résolution | Images | Extend |
|---|---|---|---|---|---|
grok-imagine-video-official | Texte vers vidéo, première image et multi-référence | 1–15 secondes (par défaut 8) | 480p, 720p | image facultative plus reference_images ; jusqu'à 7 au total | 2–10 secondes (duration par défaut 6) |
grok-imagine-video-1.5-official | Image vers vidéo avec première image uniquement | 1–15 secondes (par défaut 8) | 480p, 720p, 1080p | image est obligatoire (exactement une première image). Les reference_images supplémentaires comptent toujours dans le total de 7 images | Non pris en charge |
Les valeurs de ratio dans les références Imagine officielles incluent 16:9, 9:16, 4:3, 3:4, 3:2, 2:3 et 1:1. Envoyez une valeur que vous avez confirmée pour cet ID et ce canal.
Il n'existe aucune chaîne de scope publique documentée pour demander « générer », « prolonger » ou « téléverser » séparément. L'accès correspond à ce que la clé API, le groupe d'utilisateurs et la configuration du canal autorisent déjà. Si un appel échoue pour une raison de permission ou de disponibilité, consultez la liste de modèles de la clé et la référence des erreurs au lieu d'ajouter un paramètre de requête scope inventé.

Figure 1 : une seule clé API Bearer autorise le téléversement, la génération ou l'extend et l'interrogation de statut ; l'ID officiel 1.5 n'ajoute pas de branche extend.
Pour la famille Grok Video non officielle (grok-video-1.0 / grok-video-1.5), consultez le guide pratique Grok Video. Ces IDs relèvent d'un autre contrat et n'héritent pas de ce chemin extend.
3. Implémentation en production : cURL et Python
Étape 1 : cURL — texte vers vidéo sur le canal officiel
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-video-official",
"prompt": "A golden retriever running on a green field in sunny weather",
"duration": 10,
"resolution": "720p",
"aspect_ratio": "16:9"
}'
Une tâche avec première image sur grok-imagine-video-1.5-official utilise le même chemin, exige "image": "https://example.com/portrait.jpg" et peut définir "resolution": "1080p". Remplacez l'URL d'exemple par une adresse publique — téléversez d'abord le fichier s'il est local :
curl -X POST "https://api.toapis.com/v1/uploads/images" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-F "file=@/path/to/first-frame.jpg"
Étape 2 : Python — générer, interroger et extend facultatif
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_imagine(
prompt: str,
*,
model: str = "grok-imagine-video-official",
duration: int = 10,
resolution: str = "720p",
aspect_ratio: str = "16:9",
image_url: str | None = None,
reference_images: list[str] | None = None,
) -> str:
if model == "grok-imagine-video-1.5-official" and not image_url:
raise ValueError("grok-imagine-video-1.5-official requires exactly one first-frame image")
payload = {
"model": model,
"prompt": prompt,
"duration": duration,
"resolution": resolution,
"aspect_ratio": aspect_ratio,
}
if image_url:
payload["image"] = image_url
if reference_images:
payload["reference_images"] = reference_images
res = requests.post(
f"{BASE}/v1/videos/generations",
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) -> dict:
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={"Authorization": f"Bearer {API_KEY}"}, 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
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")
def extend_official(source_task_id: str, prompt: str, duration: int = 6) -> str:
if not (2 <= duration <= 10):
raise ValueError("official extend duration is documented as 2-10 seconds")
res = requests.post(
f"{BASE}/v1/videos/{source_task_id}/extend",
headers=HEADERS,
json={
"model": "grok-imagine-video-official",
"prompt": prompt,
"duration": duration,
},
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 extend envelope: {data}")
return task_id
if __name__ == "__main__":
task_id = dispatch_imagine(
"A golden retriever running on a green field in sunny weather",
duration=10,
resolution="720p",
)
print("Task:", task_id)
result = poll_task(task_id)
print("Video:", result["result"]["data"][0]["url"])
Pour prolonger depuis un MP4 public au lieu d'un id de tâche, utilisez POST /v1/videos/extend avec le même modèle officiel, le prompt, duration et une liste video_urls. N'appelez pas extend avec grok-imagine-video-1.5-official.
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. La référence des erreurs distingue les erreurs de requête, les valeurs error.reason des tâches échouées et les payloads de webhook.
| État HTTP ou de tâche | Catégorie courante | Action recommandée |
|---|---|---|
400 | Champ invalide, image obligatoire manquante sur 1.5-official, dépassement du nombre d'images ou extend envoyé à un modèle qui ne le prend pas en charge | Vérifiez l'ID officiel exact, la durée (1–15 en génération, 2–10 en extend), la résolution (1080p uniquement sur 1.5-official) et que toutes les valeurs de média sont des URL publiques |
401 | Clé API absente ou invalide | Faites tourner la clé et confirmez Authorization: Bearer. N'ajoutez pas de paramètre scope non documenté comme contournement |
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 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 |
status: failed avec content_policy_rejected | Contrôle de sécurité ou de droits d'auteur | Inspectez le prompt et chaque asset de référence ; une entrée conforme peut malgré tout produire une sortie rejetée |
status: failed avec insufficient_user_balance ou token_quota_exceeded | Solde ou quota de jetons | Vérifiez à la fois le solde et les limites périodiques |
status: failed avec generation_timeout, model_unavailable ou service_busy | Expiration ou disponibilité en amont | Vérifiez d'abord l'id existant ; ne réessayez avec backoff que si la tâche est terminale |
5. Tarifs et retour sur investissement FinOps
Les pages officielles de génération et d'extend d'Imagine décrivent une forme de facturation, pas un prix unitaire public fixe :
Utilisez les tarifs renvoyés pour votre compte et votre SKU, pas des chiffres de brouillon.
grok-imagine-video-1.5-officialinclut toujours une facturation d'image d'entrée, car une image de première image est obligatoire.- Extend n'est pas une continuation gratuite. La facturation extend officielle inclut les secondes d'extension générées et la durée de la vidéo source. Les extends empilés refacturent donc la longueur source croissante — confirmez ce comportement avec un devis en vigueur avant de construire une boucle.
- Ne réutilisez pas les prix unitaires ni les chiffres de SLA des brouillons de planification. 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 du compte.
- Travaillez en
720pavec une durée intermédiaire, ne changez qu'une variable à la fois et ne resoumettez jamais après une expiration côté client tant que l'état de la tâche n'est pas vérifié.
6. Questions fréquentes
Voir le bloc FAQ du frontmatter. En résumé : envoyez grok-imagine-video-official ou grok-imagine-video-1.5-official, pas grok-imagine-1.0 ; l'authentification est une clé API Bearer sans matrice publique de scopes OAuth ; 1.5-official est uniquement première image et ne peut pas prolonger ; la durée extend est de 2 à 10 secondes et facture aussi la longueur source ; distinguez toujours les erreurs HTTP de status: failed.
7. Liste d'actions
- Créez une clé sur le portail développeur ToAPIs.
- Confirmez que
grok-imagine-video-officialougrok-imagine-video-1.5-officialapparaît pour votre clé viaGET /v1/models?type=video. - Testez rapidement une génération officielle en
720p, interrogezGET /v1/videos/generations/{id}et téléchargez le fichier avantexpires_at. - Si vous avez besoin d'une continuation, prolongez uniquement avec
grok-imagine-video-officialet unedurationde 2 à 10 secondes, puis confirmez que le devis inclut la facturation de la durée source. - Étape suivante : le guide officiel du modèle Imagine et le guide officiel du modèle Imagine 1.5 pour l'état du catalogue en production, et le guide pratique Grok Video si vous visiez la famille non officielle
grok-video-*.







