> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Documentation d'intégration de l'API de génération de vidéos Grok

> Grok API guide - Ace Data Cloud

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](https://platform.acedata.cloud/console/applications) pour le garder en sécurité.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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](https://platform.acedata.cloud/console/coin).

> 📘 Documentation complète : [API de génération de vidéos Grok →](https://platform.acedata.cloud/documents/grok-videos)

## Description du modèle

Cette API choisit le point de terminaison en amont en fonction du suffixe du nom du modèle : `:reverse` utilise le point de terminaison rapide/standard (moins cher), `:official` utilise le point de terminaison officiel (qualité d'image plus élevée, facturation par seconde de sortie). Quatre modèles sont pris en charge :

* `grok-imagine-video-1.5-fast:reverse` (par défaut) : prend en charge les vidéos générées par texte (uniquement en passant `prompt`) et les vidéos générées par image (en passant `image_url`), durée de 6 à 30 secondes, facturation par tranche de durée, le moins cher.
* `grok-imagine-video:reverse` : prend en charge les vidéos générées par texte et par image, durée de 1 à 15 secondes, facturation par seconde de sortie.
* `grok-imagine-video:official` : point de terminaison officiel, prend en charge les vidéos générées par texte et par image, durée de 1 à 15 secondes, facturation par seconde de sortie, qualité d'image plus élevée.
* `grok-imagine-video-1.5:official` : point de terminaison officiel, **prend uniquement en charge les vidéos générées par image**, **doit** passer `image_url`, durée de 1 à 15 secondes, prend en charge jusqu'à `1080p`, facturation par seconde de sortie.

## 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 :

```json theme={null}
{
  "success": true,
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
  "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
  "data": [
    {
      "id": "grok-imagine-video-1.5-fast:reverse:41eb9a5f-3b2d-4d1e-9f5a-6c2f1a0b9e77",
      "video_url": "https://cdn.acedata.cloud/c8cbf53aa0.mp4",
      "state": "succeeded"
    }
  ]
}
```

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 :

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/grok/videos' \
-H 'authorization: Bearer ${bearer_token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "resolution": "480p",
  "duration": 6
}'
```

Le code Python correspondant est le suivant :

```python theme={null}
import requests

url = "https://api.acedata.cloud/grok/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
    "model": "grok-imagine-video-1.5-fast:reverse",
    "resolution": "480p",
    "duration": 6
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

## 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 :

```json theme={null}
{
  "prompt": "The character slowly turns around and smiles at the camera",
  "model": "grok-imagine-video-1.5:official",
  "image_url": "https://cdn.acedata.cloud/5hmkdg.jpg",
  "resolution": "720p",
  "duration": 6
}
```

## 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` :

```json theme={null}
{
  "prompt": "A character dancing in the same art style",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "reference_image_urls": [
    "https://cdn.acedata.cloud/vunnjf.png"
  ]
}
```

## 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 :

```json theme={null}
{
  "prompt": "Une prise de vue cinématographique d'un chaton poursuivant un papillon dans un jardin ensoleillé",
  "model": "grok-imagine-video-1.5-fast:reverse",
  "duration": 6,
  "callback_url": "https://your-domain.com/callback/grok"
}
```

Le résultat renvoyé immédiatement est le suivant :

```json theme={null}
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
```

## 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](https://platform.acedata.cloud/documents/grok-tasks) (`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 le `model` :

* `grok-imagine-video-1.5-fast:reverse` : facturation par tranche de durée, sans rapport avec la résolution — `6–10` secondes, `11–20` secondes, `21–30` secondes correspondent respectivement à différents niveaux de prix.
* `grok-imagine-video:reverse` : facturation par « secondes de sortie », prix total = prix unitaire × `duration`.
* `grok-imagine-video:official` et `grok-imagine-video-1.5:official` : points de terminaison officiels, facturation par « secondes de sortie », plus la résolution est élevée, plus le prix unitaire est élevé ; les modèles officiels seront facturés même si l'examen du contenu échoue.

Le prix unitaire exact est conforme à la page de tarification. Les demandes échouées ne sont pas facturées et ne consomment pas de 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.