Guide de l’API Gemini pour la compréhension vidéo agentique

On n’analyse pas de la même manière un cours de deux heures et une démonstration produit de 20 secondes. Pour les vidéos longues ou les questions ciblant des moments précis, le nouveau mode de compréhension vidéo agentique de Gemini constitue un meilleur point de départ. Attention toutefois : les économies annoncées par Google sont des résultats de benchmark. Elles ne garantissent pas une baisse de 66 % sur chaque facture API.

Choisissez le mode selon la tâche, pas selon la durée de la vidéo

La compréhension vidéo agentique de Gemini est particulièrement adaptée aux questions qui nécessitent de retrouver ou de réexaminer des moments précis. Le traitement statique reste plus simple lorsqu’il faut répondre rapidement sur une courte séquence ou couvrir de façon uniforme chaque intervalle échantillonné.

Google met en avant quatre cas d’usage au lancement : retrouver un moment à la fraction de seconde, effectuer une recherche de type « aiguille dans une botte de foin » sur des contenus longs, détecter des anomalies et compter des actions ou des objets. L’annonce officielle cite des exemples allant de tutoriels de 10 minutes à des cours de 90 minutes et des enregistrements de plusieurs heures.

Aucun seuil de durée officiel n’a été publié : une vidéo de cinq minutes contenant un événement difficile à repérer peut justifier le traitement agentique, tandis qu’un long enregistrement uniforme ne le nécessitera pas forcément.

Une fonctionnalité, deux formats de requête API

« Agentique » ne correspond pas à un champ JSON universel. L’exemple de lancement de Google utilise l’API Interactions et place processing: "agentic" dans l’entrée vidéo ; avec GenerateContent, le traitement du média est exposé dans la partie consacrée au média.

Interactions API : définissez le traitement dans l’entrée vidéo

Dans son article de lancement, Google présente ce modèle Python pour une vidéo YouTube :

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.7-flash",
    input=[
        {
            "type": "video",
            "uri": "https://youtu.be/7Z5Vy9JBANs",
            "processing": "agentic"
        },
        {
            "type": "text",
            "text": "What are the 3 most important announcements in this keynote?",
        },
    ],
)

print(interaction.output_text)

Le paramètre doit se trouver sur l’objet vidéo, et non dans un champ de premier niveau sans rapport.

GenerateContent : définissez le traitement dans la partie média

La documentation consacrée à la compréhension vidéo de Gemini décrit séparément le format GenerateContent. Dans cette structure de requête, l’entrée média utilise media_processing: "AGENTIC" ; en JavaScript, la propriété correspondante s’écrit en camelCase : mediaProcessing.

Voici à quoi ressemble une structure Python minimale :

from google import genai
from google.genai import types

client = genai.Client()
video_uri = "YOUR_VIDEO_FILE_URI"

response = client.models.generate_content(
    model="gemini-3.7-flash",
    contents=[
        types.Part.from_uri(
            file_uri=video_uri,
            mime_type="video/mp4",
            media_processing="AGENTIC",
        ),
        "Find the first product announcement and return its timestamp.",
    ],
)

print(response.text)

Pour une vidéo locale, remplacez YOUR_VIDEO_FILE_URI par l’URI renvoyée par le processus d’import de fichiers Gemini, puis attendez que le fichier soit prêt avant d’envoyer la partie média. Consultez le guide officiel actuel consacré à la compréhension vidéo afin de vérifier les détails du SDK correspondant à la version de votre client.

Ne réutilisez pas les extraits tels quels lorsque vous passez de client.interactions.create à generateContent.

Ce que fait réellement la compréhension vidéo agentique

Le traitement vidéo statique échantillonne la vidéo à une fréquence fixe. Google indique que la valeur par défaut est de 1 image par seconde, avec une fréquence ajustable via l’API, puis fournit ces images au modèle pour analyse.

Le mode agentique permet à Gemini de parcourir la timeline, de choisir une vitesse d’analyse adaptée et de s’appuyer sur les images, l’audio ou les transcriptions, plutôt que de charger l’enregistrement entier de manière uniforme :

1. Demander le segment ou la modalité pertinente pour la question.
2. Examiner les images, l’audio ou la transcription renvoyés.
3. Revenir sur un intervalle plus étroit lorsqu’une précision temporelle supérieure est nécessaire.

