Analyser des vidéos d’architecture avec l’API Gemini : guide pas à pas

Ce que vous apprendrez dans ce guide

L’API Gemini permet d’extraire des informations de vidéos et de répondre à des questions sur leur contenu. Ce guide présente les étapes à suivre pour analyser des vidéos de présentation de projets architecturaux, de chantiers ou de visites de lieux : choisir le mode de transfert adapté, attendre le traitement du fichier et rédiger des prompts pertinents. Les modèles Gemini peuvent décrire une vidéo, en extraire des informations et faire référence à des horodatages précis. Il est ainsi possible de demander un résumé ou une réponse ciblée, plutôt que de visionner manuellement l’intégralité d’un long enregistrement.

Les exemples présentés ici portent sur la compréhension d’une vidéo existante, et non sur la génération de vidéos. Le guide de Google consacré à la génération vidéo présente Gemini Omni Flash pour cet usage ; la compréhension vidéo est un cas d’utilisation distinct. Bien faire la différence permet d’éviter de choisir le mauvais modèle ou flux de travail pour une demande d’analyse.

Prérequis

Ce flux de travail nécessite un accès à l’API Gemini, un fichier vidéo ou une vidéo YouTube publique, ainsi qu’un prompt textuel. L’exemple officiel utilise le client Python google-genai, Files API et Interactions API. La source ne précisant ni version particulière du SDK ni procédure de création de compte, aucun numéro de version ni condition d’inscription n’est indiqué ici. Configurez l’authentification du client API selon votre environnement ; l’exemple REST de la source utilise la variable GEMINI_API_KEY.

Choisissez le mode de transfert en fonction de la taille du fichier et de la nécessité de le réutiliser :

• Files API : la source recommande cette méthode pour les fichiers de plus de 100 MB, les longues vidéos et les contenus destinés à être réutilisés. La capacité indiquée dans la documentation est de 20 GB pour l’utilisation payante et de 2 GB pour l’utilisation gratuite.

• Cloud Storage Registration : une limite de 2 GB par fichier est indiquée, sans limite de stockage ; cette option est destinée aux contenus volumineux, conservés longtemps et réutilisés.

• Données en ligne : la documentation indique que cette méthode convient aux petits fichiers. Les instructions détaillées recommandent de transférer de courtes vidéos par cette méthode lorsque la taille totale de la requête est inférieure à 20 MB ; en pratique, retenez donc le seuil de 20 MB, plus restrictif.

• URL YouTube : une méthode d’entrée prise en charge pour les vidéos publiques.

Analyse vidéo étape par étape

1. Définissez l’objectif de l’analyse

Avant d’envoyer la vidéo, déterminez clairement le résultat attendu. Pour une présentation de projet, vous pouvez demander un résumé général ; pour une visite de lieu, une liste des matériaux visibles ; ou encore une description d’un moment précis de l’enregistrement. Plutôt que de demander des résultats très différents dans une seule requête, précisez l’objectif principal et le format de la réponse. Vous pouvez également demander au modèle de ne rapporter que ce qui est visible dans l’enregistrement, afin d’éviter qu’il ne complète avec des informations absentes de la vidéo.

Par exemple, le prompt suivant permet d’obtenir un résumé structuré et succinct d’une vidéo d’intérieur :

Analyze this interior architecture video. Summarize the visible spaces, circulation, lighting, and materials. Use only details that can be observed in the video, and organize the response by topic.

Ce prompt organise par thèmes les espaces, la circulation, l’éclairage et les matériaux visibles dans la vidéo. Il demande de s’en tenir aux éléments observables, plutôt que de donner le nom exact d’un matériau qui ne peut pas être distingué à l’image.

2. Choisissez un mode de transfert adapté au fichier

Privilégiez Files API si la vidéo est volumineuse ou longue, ou si vous comptez la réutiliser dans des prompts ultérieurs. L’importation en ligne peut convenir à un fichier court, à condition que la taille totale de la requête reste inférieure à 20 MB. Pour une vidéo YouTube publique, envisagez l’option URL. Vérifiez la taille du fichier et les conditions d’utilisation avant l’envoi ; la source présente séparément les capacités selon l’utilisation gratuite ou payante.

3. Importez la vidéo avec Files API et attendez son traitement

L’exemple officiel en Python importe le fichier avec client.files.upload et vérifie son état jusqu’à ce qu’il passe à ACTIVE. Le fait que le fichier soit importé ne signifie pas qu’il est immédiatement prêt pour l’analyse : attendez la fin du traitement. Dans l’exemple ci-dessous, l’état est vérifié toutes les cinq secondes. Ce code est fondé sur l’exemple librement sous licence de la source :

from google import genai
import time

client = genai.Client()
myfile = client.files.upload(file="path/to/sample.mp4")

while not myfile.state or myfile.state.name != "ACTIVE":
    print("Processing video...")
    time.sleep(5)
    myfile = client.files.get(name=myfile.name)

Remplacez path/to/sample.mp4 par le chemin du fichier à analyser. L’exemple de la source montre comment utiliser la référence du fichier comme entrée vidéo une fois celle-ci prête. Si le traitement échoue, ne considérez pas le fichier comme prêt ; vérifiez que son état évolue.

