Compréhension des vidéos

Pour en savoir plus sur la génération de vidéos, consultez le guide Gemini Omni Flash.

Les modèles Gemini peuvent traiter des vidéos, ce qui permet de nombreux cas d'utilisation pour les développeurs de pointe qui nécessitaient auparavant des modèles spécifiques à un domaine. Parmi les fonctionnalités de vision de Gemini, citons la possibilité de décrire, de segmenter et d'extraire des informations à partir de vidéos, de répondre à des questions sur le contenu vidéo et de faire référence à des codes temporels spécifiques dans une vidéo.

Vous pouvez fournir des vidéos en entrée à Gemini de différentes manières :

Mode de saisie Taille maximale Cas d'utilisation recommandé
API Files 20 Go (payant) / 2 Go (sans frais) Fichiers volumineux (plus de 100 Mo), vidéos longues (plus de 10 minutes), fichiers réutilisables.
Enregistrement Cloud Storage 2 Go (par fichier, sans limites de stockage) Fichiers volumineux (plus de 100 Mo), vidéos longues (plus de 10 minutes), fichiers persistants et réutilisables.
Données intégrées Moins de 100 Mo Petits fichiers (moins de 100 Mo), courte durée (moins d'une minute), entrées ponctuelles.
URL YouTube N/A Vidéos YouTube publiques.

Remarque : L'API Files est recommandée pour la plupart des cas d'utilisation, en particulier pour les fichiers de plus de 100 Mo ou lorsque vous souhaitez réutiliser le fichier dans plusieurs requêtes.

Pour en savoir plus sur les autres méthodes de saisie de fichiers, par exemple à l'aide d'URL externes ou de fichiers stockés dans Google Cloud, consultez le guide Méthodes de saisie de fichiers.

Importer un fichier vidéo

Le code suivant télécharge un échantillon vidéo, l'importe à l'aide de l'API Files, attend qu'elle soit traitée, puis utilise la référence du fichier importé pour résumer la vidéo.

Python

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)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "video", "uri": myfile.uri, "mime_type": myfile.mime_type},
        {"type": "text", "text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}
    ]
)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/sample.mp4",
    config: { mimeType: "video/mp4" },
  });

  let getFile = await ai.files.get({ name: myfile.name });
  while (getFile.state === 'PROCESSING') {
      getFile = await ai.files.get({ name: myfile.name });
      console.log(`current file status: ${getFile.state}`);
      console.log('File is still processing, retrying in 5 seconds');

      await new Promise((resolve) => {
          setTimeout(resolve, 5000);
      });
  }
  if (getFile.state === 'FAILED') {
      throw new Error('File processing failed.');
  }

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "video", uri: myfile.uri, mime_type: myfile.mimeType },
      { type: "text", text: "Summarize this video. Then create a quiz with an answer key based on the information in this video." }
    ],
  });
  console.log(interaction.output_text);
}

await main();

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import com.google.genai.types.File;
import com.google.genai.types.FileState;
import com.google.genai.types.UploadFileConfig;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

File myfile =
    client.files.upload(
        "path/to/sample.mp4", UploadFileConfig.builder().mimeType("video/mp4").build());

while (!myfile.state().isPresent()
    || myfile.state().get().knownEnum() != FileState.Known.ACTIVE) {
  System.out.println("Processing video...");
  Thread.sleep(5000);
  myfile = client.files.get(myfile.name().get(), null);
}

Content videoContent =
    VideoContent.builder()
        .uri(myfile.uri().get())
        .mimeType(VideoContentMimeType.of(myfile.mimeType().get()))
        .build();
Content textContent =
    TextContent.builder()
        .text(
            "Summarize this video. Then create a quiz with an answer key based on the information in this video.")
        .build();