L’échantillonnage statique fournit une règle de couverture simple pour les développeurs. Le traitement agentique laisse davantage au modèle le soin de décider où chercher. En production, il faut donc vérifier les timestamps et les décomptes sur des vidéos représentatives.

L’économie annoncée ne correspond pas à une remise de 66 %

Google rapporte les résultats suivants sur des benchmarks standards d’analyse vidéo, avec les gains les plus importants observés sur les contenus longs :

Selon l’annonce de lancement de Google, la compréhension vidéo agentique utilise la tarification standard des tokens de l’API Gemini et ne facture pas de supplément pour cette fonctionnalité. Le coût réel dépend néanmoins du modèle, du contenu récupéré, de la requête et de la sortie. Pour le détail de la tarification des tokens et des modèles, consultez le guide des tarifs de l’API Gemini 3.7 Flash.

Si vous posez régulièrement les mêmes questions sur un même enregistrement, mettez en cache le contexte vidéo lorsque le workflow de l’API le permet. Les retours pratiques de Google Cloud sur l’analyse vidéo présentent la mise en cache du contexte comme un levier important pour réduire les coûts lors d’analyses répétées.

Disponibilité et limites du déploiement

La compréhension vidéo agentique est une capacité de traitement proposée sur trois modèles de la famille Flash, et non un modèle vidéo distinct annoncé séparément. Google indique un lancement le 1er septembre 2026 pour les modèles et surfaces suivants :

Les déploiements prévus pour l’application grand public et YouTube ne prouvent pas que la fonctionnalité est déjà disponible pour tous les comptes.

Quatre tests à mener en production avant d’en faire le mode par défaut

L’annonce de lancement présente des promesses de capacité, mais elle ne permet pas de savoir comment le mode se comportera sur vos propres vidéos. Constituez un petit jeu d’évaluation avant de remplacer un workflow statique existant.

1. Recherche de timestamps : Incluez des séquences avec des changements de plan, des apparitions très brèves et un événement dont les heures de début et de fin exactes sont importantes. Comparez les timestamps renvoyés avec une référence vérifiée par un humain.
2. Comptage d’actions rapides : Utilisez des vidéos contenant des mouvements répétés ou des objets traversant le cadre. Vérifiez le total et assurez-vous que la réponse précise la fenêtre de comptage.
3. Ancrage audio et transcription : Posez des questions pour lesquelles les paroles prononcées et l’action visible divergent. Vérifiez que la réponse ne remplace pas implicitement une modalité par l’autre.
4. Comportement opérationnel : Exécutez les mêmes fichiers dans les deux modes et consignez les tokens d’entrée et de sortie, la latence totale, les nouvelles tentatives, les réponses vides, les événements manqués et le résultat obtenu avec le fallback statique. Conservez ce fallback si la récupération sélective manque des éléments ou ajoute un délai inacceptable.

Ne définissez pas une règle rigide du type « utiliser le mode agentique au-delà de X minutes » à partir de l’article de lancement. Les informations publiées justifient un choix fondé sur la tâche, pas un seuil de durée universel.

FAQ de l’API Gemini pour la compréhension vidéo agentique

La compréhension vidéo agentique est-elle un nouveau modèle Gemini ?

Non. Google la présente comme une capacité de compréhension vidéo disponible avec Gemini 3.7 Flash, Gemini 3.6 Flash et Gemini 3.5 Flash-Lite.

Puis-je utiliser une vidéo importée plutôt qu’une URL YouTube ?

Oui. Google cite les fichiers vidéo importés et les vidéos YouTube parmi les entrées API compatibles. Pour un fichier local, importez-le d’abord, puis transmettez l’URI renvoyée dans la partie média une fois le traitement terminé.

Le traitement vidéo agentique est-il facturé en supplément ?

Google indique qu’aucun supplément n’est appliqué à la fonctionnalité. La tarification normale des tokens de l’API Gemini reste valable, et la facture finale dépend du contenu récupéré ainsi que du reste de la requête.

Faites passer un échantillon représentatif dans les deux modes, puis ne retenez le traitement agentique comme mode par défaut que là où la qualité des éléments récupérés et le coût mesuré des tokens correspondent aux objectifs de l’application.