Les analystes de contenu, les chercheurs en expérience utilisateur (UX) et les spécialistes des études de marché traitent quotidiennement des heures d'enregistrements vidéo : tests d'utilisabilité, entretiens de groupe, conférences universitaires, annonces de résultats financiers et webinaires professionnels. Traditionnellement, l'extraction d'un journal d'événements structuré imposait une chaîne d'outils morcelée : transcrire la voix par reconnaissance automatique de la parole (ASR), développer des scripts de vision par ordinateur pour repérer les changements de diapositives, puis synchroniser manuellement les codes temporels.
La compréhension vidéo multimodale native de Google Gemini révolutionne cette méthodologie. Grâce à des fenêtres de contexte étendues (1 million de tokens et plus) et à une synchronisation audiovisuelle native, les modèles Gemini (dont Gemini 3.8 Flash, Gemini 3.7 Flash et Gemini 2.5 Pro) ingèrent directement des fichiers vidéo bruts. Les chercheurs peuvent interroger des heures d'enregistrements en langage naturel, croiser les déclarations orales avec les actions visibles à l'écran et extraire des répertoires d'événements précis au format d'horodatage MM:SS.
Ce guide détaille la mise en place d'un flux d'analyse de qualité professionnelle via l'API Files de Gemini, le choix entre le mode statique et le mode agentique, l'application de schémas JSON stricts et la réduction drastique des coûts d'analyse itérative grâce à la mise en cache de contexte (Context Caching).
1. Choix du mode de traitement : Statique vs Agentique
Gemini propose deux modes d'exécution pour la vidéo. Choisir le mode adéquat est déterminant pour équilibrer la consommation de tokens, la rapidité d'exécution et la finesse de l'analyse.
| Dimension | Traitement statique (Par défaut) | Compréhension vidéo agentique (Agentic Mode) |
|---|---|---|
| Mécanisme | Échantillonne les images à fréquence fixe (par défaut 1 FPS) et décode l'audio à 1 kbit/s, chargeant l'intégralité du contenu dans le contexte en une seule passe | Fonctionne selon une boucle Think-Act-Observe ; le modèle explore activement la chronologie et charge transcripts, audio ou images ciblées à la demande |
| Consommation de tokens | ~100 tokens/seconde en basse résolution ; ~300 tokens/seconde en haute résolution | Jusqu'à 88 % de tokens d'entrée en moins sur les vidéos longues ; le raisonnement compte en tokens de réflexion et les médias en tokens d'outils |
| Délai du premier token (TTFT) | Immédiat sur les vidéos courtes (<5 minutes) | Latence initiale légèrement supérieure en raison de la planification et des allers-retours d'outils sur le serveur |
| Cas d'usage recommandés | Audits visuels continus image par image, clips courts, mouvements rapides sans intervention orale | Enregistrements de 15 à 180 minutes, recherche de sujets précis, découpage en chapitres et synthèses d'événements |
| Modèles compatibles | L'ensemble des modèles Gemini | Gemini 3.8 Flash, Gemini 3.7 Flash, 3.6 Flash, 3.5 Flash Lite |
Quand privilégier le mode agentique
Pour les enregistrements de plus de 15 minutes, le mode agentique ("processing": "agentic") est vivement recommandé. Transférer des dizaines de milliers d'images statiques dans le contexte engendre des coûts élevés et risque de diluer l'attention du modèle. En mode agentique, le modèle commence par parcourir la transcription textuelle pour repérer les passages clés, puis ne télécharge des images en haute résolution que lorsqu'une preuve visuelle est requise (par exemple, vérifier un clic sur un bouton ou un schéma sur un tableau blanc). Cette méthode réduit les coûts de tokens d'entrée jusqu'à 66 % tout en augmentant la précision des réponses d'environ 7 %.
Quand retenir le mode statique
Si votre recherche porte sur des comportements visuels continus et silencieux — tels que les mouvements oculaires, les micro-expressions ou des parcours d'interface sans commentaire à voix haute —, le mode statique assure une couverture temporelle absolue. Vous pouvez également ajuster la fréquence d'échantillonnage (par exemple fps: 0.5 pour une image toutes les deux secondes) afin d'analyser jusqu'à 3 heures d'affilée sans dépasser la limite de 1 million de tokens.
2. Ingestion de longues séquences via l'API Files
L'envoi de vidéos directement en ligne (base64 dans le corps de requête) est réservé aux petits fichiers de moins de 20 Mo (ou 100 Mo selon le point de terminaison). Pour les enregistrements d'études volumineux, utilisez impérativement l'API Files. Celle-ci accepte des fichiers allant jusqu'à 20 Go dans les offres payantes (2 Go dans l'offre gratuite) et prend en charge les formats standards tels que MP4, MOV, MPEG, WEBM et AVI.
L'ingestion se déroule en deux étapes asynchrones :
- Téléversement avec reprise : Envoi du fichier multimédia vers le stockage managé de Gemini.
- Sondage de statut : Attente de la fin du transcodage et de l'indexation par le serveur, jusqu'à ce que l'état passe de
PROCESSINGàACTIVE.
Les fichiers restent accessibles dans votre projet pendant 48 heures sans frais de stockage supplémentaires, ce qui permet de conduire de multiples séries d'analyses qualitatives au cours d'une même journée.
3. Ingénierie de prompt et structuration JSON
Afin que les données extraites s'intègrent directement dans vos bases de données de recherche ou vos tableaux de bord, il est crucial d'imposer des conventions temporelles et des schémas stricts :
- Format d'horodatage explicite : Gemini gère nativement le format
MM:SS(ouHH:MM:SSpour les enregistrements de plusieurs heures). Ordonnez explicitement au modèle d'indiquer l'horodatage de début et de fin de chaque séquence. - Validation croisée multimodale : Exigez du modèle qu'il confronte les paroles et les images. Exemple : « Vérifiez si le doute exprimé par le participant à 14:20 correspond à l'affichage d'un message d'erreur à l'écran. »
- Schéma JSON obligatoire : Définissez
response_mime_type: "application/json"associé à un schéma Pydantic pour obtenir obligatoirement les champstimestamp_start,timestamp_end,event_type,summary,visual_evidenceetverbal_quote, éliminant toute formule de politesse superflue. - Positionnement du prompt : Dans le tableau de contenu de la requête, placez systématiquement le prompt textuel après l'objet vidéo.
4. Script d'implémentation complet en Python
Le code Python ci-dessous illustre comment un chercheur peut téléverser un entretien d'utilisabilité de 60 minutes, activer le mode agentique avec exécution asynchrone en arrière-plan (background=True) et récupérer une synthèse structurée des événements :
import time
from google import genai
from google.genai import types
from pydantic import BaseModel, Field
# 1. Initialiser le client
client = genai.Client()
# 2. Téléverser la vidéo via l'API Files
print("Téléversement de l'enregistrement vidéo...")
video_file = client.files.upload(
file="user_research_session_04.mp4",
config={"mime_type": "video/mp4"}
)
# 3. Attendre la fin du traitement sur le serveur
while video_file.state.name == "PROCESSING":
print("Traitement et indexation de la vidéo sur le serveur, nouvel essai dans 5 secondes...")
time.sleep(5)
video_file = client.files.get(name=video_file.name)
if video_file.state.name == "FAILED":
raise RuntimeError("Le traitement de la vidéo a échoué sur le serveur.")
print(f"Vidéo active disponible à l'URI : {video_file.uri}")
# 4. Définir le schéma de données structurées
class VideoEvent(BaseModel):
timestamp_start: str = Field(description="Début de l'événement au format MM:SS")
timestamp_end: str = Field(description="Fin de l'événement au format MM:SS")
event_type: str = Field(description="Catégorie : Point de friction, Demande d'évolution, Bogue ou Débat")
summary: str = Field(description="Description synthétique de l'événement")
visual_evidence: str = Field(description="Actions visuelles observées à l'écran")
verbal_quote: str = Field(description="Citation textuelle prononcée par l'utilisateur")
class ResearchSummary(BaseModel):
video_overview: str = Field(description="Synthèse exécutive de la session")
events: list[VideoEvent] = Field(description="Liste chronologique des événements horodatés")
# 5. Lancer l'analyse en mode agentique avec exécution en arrière-plan
# background=True prévient les déconnexions réseau lors des raisonnements approfondis
prompt_text = """
Analysez cet enregistrement d'entretien utilisateur.
Identifiez l'ensemble des difficultés d'ergonomie, des demandes de fonctionnalités et des moments de décision.
Croisez les remarques formulées oralement avec les actions à l'écran.
Générez une liste chronologique d'événements assortis d'horodatages précis au format MM:SS.
"""
print("Envoi de la requête d'analyse vidéo agentique...")
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{
"type": "video",
"uri": video_file.uri,
"mime_type": video_file.mime_type,
"processing": "agentic" # Active la navigation dynamique sur la ligne temporelle
},
{
"type": "text",
"text": prompt_text
}
],
response_mime_type="application/json",
response_schema=ResearchSummary,
background=True # Traitement asynchrone côté serveur
)
# 6. Interroger le statut de la tâche en arrière-plan
while interaction.status == "in_progress":
print("Le modèle explore la chronologie et synthétise les preuves...")
time.sleep(5)
interaction = client.interactions.get(interaction.id)
print("\n--- Résultats de l'analyse ---")
print(interaction.output_text)
5. Optimiser les requêtes itératives grâce au Context Caching
En recherche qualitative, on ne pose presque jamais une seule question par vidéo. Les analystes souhaitent successivement cartographier le déroulé, sonder les mentions des concurrents, évaluer l'état émotionnel des participants et analyser des parcours spécifiques.
Téléverser et réanalyser intégralement une vidéo de 90 minutes à chaque nouvelle requête multiplierait les coûts et les temps d'attente. La fonctionnalité de mise en cache de contexte (Context Caching) de Gemini résout cette contrainte :
- Économies substantielles : Le coût des tokens d'entrée mis en cache est réduit de 80 % à 90 % par rapport au tarif d'ingestion classique.
- Accélération des réponses : Les représentations audiovisuelles étant déjà précalculées en mémoire, le délai de génération du premier token diminue drastiquement.
- Mise en œuvre : Via l'API
generateContent, l'analyste crée un objet de cache doté d'une durée de vie définie (TTL, par exemple 2 heures). Toutes les questions ultérieures ciblent simplementcachedContents/<cache-id>, permettant à une équipe d'effectuer des dizaines de requêtes qualitatives détaillées pour un coût minime.
6. Conseils pratiques et écueils à éviter
- Éviter les interruptions de connexion : Sur les vidéos de plus de 15 minutes, l'analyse approfondie peut nécessiter plusieurs minutes. Les requêtes HTTP synchrones risquent d'expirer (renvoyant des erreurs telles que
401 Unauthorizedpour cause d'expiration de jeton). Avec l'API Interactions, utilisez systématiquementbackground=True; avec l'API generateContent, utilisez le streaming (stream=True). - Valider l'exploration agentique : Dans l'objet de réponse, inspectez le champ
interaction.steps. La présence d'étapesprocessing_calletprocessing_resultconfirme que le modèle a activement chargé des segments ciblés plutôt que de déduire ses réponses à partir d'un contexte global compressé. - Régler la résolution des médias : Si l'analyse requiert de lire de petits caractères sur une diapositive, des cellules de tableur ou des lignes de code, configurez
media_resolution: "high". Pour des réunions ou des exposés généraux, la basse résolution par défaut (66 tokens par image) assure un débit optimal au coût le plus bas. - Anticiper le décalage temporel : Il existe fréquemment un léger décalage entre le moment où un interlocuteur prend la parole et l'action correspondante à l'écran. Demander une plage temporelle (
timestamp_startettimestamp_end) plutôt qu'une seconde isolée garantit une précision nettement supérieure lors du calage dans un logiciel de montage vidéo.