List<Content> contents = Arrays.asList(videoContent, textContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    myfile, err := client.Files.UploadFromPath(ctx, "path/to/sample.mp4", &genai.UploadFileConfig{
        MIMEType: "video/mp4",
    })
    if err != nil {
        log.Fatal(err)
    }

    for myfile.State != genai.FileStateActive {
        fmt.Println("Processing video...")
        time.Sleep(5 * time.Second)
        myfile, err = client.Files.Get(ctx, myfile.Name, nil)
        if err != nil {
            log.Fatal(err)
        }
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.VideoContent{
            URI:      genai.Ptr(myfile.URI),
            MimeType: interactions.VideoContentMimeType(myfile.MIMEType).ToPointer(),
        }),
        interactions.NewContent(interactions.TextContent{
            Text: "Summarize this video. Then create a quiz with an answer key based on the information in this video.",
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

VIDEO_PATH="path/to/sample.mp4"
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO

tmp_header_file=upload-header.tmp

echo "Starting file upload..."
curl "https://generativelanguage.googleapis.com/upload/v1beta/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -D ${tmp_header_file} \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

echo "Uploading video data..."
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${VIDEO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq -r ".file.uri" file_info.json)
file_name=$(jq -r ".file.name" file_info.json)
echo file_uri=$file_uri

echo "File uploaded successfully. File URI: ${file_uri}"

# Polling loop
echo "Waiting for file to be processed..."
while true; do
  curl -s "https://generativelanguage.googleapis.com/v1beta/${file_name}" \
    -H "x-goog-api-key: $GEMINI_API_KEY" > file_status.json
  state=$(jq -r ".state" file_status.json)
  echo "Current state: $state"
  if [ "$state" == "ACTIVE" ]; then
    break
  elif [ "$state" == "FAILED" ]; then
    echo "File processing failed."
    exit 1
  fi
  sleep 5
done

echo "Generating content from video..."
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "video", "uri": "'${file_uri}'", "mime_type": "'${MIME_TYPE}'"},
        {"type": "text", "text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}
      ]
    }' 2> /dev/null > response.json

jq ".steps[].content[0].text" response.json

Pour optimiser l'efficacité et les performances des jetons, envisagez d'utiliser le traitement vidéo agentif.

Utilisez toujours l'API Files lorsque la taille totale de la requête (y compris le fichier, le prompt textuel, les instructions système, etc.) est supérieure à 20 Mo, que la durée de la vidéo est importante ou si vous prévoyez d'utiliser la même vidéo dans plusieurs invites. L'API Files accepte directement les formats de fichiers vidéo.

Pour en savoir plus sur l'utilisation des fichiers multimédias, consultez API Files.

Transmettre des données vidéo de manière intégrée

Au lieu d'importer un fichier vidéo à l'aide de l'API Files, vous pouvez transmettre des vidéos plus petites directement dans la requête. Cette méthode convient aux vidéos plus courtes dont la taille totale de la requête est inférieure à 20 Mo.

Voici un exemple de fourniture de données vidéo intégrées :

Python

from google import genai
import base64

video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "data": base64.b64encode(video_bytes).decode('utf-8'),
            "mime_type": "video/mp4"
        }
    ]
)
print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});
const base64VideoFile = fs.readFileSync("path/to/small-sample.mp4", {
  encoding: "base64",
});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      data: base64VideoFile,
      mime_type: "video/mp4",
    }
  ],
});
console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;

String videoFileName = "/path/to/your/video.mp4";
byte[] videoBytes = Files.readAllBytes(Paths.get(videoFileName));
String base64Video = Base64.getEncoder().encodeToString(videoBytes);

Client client = new Client();

Content textContent =
    TextContent.builder().text("Please summarize the video in 3 sentences.").build();
Content videoContent =
    VideoContent.builder()
        .data(base64Video)
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "encoding/base64"
    "fmt"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    videoFileName := "/path/to/your/video.mp4"
    videoBytes, err := os.ReadFile(videoFileName)
    if err != nil {
        log.Fatal(err)
    }
    base64Video := base64.StdEncoding.EncodeToString(videoBytes)

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Please summarize the video in 3 sentences.",
        }),
        interactions.NewContent(interactions.VideoContent{
            Data:     genai.Ptr(base64Video),
            MimeType: interactions.VideoContentMimeTypeVideoMp4.ToPointer(),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

VIDEO_PATH=/path/to/your/video.mp4

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
          "type": "video",
          "data": "'$(base64 $B64FLAGS $VIDEO_PATH)'",
          "mime_type": "video/mp4"
        }
      ]
    }' 2> /dev/null

