Passer au contenu principal
Cet article présente la documentation d’intégration de l’API de génération de vidéos Grok, qui peut générer des vidéos Grok Imagine (xAI) en entrant des mots-clés textuels, des images d’entrée et des images de référence optionnelles.

Processus de demande

Pour utiliser l’API de génération de vidéos Grok, commencez par obtenir votre jeton API sur le tableau de bord Ace Data Cloud pour le garder en sécurité. Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion vous invitant à vous inscrire et à vous connecter, après quoi vous serez automatiquement renvoyé à la page actuelle. Un jeton API suffit pour appeler tous les services de la plateforme, sans avoir à en demander un pour chaque service. La première demande vous donnera un quota gratuit pour une expérience sans frais ; si le quota est insuffisant, vous pouvez recharger le solde général dans le tableau de bord.
📘 Documentation complète : API de génération de vidéos Grok →

Description des modèles

Les quatre modèles publics suivants peuvent être sélectionnés via model. Leurs capacités et modes de facturation sont les suivants :
  • grok-imagine-video-1.5-fast:reverse (par défaut) : prend en charge la génération de vidéos à partir de texte (transmettre uniquement prompt) et à partir d’images (transmettre image_url), avec une durée de 6 à 30 secondes ; facturation par paliers selon la durée, c’est l’option la moins chère.
  • grok-imagine-video:reverse : prend en charge la génération de vidéos à partir de texte et d’images, avec une durée de 1 à 15 secondes ; facturation selon le nombre de secondes générées.
  • grok-imagine-video:official : prend en charge la génération de vidéos à partir de texte et d’images, avec une durée de 1 à 15 secondes ; facturation selon le nombre de secondes générées, avec une meilleure qualité d’image.
  • grok-imagine-video-1.5:official : prend uniquement en charge la génération de vidéos à partir d’images ; vous devez transmettre image_url. La durée est de 1 à 15 secondes, prend en charge jusqu’à 1080p, et la facturation s’effectue selon le nombre de secondes générées.

Utilisation de base

Commencez par comprendre les méthodes d’utilisation de base, en entrant les mots-clés prompt, le modèle model, etc., pour générer la vidéo correspondante. Ici, nous avons défini les en-têtes de requête, y compris :
  • accept : le format de réponse souhaité, ici défini sur application/json, c’est-à-dire au format JSON.
  • authorization : la clé d’API pour appeler l’API, que vous pouvez sélectionner directement après la demande.
Nous avons également défini le corps de la requête, y compris :
  • prompt : les mots-clés textuels décrivant le contenu vidéo souhaité. Obligatoire pour les vidéos générées par texte ; optionnel lors du passage de image_url.
  • model : le modèle pour générer la vidéo, pouvant être grok-imagine-video-1.5-fast:reverse (par défaut), grok-imagine-video:reverse, grok-imagine-video:official ou grok-imagine-video-1.5:official.
  • image_url : le lien de l’image d’entrée pour les vidéos générées par image. Obligatoire lorsque model est grok-imagine-video-1.5:official.
  • reference_image_urls : tableau d’URL d’images de référence optionnelles pour guider le style ou le contenu de la vidéo.
  • aspect_ratio : le rapport d’aspect de la vidéo générée, pouvant être 1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3.
  • resolution : la résolution de sortie, pouvant être 480p (par défaut), 720p ou 1080p.
  • duration : la durée de la vidéo générée (en secondes). grok-imagine-video-1.5-fast:reverse a une plage de valeurs de 6 à 30, les autres modèles de 1 à 15, par défaut 6. Il est recommandé d’utiliser 6 secondes ou 10 secondes, ces deux durées standard étant relativement stables.
  • callback_url : adresse de rappel asynchrone, une fois définie, l’API renverra immédiatement task_id, et lorsque la tâche sera terminée, elle POSTera le résultat à cette adresse.
  • async : optionnel, si défini sur true, l’interface renvoie immédiatement task_id, sans avoir besoin de fournir callback_url, puis vous pouvez interroger le résultat via l’interface de requête de tâche correspondante.
Cliquez sur le bouton « Essayer » pour effectuer un test, le résultat obtenu sera similaire à ceci :
Le résultat de retour contient plusieurs champs, décrits comme suit :
  • success : indique si la demande de génération de vidéo a réussi.
  • task_id : l’ID de la tâche de génération de vidéo.
  • trace_id : l’ID de suivi de la demande, utilisé pour le dépannage.
  • data : liste des résultats vidéo générés.
    • id : identifiant unique de la vidéo générée.
    • video_url : adresse du lien de la vidéo générée.
    • state : état de la tâche de génération de vidéo, pouvant être pending / succeeded / failed.
Nous devons simplement récupérer la vidéo générée à partir de l’adresse video_url dans le résultat data. Le code CURL correspondant est le suivant :
Le code Python correspondant est le suivant :

Vidéo générée par image

Si vous souhaitez générer une vidéo à partir d’une image d’entrée, vous pouvez passer image_url. Lors de l’utilisation de grok-imagine-video-1.5:official, ce champ doit être fourni :

Guidage par image de référence

Si vous souhaitez utiliser une ou plusieurs images de référence pour guider le style ou le contenu de la vidéo générée, vous pouvez passer un tableau d’URL d’images dans reference_image_urls :

Rappel asynchrone

La génération de vidéos nécessite un certain temps de traitement. Si vous ne souhaitez pas maintenir une connexion longue en attendant, vous pouvez passer un callback_url, auquel cas l’API renverra immédiatement un task_id, et une fois la tâche terminée, le résultat final sera POSTé à cette adresse :
Le résultat renvoyé immédiatement est le suivant :

Vérification des résultats de la tâche

Si vous avez utilisé un rappel asynchrone ou si vous souhaitez interroger activement l’état de la tâche, vous pouvez utiliser Grok Tasks API (POST https://api.acedata.cloud/grok/tasks) pour interroger l’état et le résultat les plus récents de la tâche en fonction du task_id.

Informations de facturation

Le mode de facturation de ce service est déterminé par model :
  • grok-imagine-video-1.5-fast:reverse : facturation par paliers selon la durée, indépendamment de la résolution — 6–10 secondes, 11–20 secondes et 21–30 secondes correspondent chacun à un tarif différent.
  • grok-imagine-video:reverse : facturation selon les « secondes générées » ; prix total = prix unitaire × duration.
  • grok-imagine-video:official et grok-imagine-video-1.5:official : facturation selon les « secondes générées » ; plus la résolution est élevée, plus le prix unitaire est élevé. Les modèles officiels sont facturés même si la modération du contenu échoue.
Les prix unitaires exacts sont indiqués sur la page de tarification. Les requêtes échouées ne sont pas facturées et ne consomment pas le quota gratuit.

Gestion des erreurs

Lorsque la demande rencontre un problème, l’API renverra le code d’erreur correspondant et une explication, les plus courants sont les suivants :
  • 400 : paramètres de demande incorrects, par exemple, la vidéo générée manque de prompt, ou grok-imagine-video-1.5:official manque de image_url, ou duration dépasse la plage (pour grok-imagine-video-1.5-fast:reverse, c’est 6–30, pour les autres modèles c’est 1–15).
  • 401 : échec de l’authentification, token invalide ou ne correspondant pas à l’API.
  • 403 : solde insuffisant, ou le mot-clé a été rejeté par l’examen de contenu.
  • 429 : trop de demandes, veuillez réessayer plus tard.
  • 500 : échec de la génération de vidéo ou anomalie de service.