4. Envoyez la vidéo et le prompt avec Interactions API

Lorsque le fichier atteint l’état ACTIVE, ajoutez l’URI de la vidéo et le prompt textuel aux entrées de la même interaction. L’exemple de la source utilise le nom de modèle gemini-3.8-flash. Le prompt ci-dessous vise à examiner l’enchaînement spatial et les transitions dans une vidéo de présentation :

Review this architectural walkthrough in chronological order. Describe how the spaces connect, identify visible transitions, and refer to relevant moments with timestamps when possible. Do not infer dimensions or design intent that the video does not show.

Demander des horodatages aide à relier les observations à des passages précis de l’enregistrement. Indiquer explicitement au modèle de ne pas déduire des dimensions ou une intention de conception que la vidéo ne permet pas de vérifier contribue à maintenir la réponse dans les limites de l’analyse visuelle.

5. Affinez le résultat selon les besoins du projet

Si la première réponse reste trop générale, orientez la question de suivi vers un sujet précis au lieu de reformuler la description de la vidéo. Le guide vidéo de Gemini décrit l’édition conversationnelle en plusieurs tours dans le contexte de la génération vidéo ; la documentation sur la compréhension vidéo mentionne, elle, la possibilité de poser des questions sur des vidéos et de faire référence à des horodatages. Dans ce scénario d’analyse, précisez le passage à examiner ou le type d’observation recherché.

From the video, list only the visible changes in lighting and material appearance between the main spaces. For each observation, include a timestamp when available and mark anything uncertain as unclear.

Ce prompt limite la réponse aux changements d’éclairage et d’apparence des matériaux. Demander de signaler les éléments « incertains » aide à éviter de présenter comme certains des détails qui sont difficiles à voir en raison d’une faible qualité d’image ou parce qu’ils se trouvent hors champ.

Erreurs fréquentes

• Envoyer une vidéo volumineuse en ligne : les instructions détaillées de la source réservent l’importation en ligne aux vidéos courtes dont la requête totale est inférieure à 20 MB. Pour les fichiers volumineux, envisagez Files API.

• Demander une analyse avant le traitement du fichier : après l’importation, vérifiez que l’état est ACTIVE ; l’exemple interroge régulièrement l’état du fichier.

• Rédiger un prompt trop large ou vague : au lieu d’une demande générale comme « analyse la vidéo », concentrez-vous sur un objectif unique : un résumé, les transitions spatiales ou les matériaux visibles, par exemple.

• Attendre des informations absentes de l’image : la compréhension vidéo sert à examiner les informations visuelles du contenu ; elle ne doit pas être considérée comme une source de vérification des dimensions du projet ou des décisions de conception qui ne figurent pas dans l’enregistrement.

• Confondre le guide sur la génération vidéo avec celui sur l’analyse : pour comprendre une vidéo existante, suivez la documentation sur la compréhension vidéo. Google indique que Veo 3.1 Preview a été arrêté dans l’API Gemini le 22 octobre 2026 et recommande de passer à Gemini Omni Flash pour la génération vidéo ; ce changement ne remplace pas les étapes d’analyse.

Utilisation dans les flux de travail d’architecture, d’architecture d’intérieur et d’archviz

Les équipes d’architecture et d’architecture d’intérieur peuvent essayer cette méthode pour établir un premier résumé des observations tirées d’une visite de projet ou d’un enregistrement de lieu, retrouver des passages importants grâce aux horodatages et répondre à des questions sur l’enregistrement. Les équipes d’archviz peuvent également examiner un flux de questions-réponses portant sur le contenu d’une vidéo de présentation existante. Toutefois, les résultats doivent rester limités à ce que montre la vidéo ; les dimensions, la conformité technique ou l’applicabilité au projet, qui ne peuvent pas être vérifiées à partir de l’enregistrement, doivent faire l’objet d’un contrôle distinct.

Les limites de Files API étant différentes pour les offres gratuites et payantes, les équipes devraient vérifier la taille du fichier du projet et leurs conditions d’accès avant de l’envoyer. La source ne précise ni les exigences matérielles, ni les détails tarifaires, ni l’intégration à des logiciels locaux ; ne partez donc pas du principe que ce flux de travail est relié aux outils de modélisation ou de rendu déjà utilisés.

Étapes suivantes

Commencez par tester un prompt de résumé sur une courte vidéo de projet dont l’utilisation est autorisée, puis ajoutez des questions de suivi portant sur des horodatages ou des types d’observations précis. Si le fichier est volumineux ou destiné à être réutilisé, envisagez Files API. Avant de reprendre les résultats dans les notes du projet, ouvrez la vidéo aux horodatages concernés et vérifiez les observations du modèle. Pour connaître les détails d’implémentation liés à l’importation des fichiers ou au choix du modèle, consultez la documentation officielle de l’API Gemini sur la compréhension et la génération vidéo.

Sources et licence

Ce guide a été adapté en turc à partir des informations contenues dans la documentation de Google sur la compréhension vidéo et la génération vidéo avec l’API Gemini. Les deux sources sont sous licence CC BY 4.0. L’exemple de code Python provient de la documentation sur la compréhension vidéo, publiée sous licence libre.