Transmettre des URL YouTube

Vous pouvez transmettre des URL YouTube directement à l'API Gemini dans le cadre de votre requête comme suit :

Python

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
    ]
)
print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      uri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    }
  ],
});
console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent =
    TextContent.builder().text("Please summarize the video in 3 sentences.").build();
Content videoContent =
    VideoContent.builder()
        .uri("https://www.youtube.com/watch?v=9hE5-98ZeCg")
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    contents := []interactions.Content{
        interactions.NewContent(interactions.TextContent{
            Text: "Please summarize the video in 3 sentences.",
        }),
        interactions.NewContent(interactions.VideoContent{
            URI: genai.Ptr("https://www.youtube.com/watch?v=9hE5-98ZeCg"),
        }),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(contents),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
          "type": "video",
          "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
      ]
    }' 2> /dev/null

Limites :

  • Pour le niveau sans frais, vous ne pouvez pas importer plus de huit heures de vidéo YouTube par jour.
  • Pour le niveau payant, il n'y a pas de limite en fonction de la durée de la vidéo.
  • Pour les modèles antérieurs à Gemini 2.5, vous ne pouvez importer qu'une seule vidéo par requête. Pour Gemini 2.5 et les modèles ultérieurs, vous pouvez importer jusqu'à 10 vidéos par requête.
  • Vous ne pouvez importer que des vidéos publiques (et non des vidéos privées ou non répertoriées).

Compréhension agentique des vidéos

Par défaut, les entrées vidéo utilisent le traitement statique (extraction d'images à 1 FPS) sur tous les modèles, y compris Gemini 4. Les modèles Gemini 4 Argon, 3.8 Flash, 3.6 Flash et 3.5 Flash Lite sont également compatibles avec la compréhension agentique des vidéos, un mode d'activation dans lequel le modèle explore dynamiquement la chronologie de la vidéo , inspecte de manière sélective les transcriptions et ajuste de manière adaptative la fréquence d'images et la résolution à la volée en fonction de l'invite.

Mode Description Modèles compatibles
Statique (par défaut) Extrait des images à une fréquence fixe (1 FPS) et les place dans le contexte en une seule passe. Par défaut pour tous les modèles Gemini, y compris Gemini 4. Tous les modèles Gemini
Agentif Le modèle navigue dynamiquement dans la chronologie de la vidéo, en ne chargeant que le contenu dont il a besoin en fonction de l'invite. Jusqu'à 88% d'efficacité en plus en termes de jetons et une qualité supérieure d'environ 7% pour les contenus longs. Gemini 4 Argon, 3.8 Flash, 3.6 Flash, 3.5 Flash Lite

Choisir un mode de traitement

Sélectionnez le mode de traitement qui correspond à la durée de la vidéo et au type de requête :

  • Statique (par défaut) : idéal pour les clips courts (moins de 5 minutes), les résumés complets de vidéos où l'enregistrement complet est pertinent, les requêtes sensibles à la latence ou la précision au niveau de l'image sur l'ensemble du clip. Sur les vidéos courtes ou les invites larges qui nécessitent l'inspection de la majeure partie de la vidéo, le traitement statique évite les jetons de réflexion supplémentaires (total_thought_tokens) et les allers-retours d'appel d'outil (total_tool_use_tokens) entraînés par la navigation dans la chronologie.
  • Agentif : idéal pour les vidéos longues (plus de 5 à 10 minutes), la récupération d'informations spécifiques ou les requêtes ciblant des moments ou des sujets spécifiques. Le modèle inspecte d'abord les transcriptions et ne charge que les segments visuels pertinents à la demande, ce qui réduit l'utilisation de jetons d'entrée vidéo jusqu'à 88% sans remplir la fenêtre de contexte.

Remarque : Pour les vidéos longues ou les invites complexes où le traitement agentif prend plus de temps, utilisez le streaming (stream=True) ou l'exécution en arrière-plan (background=True). Cela maintient la connexion active, affiche les étapes de raisonnement intermédiaires et évite les délais d'expiration de connexion ou d'authentification.

Définir le mode de traitement

Pour utiliser la compréhension agentique des vidéos, définissez "processing": "agentic" sur la partie vidéo du tableau input.

Le traitement vidéo agentif peut prendre plus de temps sur les vidéos longues, car le modèle effectue plusieurs passes d'inspection pour naviguer dans la chronologie. Pour éviter de perdre la progression en cas de perte de connexion réseau, cet exemple utilise background=True pour exécuter la tâche de manière asynchrone sur le serveur. Vous pouvez également exécuter des requêtes de manière synchrone sans exécution en arrière-plan en omettant le paramètre background, ce qui fonctionne bien pour les vidéos plus courtes.

Pour en savoir plus sur l'interrogation, la récupération des résultats et la gestion des tâches en arrière-plan, consultez le guide sur l'exécution en arrière-plan.

Python

import time
from google import genai

client = genai.Client()

# Upload a long video
video_file = client.files.upload(file="path/to/lecture.mp4")

while video_file.state.name == "PROCESSING":
    time.sleep(2)
    video_file = client.files.get(name=video_file.name)

# Use agentic processing with background execution
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": "agentic"
        },
        {"type": "text", "text": "What are the three main arguments presented?"}
    ],
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(interaction.id)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

