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

# Guide d’intégration de l’API Gemini Videos Generation

> Gemini AI API guide - Ace Data Cloud

Cet article présentera le guide d’intégration de l’API Gemini Videos Generation, qui permet de générer des vidéos Google Gemini (omni-flash) à partir de textes d’invite saisis (ainsi que d’images de référence facultatives).

## Processus de demande

Pour utiliser l’API Gemini Videos Generation, obtenez d’abord votre API Token dans la [console Ace Data Cloud](https://platform.acedata.cloud/console/applications) et conservez-le pour une utilisation ultérieure.

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

Si vous n’êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inviter à vous inscrire et à vous connecter. Une fois terminé, vous reviendrez automatiquement sur la page actuelle.

**Un seul API Token permet d’appeler tous les services de la plateforme, sans avoir besoin d’en demander un séparément pour chaque service.** Lors de votre première demande, un quota gratuit vous sera offert pour permettre un essai gratuit ; lorsque le quota est insuffisant, vous pouvez recharger le solde général dans la [console](https://platform.acedata.cloud/console/coin).

> 📘 Documentation complète : [Gemini Videos Generation API →](https://platform.acedata.cloud/documents/gemini-videos)

## Utilisation de base

Commençons par comprendre le mode d’utilisation de base : saisissez le texte d’invite `prompt`, le modèle `model` ainsi que le rapport hauteur/largeur `aspect_ratio` pour générer la vidéo correspondante.

Vous pouvez voir qu’ici nous avons défini les Request Headers, y compris :

* `accept` : le format de résultat de réponse que vous souhaitez recevoir ; ici, il est renseigné comme `application/json`, c’est-à-dire au format JSON.
* `authorization` : la clé pour appeler l’API, qui peut être directement sélectionnée dans la liste déroulante après la demande.

Les paramètres du Request Body sont également définis, y compris :

* `prompt` : le texte d’invite décrivant le contenu vidéo que vous souhaitez générer, **obligatoire**.
* `model` : le modèle de génération vidéo ; actuellement, seul `omni-flash` est pris en charge, et la valeur par défaut est `omni-flash`.
* `aspect_ratio` : le rapport hauteur/largeur de la vidéo générée ; vous pouvez choisir `16:9` (paysage) ou `9:16` (portrait), avec `16:9` par défaut.
* `resolution` : la résolution de sortie facultative ; vous pouvez choisir `720p` ou `1080p`, avec `720p` par défaut.
* `image_urls` : un tableau facultatif de liens d’images de référence, utilisé pour guider la génération vidéo ; les éléments vides seront ignorés. Lors de l’utilisation de `video_urls` pour l’édition vidéo, ce paramètre est obligatoire (au moins une image).
* `video_urls` : un tableau facultatif de liens de vidéos de référence (1 maximum), utilisé pour **l’édition vidéo / la référence vidéo** ; lorsqu’il est fourni, au moins une `image_urls` doit également être fournie.
* `callback_url` : l’adresse de rappel asynchrone ; après sa définition, l’API renvoie immédiatement le `task_id` et envoie le résultat par POST à cette adresse lorsque la tâche est terminée.
* `async` : facultatif ; lorsque défini sur `true`, l’interface renvoie immédiatement le `task_id`, sans nécessiter de fournir `callback_url`, puis le résultat est obtenu en interrogeant l’interface de requête de tâche correspondante.

Cliquez sur le bouton « Try » pour effectuer un test ; le résultat obtenu est similaire au suivant :

```json theme={null}
{
  "success": true,
  "task_id": "9258c45f-bed9-4dde-81c2-a70a710a6904",
  "trace_id": "862d6aae-cec0-407f-9524-bc1be2291bcb",
  "data": [
    {
      "id": "dc4b7292-070c-49a8-8183-919bdf8ad59e",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/9258c45f-bed9-4dde-81c2-a70a710a6904-418c13e0605f.mp4",
      "state": "succeeded",
      "aspect_ratio": "16:9",
      "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden"
    }
  ],
  "started_at": 1784112953.856,
  "finished_at": 1784113021.328,
  "elapsed": 67.472,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}
```

Le résultat retourné contient plusieurs champs, présentés ci-dessous :

* `success` : indique si cette demande de génération vidéo a réussi.
* `task_id` : l’ID de cette tâche de génération vidéo.
* `trace_id` : l’ID de suivi de cette demande, utilisé pour diagnostiquer les problèmes.
* `data` : la liste des résultats vidéo générés.
  * `id` : l’identifiant unique de la vidéo générée.
  * `video_url` : l’adresse du lien de la vidéo générée (`null` lorsque `state` est `pending`).
  * `state` : l’état de la tâche de génération vidéo ; vous pouvez choisir `pending` / `succeeded` / `failed`.
  * `aspect_ratio` : le rapport hauteur/largeur de cette vidéo, identique au paramètre de demande.
  * `prompt` : le texte d’invite utilisé pour générer cette vidéo.

Lors d’un retour synchrone, le niveau supérieur inclut également des champs tels que `started_at`, `finished_at`, `elapsed` (durée, en secondes) et `cost` (coût de cette demande, en Credits).

Il nous suffit d’obtenir la vidéo générée à partir de l’adresse de lien `video_url` dans `data` du résultat.

Le code CURL correspondant est le suivant :

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/gemini/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": "omni-flash",
  "aspect_ratio": "16:9"
}'
```

Le code Python correspondant est le suivant :

```python theme={null}
import requests

url = "https://api.acedata.cloud/gemini/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": "omni-flash",
    "aspect_ratio": "16:9"
}

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

## Génération vidéo à partir d’images

Si vous souhaitez générer une vidéo à partir d’images de référence, vous pouvez transmettre un ou plusieurs liens d’images dans `image_urls` afin de guider la génération vidéo :

```json theme={null}
{
  "prompt": "The woman slowly turns around and smiles at the camera, gentle breeze",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "image_urls": [
    "https://cdn.acedata.cloud/assets/examples/nanobanana/e44bfceb-1458-4b4b-9d10-21024678f1a3-5ccb6e83b402.png"
  ]
}
```

## Édition vidéo / vidéo de référence (vidéo en entrée, vidéo générée)

Il est possible de prendre directement « une vidéo en entrée et de générer une nouvelle vidéo » : transmettez un lien de vidéo de référence dans `video_urls` (1 maximum) et fournissez **simultanément** au moins une image de référence dans `image_urls` (exigence stricte en amont), puis utilisez `prompt` pour décrire l’effet d’édition souhaité (changer le style, modifier la scène, ajouter ou supprimer des éléments, etc.).

Voici un exemple réel complet — transformer une vidéo de plage ensoleillée en scène hivernale sous une forte chute de neige, tout en conservant la disposition de la plage, des cocotiers et du petit bateau. L’édition vidéo prend relativement longtemps (environ 6,5 minutes dans cet exemple), c’est pourquoi elle est soumise de manière asynchrone avec `async: true` :

```json theme={null}
{
  "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout.",
  "model": "omni-flash",
  "aspect_ratio": "9:16",
  "resolution": "720p",
  "image_urls": [
    "https://cdn.acedata.cloud/99289603bd.png"
  ],
  "video_urls": [
    "https://cdn.acedata.cloud/assets/examples/seedance/dd3dc063-3383-4f29-bedc-e771a096758c-044e05281a2a.mp4"
  ],
  "async": true
}
```

Après la soumission, l’API renvoie immédiatement le `task_id` :

```json theme={null}
{
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284"
}
```

Utilisez ensuite ce `task_id` comme `id` pour interroger l’[API Gemini Tasks](https://platform.acedata.cloud/documents/gemini-tasks). Une fois la tâche terminée, vous pourrez obtenir la nouvelle vidéo générée (il s’agit du véritable résultat retourné dans cet exemple) :

```json theme={null}
{
  "success": true,
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284",
  "trace_id": "5b22104b-5a6d-4a4f-8063-69acae1dc1c6",
  "data": [
    {
      "id": "e125d316-3d26-4c65-9413-55baf6be46b8",
      "video_url": "https://cdn.acedata.cloud/assets/examples/sora/cd68b4ee-de70-4c94-ac69-997a3fed0284-c5603ef983da.mp4",
      "state": "succeeded",
      "aspect_ratio": "9:16",
      "prompt": "Turn this sunny tropical beach into a snowy winter scene with heavy falling snow and overcast sky; keep the same beach, palm trees and boat layout."
    }
  ],
  "started_at": 1784084482.914,
  "finished_at": 1784084877.09,
  "elapsed": 394.176,
  "cost": {
    "amount": 1.932,
    "currency": "credit",
    "list_amount": 2.1
  }
}
```

Pour obtenir un résultat en plus haute résolution, vous pouvez définir `resolution` sur `1080p` (les autres paramètres restent inchangés).

> Conseil : les liens médias d’entrée / sortie dans l’exemple sont tous des résultats réellement générés. **Les liens vers les vidéos et images générées par la plateforme ont une durée de conservation limitée et expireront**, veuillez les télécharger et les enregistrer rapidement dans votre propre stockage après avoir obtenu le résultat.

> Attention : au maximum 1 vidéo de référence est autorisée ; et lorsque `video_urls` est fourni, vous devez fournir au moins une `image_urls`, sinon l’erreur de paramètre suivante sera retournée :

```json theme={null}
{
  "success": false,
  "error": {
    "code": "bad_request",
    "message": "image_urls (at least one reference image) is required when video_urls is provided."
  }
}
```

## 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 attente, vous pouvez transmettre `callback_url`. Dans ce cas, l’API renverra immédiatement le `task_id` et enverra le résultat final par POST à cette adresse une fois la tâche terminée :

```json theme={null}
{
  "prompt": "A cinematic shot of a kitten chasing a butterfly in a sunlit garden",
  "model": "omni-flash",
  "aspect_ratio": "16:9",
  "callback_url": "https://your-domain.com/callback/gemini"
}
```

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

```json theme={null}
{
  "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}
```

## Interroger le résultat de la tâche

Si vous avez utilisé un rappel asynchrone ou souhaitez interroger activement l’état de la tâche, vous pouvez utiliser l’[API Gemini Tasks](https://platform.acedata.cloud/documents/gemini-tasks) (`POST https://api.acedata.cloud/gemini/tasks`) pour interroger le dernier état et le résultat de la tâche selon le `task_id`. Transmettez dans le corps de la requête le `task_id` retourné lors de la création de la vidéo comme `id` :

```json theme={null}
{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee"
}
```

Le résultat retourné une fois la tâche terminée est similaire à ce qui suit. La structure de `response.data` est identique à celle lors de la génération synchrone (pendant la génération, `state` est `pending` et `video_url` est `null`) :

```json theme={null}
{
  "id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
  "type": "videos",
  "request": {
    "model": "omni-flash",
    "prompt": "A time-lapse of clouds over snow mountains at sunrise",
    "aspect_ratio": "16:9",
    "async": true
  },
  "response": {
    "success": true,
    "task_id": "04a043bd-6b23-4b4e-945c-ce48158c3eee",
    "data": [
      {
        "id": "486ebd5a-6a4b-406c-84ae-33835de4fe19",
        "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
        "state": "succeeded",
        "aspect_ratio": "16:9",
        "prompt": "A time-lapse of clouds over snow mountains at sunrise"
      }
    ],
    "elapsed": 96.716,
    "cost": {
      "amount": 1.932,
      "currency": "credit",
      "list_amount": 2.1
    }
  }
}
```

## Gestion des erreurs

Lorsqu’un problème survient avec la requête, l’API renvoie le code d’erreur et la description correspondants. Les erreurs courantes sont les suivantes :

* `400` : les paramètres de la requête sont incorrects, par exemple `prompt` est manquant ou la valeur de `aspect_ratio` est invalide.
* `401` : l’authentification a échoué, le token est invalide ou ne correspond pas à l’API.
* `403` : solde insuffisant, ou l’invite a été refusée car elle a déclenché la modération de contenu.
* `500` : erreur interne du serveur ou échec de génération en amont.


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