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

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 et conservez-le pour une utilisation ultérieure.

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.

📘 Documentation complète : Gemini Videos Generation API →

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 :

{
  "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 :

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 :

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 :

{
  "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 :

{
  "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 :

{
  "task_id": "cd68b4ee-de70-4c94-ac69-997a3fed0284"
}

Utilisez ensuite ce task_id comme id pour interroger l’API 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) :

{
  "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 :

{
  "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 :

{
  "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 :

{
  "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 (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 :

{
  "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) :

{
  "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.

Démarrage

Chat IA

Image IA

Vidéo IA

Audio IA

Web & Données

CAPTCHA

Identité

Coding

Autres guides

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

Processus de demande

Utilisation de base

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

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

Rappel asynchrone

Interroger le résultat de la tâche

Gestion des erreurs

​Processus de demande

​Utilisation de base

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

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

​Rappel asynchrone

​Interroger le résultat de la tâche

​Gestion des erreurs

Processus de demande

Utilisation de base

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

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

Rappel asynchrone

Interroger le résultat de la tâche

Gestion des erreurs