// Upload a long video
let videoFile = await ai.files.upload({
  file: "path/to/lecture.mp4",
  config: { mimeType: "video/mp4" }
});

while (videoFile.state === "PROCESSING") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  videoFile = await ai.files.get({ name: videoFile.name });
}

// Use agentic processing with background execution
let interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: "agentic"
    },
    { type: "text", text: "What are the three main arguments presented?" }
  ],
  background: true,
});

while (interaction.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await ai.interactions.get(interaction.id);
}

console.log(interaction.output_text);

REST

# 1. Start the interaction in the background
interaction=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {"type": "text", "text": "What are the three main arguments presented?"}
    ],
    "background": true
  }')

id=$(echo "$interaction" | jq -r '.id')

# 2. Poll until the interaction finishes
while [ "$(echo "$interaction" | jq -r '.status')" = "in_progress" ]; do
  sleep 5
  interaction=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$id" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
done

echo "$interaction" | jq '.'

Remarque : Pour vérifier que le traitement agentif a été utilisé, inspectez interaction.steps. La présence de processing_call et processing_result indique que le modèle a navigué dynamiquement dans la vidéo.

Étapes de réponse

Le traitement agentif ajoute deux nouveaux types d'étapes au tableau steps :

  • processing_call : le modèle a demandé un segment vidéo ou une transcription audio, identifié par id.
  • processing_result : résultat de ce chargement, lié par call_id.

Ces étapes apparaissent entrelacées avec les étapes thought (lorsque les résumés sont activés) et précèdent l'étape finale model_output. Elles peuvent être utilisées pour afficher une trace de progression dans votre interface utilisateur, mais ne nécessitent pas de réponse.

L'exemple suivant montre la charge utile de la réponse avec des étapes de traitement entrelacées :

