Passer au contenu principal
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 :
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 :
Le code Python correspondant est le suivant :

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 :

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

Il est possible de directement « fournir une vidéo en entrée et générer une nouvelle vidéo » : transmettez un lien vers une vidéo de référence (1 maximum) dans video_urls, fournissez simultanément au moins une image de référence dans image_urls, puis décrivez l’effet d’édition souhaité dans prompt (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 une scène hivernale sous d’abondantes chutes de neige, tout en conservant la disposition de la plage, des palmiers et du bateau. L’édition vidéo prend davantage de temps (environ 6,5 minutes dans cet exemple) ; elle est donc soumise de manière asynchrone avec async: true :
Après la soumission, l’API renvoie immédiatement task_id :
Utilisez ensuite ce task_id comme id pour interroger l’API Gemini Tasks. Une fois la tâche terminée, vous pourrez récupérer la nouvelle vidéo générée (il s’agit du résultat réel renvoyé pour cet exemple) :
Pour un résultat en plus haute définition, définissez resolution sur 1080p (les autres paramètres restent inchangés).
Conseil : les liens multimédias d’entrée/sortie des exemples correspondent à de vrais résultats 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 deviennent invalides après expiration ; veuillez les télécharger et les enregistrer dans votre propre espace de stockage dès réception des résultats.
Attention : un maximum de 1 vidéo de référence est autorisé ; si video_urls est fourni, au moins une image image_urls doit également être fournie, sinon l’erreur de paramètre suivante sera renvoyée :

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 :
Le résultat immédiatement retourné est le suivant :

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

Gestion des erreurs

En cas de problème avec la requête, l’API renvoie le code d’erreur correspondant et sa description. 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 : échec de l’authentification ; le jeton est invalide ou ne correspond pas à l’API.
  • 403 : solde insuffisant, ou la requête a été rejetée car l’invite a déclenché la modération du contenu.
  • 500 : erreur de service ou échec de la génération.