{
  "steps": [
    {
      "type": "thought",
      "signature": "sig_thought_1",
      "summary": [
        {
          "type": "text",
          "text": "Inspecting transcript for key discussion topics..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_01",
      "signature": "sig_call_01"
    },
    {
      "type": "processing_result",
      "call_id": "call_01",
      "signature": "sig_result_01"
    },
    {
      "type": "thought",
      "signature": "sig_thought_2",
      "summary": [
        {
          "type": "text",
          "text": "Loading visual frames to verify slide content..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_02",
      "signature": "sig_call_02"
    },
    {
      "type": "processing_result",
      "call_id": "call_02",
      "signature": "sig_result_02"
    },
    {
      "type": "thought",
      "signature": "sig_thought_3",
      "summary": [
        {
          "type": "text",
          "text": "Synthesizing answer from gathered evidence..."
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The three main arguments presented in the lecture are..."
        }
      ]
    }
  ]
}

Mixer les modes de traitement entre les vidéos

Définissez différents modes de traitement pour chaque vidéo dans la même requête :

Python

import time
from google import genai

client = genai.Client()

lecture = client.files.upload(file="path/to/long-lecture.mp4")
experiment = client.files.upload(file="path/to/short-experiment.mp4")

# Use agentic processing with background execution
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": lecture.uri,
            "mime_type": lecture.mime_type,
            "processing": "agentic"  # Use agentic video understanding
        },
        {
            "type": "video",
            "uri": experiment.uri,
            "mime_type": experiment.mime_type,
            "processing": "static"  # Use static processing
        },
        {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ],
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(interaction.id)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const lecture = await ai.files.upload({
  file: "path/to/long-lecture.mp4",
  config: { mimeType: "video/mp4" }
});
const experiment = await ai.files.upload({
  file: "path/to/short-experiment.mp4",
  config: { mimeType: "video/mp4" }
});

// Use agentic processing with background execution
let interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: lecture.uri,
      mime_type: lecture.mimeType,
      processing: "agentic" // Use agentic video understanding
    },
    {
      type: "video",
      uri: experiment.uri,
      mime_type: experiment.mimeType,
      processing: "static" // Use static processing
    },
    { type: "text", text: "Compare the lecture content with the experiment results." }
  ],
  background: true,
});

while (interaction.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  interaction = await ai.interactions.get(interaction.id);
}

console.log(interaction.output_text);

REST

# 1. Start the interaction in the background
interaction=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${lecture_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {
        "type": "video",
        "uri": "'${experiment_uri}'",
        "mime_type": "video/mp4",
        "processing": "static"
      },
      {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ],
    "background": true
  }')

id=$(echo "$interaction" | jq -r '.id')

# 2. Poll until the interaction finishes
while [ "$(echo "$interaction" | jq -r '.status')" = "in_progress" ]; do
  sleep 5
  interaction=$(curl -s "https://generativelanguage.googleapis.com/v1beta/interactions/$id" \
    -H "x-goog-api-key: $GEMINI_API_KEY")
done

echo "$interaction" | jq '.'

Conversations vidéo multitours

Le contexte vidéo est conservé entre les tours d'une conversation. Lorsque vous utilisez le traitement agentif :

  • Mode avec état (à l'aide de previous_interaction_id) : le serveur conserve le contexte vidéo. Aucune gestion supplémentaire n'est nécessaire.
  • Mode sans état (à l'aide de step_list) : en mode sans état, la réponse inclut les étapes processing_call et processing_result qui encodent le contexte vidéo. Vous devez inclure toutes les étapes de la réponse dans la step_list de votre prochaine requête pour conserver le contexte vidéo. Bien que leur omission ne renvoie pas d'erreur d'API pour le moment, le contexte vidéo est perdu, ce qui réduit considérablement la qualité de la réponse aux questions de suivi. Notez que les étapes renvoyées envoyées dans les requêtes suivantes contribuent au nombre de jetons d'entrée.

Faire référence à des codes temporels dans le contenu

Vous pouvez poser des questions sur des moments spécifiques de la vidéo à l'aide de codes temporels au format MM:SS.

Python

prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?"

JavaScript

const prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?";

Java

String prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?";

Go

prompt := "What are the examples given at 00:05 and 00:10 supposed to show us?"

REST

PROMPT="What are the examples given at 00:05 and 00:10 supposed to show us?"

Extraire des insights détaillés à partir de vidéos

Les modèles Gemini offrent de puissantes fonctionnalités de compréhension du contenu vidéo en traitant les informations des flux audio et visuels. Cela vous permet d'extraire un ensemble riche de détails, y compris de générer des descriptions de ce qui se passe dans une vidéo et de répondre à des questions sur son contenu.

Pour les descriptions visuelles, le modèle échantillonne la vidéo à une fréquence de 1 image par seconde (FPS). Cette fréquence d'échantillonnage par défaut fonctionne bien pour la plupart des contenus, mais notez qu'elle peut manquer des détails dans les vidéos avec des mouvements rapides ou des changements de scène rapides.

Python

prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

JavaScript

const prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.";

Java

String prompt =
    "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.";

Go

prompt := "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

REST

PROMPT="Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

Personnaliser le traitement vidéo

Vous pouvez personnaliser le traitement vidéo dans l'API Gemini en définissant des intervalles de découpage ou en fournissant un échantillonnage personnalisé de la fréquence d'images. Ces options de personnalisation ne sont compatibles que lors du traitement de la vidéo en mode "static".

Définir des intervalles de découpage

Vous pouvez découper une vidéo en spécifiant start_offset et end_offset dans l'objet de configuration processing.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "start_offset": 1200,
                "end_offset": 1500,
            },
        },
        {"type": "text", "text": "Summarize this section of the video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        start_offset: 1200,
        end_offset: 1500,
      },
    },
    { type: "text", text: "Summarize this section of the video." },
  ],
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "start_offset": 1200,
          "end_offset": 1500
        }
      },
      {"type": "text", "text": "Summarize this section of the video."}
    ]
  }' 2> /dev/null

Définir une fréquence d'images personnalisée

Vous pouvez définir un échantillonnage personnalisé de la fréquence d'images en transmettant un argument fps dans l'objet de configuration processing.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "fps": 0.5,  # Sample 1 frame every 2 seconds
            },
        },
        {"type": "text", "text": "Describe the scene changes in this video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        fps: 0.5, // Sample 1 frame every 2 seconds
      },
    },
    { type: "text", text: "Describe the scene changes in this video." },
  ],
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "fps": 0.5
        }
      },
      {"type": "text", "text": "Describe the scene changes in this video."}
    ]
  }' 2> /dev/null

Formats vidéo acceptés

Gemini est compatible avec les types MIME de format vidéo suivants :

  • video/mp4
  • video/mpeg
  • video/mov
  • video/avi
  • video/x-flv
  • video/mpg
  • video/webm
  • video/wmv
  • video/3gpp

Détails techniques sur les vidéos

  • Modèles et contexte compatibles : tous les modèles Gemini peuvent traiter des données vidéo.
    • Les modèles avec une fenêtre de contexte de 1 million peuvent traiter des vidéos d'une durée maximale de trois heures par défaut (à basse résolution multimédia) ou d'une durée maximale d'une heure à haute résolution multimédia.
  • Modes de traitement : les modèles Gemini 4 Argon, 3.8 Flash, 3.6 Flash, 3.5 Flash Lite, et versions ultérieures sont compatibles avec deux modes de traitement vidéo :
    • Statique : les images sont extraites à 1 FPS et placées dans le contexte (par défaut pour tous les modèles). L'audio est traité à 1 Kbit/s (canal unique). Des codes temporels sont ajoutés toutes les secondes. Idéal pour les clips courts ou lorsque chaque image est importante (par exemple, pour une inspection image par image). Notez que les séquences d'action rapides peuvent perdre des détails en raison du taux d'échantillonnage de 1 FPS.
    • Agentif : le modèle navigue dynamiquement dans la vidéo, en chargeant la transcription et/ou les images et/ou l'audio à la demande. Cela utilise jusqu'à 88 % de jetons en moins pour les contenus longs, bien que la navigation puisse augmenter le délai avant le premier jeton (TTFT) et l'utilisation totale de jetons sur les clips courts (moins de 5 minutes) ou les requêtes larges en raison du raisonnement interne et des allers-retours d'outil. Idéal pour les vidéos longues et les requêtes ciblées afin d'optimiser les coûts des jetons et la qualité des réponses. Compatible avec Gemini 4 Argon, 3.8 Flash, 3.6 Flash et 3.5 Flash Lite. Pour en savoir plus, consultez la section Compréhension agentique des vidéos.
  • Calcul des jetons (mode statique) : chaque seconde de vidéo est tokenisée comme suit :
    • Images individuelles (échantillonnées à 1 FPS) :
      • Si media_resolution est défini sur "low", les images sont tokenisées à 66 jetons par image.
      • Sinon, les images sont tokenisées à 258 jetons par image.
    • Audio : 32 jetons par seconde.
    • Les métadonnées sont également incluses.
    • Total : environ 100 jetons par seconde de vidéo à la résolution multimédia par défaut (basse) ou environ 300 jetons par seconde de vidéo à haute résolution multimédia.
  • Calcul des jetons (mode agentif) : l'utilisation des jetons varie en fonction de la complexité du contenu et de la stratégie de navigation du modèle. Les jetons de raisonnement de navigation générés lors de l'exploration vidéo sont comptabilisés comme des jetons de réflexion (total_thought_tokens), tandis que les images, l'audio et la transcription chargés à la demande sont comptabilisés comme des jetons d'utilisation d'outil (total_tool_use_tokens). Le traitement agentif utilise généralement jusqu'à 88% de jetons en moins que le traitement statique pour les contenus longs, car le modèle ne charge que la transcription et/ou les images et/ou l'audio dont il a besoin pour répondre à l'invite (consultez le guide sur les jetons).
  • Résolution multimédia : Gemini 3 introduit un contrôle précis sur le traitement de la vision multimodale avec le paramètre media_resolution. Le paramètre media_resolution détermine le nombre maximal de jetons alloués par image d'entrée ou image vidéo. Des résolutions plus élevées améliorent la capacité du modèle à lire du texte fin ou à identifier de petits détails, mais augmentent l'utilisation des jetons et la latence. Les paramètres media_resolution et processing sont indépendants : vous pouvez les définir tous les deux sur la même entrée vidéo.

Pour en savoir plus sur les calculs de jetons, consultez le guide sur les jetons.

  • Format du code temporel : lorsque vous faites référence à des moments spécifiques d'une vidéo dans votre invite, utilisez le format MM:SS (par exemple, 01:15 pour 1 minute et 15 secondes).
  • Placement du prompt : si vous combinez du texte et une seule vidéo, placez le prompt textuel après la partie vidéo du tableau input.
  • Délais d'expiration pour les requêtes longues : pour les vidéos qui nécessitent un temps de traitement prolongé ou un raisonnement en plusieurs étapes complexe, utilisez le streaming (stream=True) ou l'exécution en arrière-plan (background=True). Les requêtes synchrones non diffusées en continu qui subissent des nouvelles tentatives de backend en cas de forte demande peuvent dépasser les fenêtres de validité des jetons de connexion ou d'authentification, ce qui peut se traduire par des erreurs 401 Unauthorized ou de délai d'expiration inattendues. Le streaming maintient la connexion active et affiche la progression du raisonnement intermédiaire et de l'appel d'outil.

Étape suivante

  • Résolution multimédia : contrôlez la résolution des images vidéo pour équilibrer la qualité et l'utilisation des jetons.
  • Jetons : découvrez comment le contenu vidéo est tokenisé en mode de traitement statique et agentif.
  • Exécution en arrière-plan : exécutez de manière asynchrone les tâches de compréhension vidéo de longue durée pour éviter les délais d'expiration de connexion.
  • Instructions système : les instructions système vous permettent d'orienter le comportement du modèle en fonction de vos besoins et de vos cas d'utilisation spécifiques.
  • API Files : découvrez comment importer et gérer des fichiers à utiliser avec Gemini.
  • Stratégies de prompting de fichiers : l'API Gemini est compatible avec le prompting contenant des données textuelles, d'image, audio et vidéo, également appelé prompting multimodal.
  • Conseils de sécurité : les modèles d'IA générative produisent parfois des résultats inattendus, tels que des résultats inexacts, biaisés ou choquants. Le post-traitement et l'évaluation humaine sont essentiels pour limiter le risque de préjudice lié à ces résultats.