Comprensione dei video

Per scoprire di più sulla generazione di video, consulta la guida Gemini Omni Flash.

I modelli Gemini possono elaborare video, consentendo molti casi d'uso per gli sviluppatori all'avanguardia che in passato avrebbero richiesto modelli specifici per il dominio. Alcune delle funzionalità di visione di Gemini includono la possibilità di descrivere, segmentare ed estrarre informazioni dai video, rispondere a domande sui contenuti video e fare riferimento a timestamp specifici all'interno di un video.

Puoi fornire video come input a Gemini nei seguenti modi:

Metodo inserimento Dimensione massima Caso d'uso consigliato
API File 20 GB (a pagamento) / 2 GB (senza costi) File di grandi dimensioni (oltre 100 MB), video lunghi (oltre 10 minuti), file riutilizzabili.
Registrazione di Cloud Storage 2 GB (per file, senza limiti di spazio di archiviazione) File di grandi dimensioni (oltre 100 MB), video lunghi (oltre 10 minuti), file persistenti e riutilizzabili.
Dati in linea < 100MB File piccoli (< 100 MB), di breve durata (< 1 minuto), input una tantum.
URL di YouTube N/D Video di YouTube pubblici.

Nota:l'API File è consigliata per la maggior parte dei casi d'uso, in particolare per i file di dimensioni superiori a 100 MB o quando vuoi riutilizzare il file in più richieste.

Per scoprire altri metodi di input dei file, ad esempio l'utilizzo di URL esterni o file archiviati in Google Cloud, consulta la guida Metodi di input dei file.

Caricare un file video

Il seguente codice scarica un video di esempio, lo carica utilizzando l'API Files, attende l'elaborazione e poi utilizza il riferimento al file caricato per riassumere il video.

Python

from google import genai

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-3.8-flash", contents=[myfile, "Summarize this video. Then create a quiz with an answer key based on the information in this video."]
)

print(response.text)

JavaScript

import {
  GoogleGenAI,
  createUserContent,
  createPartFromUri,
} 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" },
  });

  const response = await ai.models.generateContent({
    model: "gemini-3.8-flash",
    contents: createUserContent([
      createPartFromUri(myfile.uri, myfile.mimeType),
      "Summarize this video. Then create a quiz with an answer key based on the information in this video.",
    ]),
  });
  console.log(response.text);
}

await main();

Go

uploadedFile, _ := client.Files.UploadFromPath(ctx, "path/to/sample.mp4", nil)

parts := []*genai.Part{
    genai.NewPartFromText("Summarize this video. Then create a quiz with an answer key based on the information in this video."),
    genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
}

contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}

result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    contents,
    nil,
)

fmt.Println(result.Text())

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)
echo file_uri=$file_uri

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

# --- 3. Generate content using the uploaded video file ---
echo "Generating content from video..."
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data":{"mime_type": "'"${MIME_TYPE}"'", "file_uri": "'"${file_uri}"'"}},
          {"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 -r ".candidates[].content.parts[].text" response.json

Per ottimizzare l'efficienza e il rendimento dei token, valuta la possibilità di utilizzare l'elaborazione di video con agenti.

Utilizza sempre l'API Files quando le dimensioni totali della richiesta (inclusi il file, il prompt di testo, le istruzioni di sistema e così via) superano i 20 MB, la durata del video è significativa o se intendi utilizzare lo stesso video in più prompt. L'API File accetta direttamente i formati dei file video.

Per saperne di più su come lavorare con i file multimediali, consulta l'API Files.

Trasmettere i dati video in linea

Anziché caricare un file video utilizzando l'API File, puoi trasmettere video più piccoli direttamente nella richiesta a generateContent. Questa opzione è adatta ai video più brevi con dimensioni totali della richiesta inferiori a 20 MB.

Ecco un esempio di fornitura di dati video in linea:

Python

from google import genai
from google.genai import types

# Only for videos of size <20Mb
video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(data=video_bytes, mime_type='video/mp4')
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)
print(response.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 contents = [
  {
    inlineData: {
      mimeType: "video/mp4",
      data: base64VideoFile,
    },
  },
  { text: "Please summarize the video in 3 sentences." }
];

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: contents,
});
console.log(response.text);

REST

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

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

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

Trasmettere gli URL di YouTube

Puoi trasmettere gli URL di YouTube direttamente all'API Gemini nell'ambito della tua richiesta nel seguente modo:

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri='https://www.youtube.com/watch?v=9hE5-98ZeCg')
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)
print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

const contents = [
  {
    fileData: {
      fileUri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    },
  },
  { text: "Please summarize the video in 3 sentences." }
];

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: contents,
});
console.log(response.text);

Go

package main

import (
  "context"
  "fmt"
  "os"
  "google.golang.org/genai"
)

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

  parts := []*genai.Part{
      genai.NewPartFromText("Please summarize the video in 3 sentences."),
      genai.NewPartFromURI("https://www.youtube.com/watch?v=9hE5-98ZeCg","video/mp4"),
  }

  contents := []*genai.Content{
      genai.NewContentFromParts(parts, genai.RoleUser),
  }

  result, _ := client.Models.GenerateContent(
      ctx,
      "gemini-3.8-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

REST

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

Limitazioni:

  • Per il livello senza costi, non puoi caricare più di 8 ore di video di YouTube al giorno.
  • Per il livello a pagamento, non esiste alcun limite in base alla durata del video.
  • Per i modelli precedenti a Gemini 2.5, puoi caricare un solo video per richiesta. Per Gemini 2.5 e modelli successivi, puoi caricare un massimo di 10 video per richiesta.
  • Puoi caricare solo video pubblici (non privati o non in elenco).

Comprensione dei video agentica

Per impostazione predefinita, gli input video utilizzano l'elaborazione statica (estrazione di frame a 1 FPS). I modelli Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash e 3.5 Flash Lite supportano anche la comprensione dei video agentici, in cui il modello esplora dinamicamente la sequenza temporale del video, ispezionando selettivamente le trascrizioni e regolando in modo adattivo la frequenza dei fotogrammi e la risoluzione al volo in base al prompt.

Modalità Descrizione Modelli supportati
Statica (impostazione predefinita) Estrae i fotogrammi a una velocità fissa (1 f/s) e li inserisce nel contesto in un'unica passata. Funziona bene per i clip brevi. Tutti i modelli Gemini
Agentic Il modello naviga dinamicamente nella sequenza temporale del video, caricando solo i contenuti necessari in base al prompt. Fino all'88% in più di efficienza dei token e una qualità superiore di circa il 7% per i contenuti nel formato lungo. Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite

Scegliere una modalità di elaborazione

Come linea guida generale, inizia con la modalità agente, soprattutto quando ottimizzi per la qualità della risposta o l'efficienza dei token.

  • Agentic:video nel formato lungo o query che hanno come target momenti specifici. Il modello naviga dinamicamente nella cronologia per individuare informazioni contestualmente pertinenti senza riempire la finestra contestuale.
  • Statica:query sensibili alla latenza su clip brevi (meno di 5 minuti) o casi in cui è necessaria una precisione a livello di frame sull'intero clip.

Nota:per video lunghi o prompt complessi in cui l'elaborazione agentica richiede più tempo, utilizza lo streaming (client.models.generate_content_stream). In questo modo la connessione rimane attiva, vengono visualizzati i passaggi di ragionamento intermedi ed evitati timeout di connessione o autenticazione.

Impostare la modalità di elaborazione

Python

import time
from google import genai
from google.genai import types

client = genai.Client()

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)

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Part.from_uri(
            file_uri=video_file.uri,
            mime_type=video_file.mime_type,
            media_processing="AGENTIC",
        ),
        "What are the three main arguments presented?",
    ],
)
print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

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 });
}

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: videoFile.uri,
            mimeType: videoFile.mimeType,
          },
          mediaProcessing: "AGENTIC",
        },
        { text: "What are the three main arguments presented?" },
      ],
    },
  ],
});
console.log(response.text);

Go

uploadedFile, _ := client.Files.UploadFromPath(ctx, "path/to/lecture.mp4", nil)
parts := []*genai.Part{
    {
        FileData: &genai.FileData{
            FileURI:  uploadedFile.URI,
            MIMEType: uploadedFile.MIMEType,
        },
        MediaProcessing: genai.MediaProcessingAgentic,
    },
    genai.NewPartFromText("What are the three main arguments presented?"),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    contents,
    nil,
)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "parts": [
        {
          "file_data": {
            "file_uri": "'${file_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing": "AGENTIC"
        },
        {"text": "What are the three main arguments presented?"}
      ]
    }]
  }'

Nota: per verificare che sia stata utilizzata l'elaborazione con agenti, esamina response.candidates[0].content.parts. La presenza di parti tool_call e tool_response con il tipo di strumento MEDIA_PROCESSING indica che il modello ha navigato dinamicamente nel video.

Nota:a differenza di altri strumenti lato server (come la Ricerca Google o il contesto URL), il video agentico non richiede l'impostazione di include_server_side_tool_invocations=True in ToolConfig per la restituzione o lo streaming delle chiamate di strumenti e dei risultati. Le parti tool_call e tool_response per la navigazione dei video vengono restituite automaticamente quando media_processing="AGENTIC" è impostato su qualsiasi parte dell'input.

Struttura della risposta

Quando l'elaborazione agentica è attivata, la risposta include parti aggiuntive che espongono la traccia di navigazione interna:

  • tool_call parti (tool_type: "MEDIA_PROCESSING"): emesse ogni volta che il modello richiede un segmento video o una trascrizione audio.
  • tool_response parti (tool_type: "MEDIA_PROCESSING"): il risultato di ogni operazione di caricamento.

Non è necessario gestire o rispondere manualmente a queste parti: restituisci la risposta completa come cronologia della conversazione e verranno gestite automaticamente.

Se include_thoughts=True è impostato in ThinkingConfig, i passaggi di ragionamento vengono visualizzati come parti thought: true intervallate alle coppie di chiamate/risposte dello strumento. Con i pensieri disattivati, il testo del pensiero viene omesso, ma le parti dello strumento sono ancora presenti.

L'esempio seguente mostra il payload della risposta con le parti della chiamata allo strumento e della risposta intercalate:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "thought": true,
            "text": "Inspecting transcript for key discussion topics..."
          },
          {
            "thought_signature": "sig_A",
            "tool_call": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought_signature": "sig_B",
            "tool_response": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought": true,
            "text": "Loading visual frames to verify slide content..."
          },
          {
            "thought_signature": "sig_C",
            "tool_call": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought_signature": "sig_D",
            "tool_response": {
              "tool_type": "MEDIA_PROCESSING"
            }
          },
          {
            "thought": true,
            "text": "Synthesizing answer from gathered evidence..."
          },
          {
            "text": "The three main arguments presented in the lecture are...",
            "thought_signature": "sig_E"
          }
        ]
      }
    }
  ]
}

Combinare le modalità di elaborazione tra i video

Puoi impostare diverse modalità di elaborazione per ogni parte del video nella stessa richiesta:

Python

from google import genai
from google.genai import types

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        types.Part.from_uri(
            file_uri=lecture.uri,
            mime_type=lecture.mime_type,
            media_processing="AGENTIC",  # Use agentic video understanding
        ),
        types.Part.from_uri(
            file_uri=experiment.uri,
            mime_type=experiment.mime_type,
            media_processing="STATIC",  # Use static processing
        ),
        "Compare the lecture content with the experiment results.",
    ],
)
print(response.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" },
});

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      role: "user",
      parts: [
        {
          fileData: {
            fileUri: lecture.uri,
            mimeType: lecture.mimeType,
          },
          mediaProcessing: "AGENTIC", // Use agentic video understanding
        },
        {
          fileData: {
            fileUri: experiment.uri,
            mimeType: experiment.mimeType,
          },
          mediaProcessing: "STATIC", // Use static processing
        },
        { text: "Compare the lecture content with the experiment results." },
      ],
    },
  ],
});
console.log(response.text);

Go

lecturePart := &genai.Part{
    FileData: &genai.FileData{
        FileURI:  lectureFile.URI,
        MIMEType: lectureFile.MIMEType,
    },
    MediaProcessing: genai.MediaProcessingAgentic, // Use agentic
}
experimentPart := &genai.Part{
    FileData: &genai.FileData{
        FileURI:  experimentFile.URI,
        MIMEType: experimentFile.MIMEType,
    },
    MediaProcessing: genai.MediaProcessingStatic, // Use static
}
parts := []*genai.Part{
    lecturePart,
    experimentPart,
    genai.NewPartFromText("Compare the lecture content with the experiment results."),
}
contents := []*genai.Content{
    genai.NewContentFromParts(parts, genai.RoleUser),
}
result, _ := client.Models.GenerateContent(ctx, "gemini-3.8-flash", contents, nil)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "parts": [
        {
          "file_data": {
            "file_uri": "'${lecture_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing": "AGENTIC"
        },
        {
          "file_data": {
            "file_uri": "'${experiment_uri}'",
            "mime_type": "video/mp4"
          },
          "media_processing": "STATIC"
        },
        {"text": "Compare the lecture content with the experiment results."}
      ]
    }]
  }'

Utilizzare la memorizzazione nella cache del contesto per i video lunghi

Per i video di durata superiore a 10 minuti o quando prevedi di effettuare più richieste sullo stesso file video, utilizza la memorizzazione nella cache del contesto per ridurre i costi e migliorare la latenza. La memorizzazione nella cache del contesto ti consente di elaborare il video una sola volta e riutilizzare i token per le query successive, il che la rende ideale per le sessioni di chat o per l'analisi ripetuta di contenuti nel formato lungo.

Fare riferimento ai timestamp nei contenuti

Puoi porre domande su momenti specifici del video utilizzando timestamp nel formato MM:SS.

Python

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        myfile,
        "What are the examples given at 00:05 and 00:10 supposed to show us?",
    ],
)
print(response.text)

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    myfile,
    "What are the examples given at 00:05 and 00:10 supposed to show us?",
  ],
});
console.log(response.text);

Go

parts := []*genai.Part{
    genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
    genai.NewPartFromText("What are the examples given at 00:05 and 00:10 supposed to show us?"),
}

result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    []*genai.Content{genai.NewContentFromParts(parts, genai.RoleUser)},
    nil,
)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data": {"file_uri": "'"${file_uri}"'", "mime_type": "'"${MIME_TYPE}"'"}},
          {"text": "What are the examples given at 00:05 and 00:10 supposed to show us?"}
        ]
      }]
    }' 2> /dev/null

Estrarre informazioni dettagliate dal video

I modelli Gemini offrono potenti funzionalità per la comprensione dei contenuti video elaborando le informazioni provenienti dai flussi audio e visivi. In questo modo puoi estrarre un ricco insieme di dettagli, tra cui generare descrizioni di ciò che accade in un video e rispondere a domande sui suoi contenuti.

Per le descrizioni visive, il modello esegue il campionamento del video a una velocità di 1 frame al secondo (f/s). Questa frequenza di campionamento predefinita funziona bene per la maggior parte dei contenuti, ma tieni presente che potrebbe non rilevare i dettagli nei video con movimenti rapidi o cambi di scena veloci. Per questi contenuti con movimenti rapidi, ti consigliamo di impostare una frequenza fotogrammi personalizzata.

Python

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        myfile,
        "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.",
    ],
)
print(response.text)

JavaScript

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    myfile,
    "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.",
  ],
});
console.log(response.text);

Go

parts := []*genai.Part{
    genai.NewPartFromURI(uploadedFile.URI, uploadedFile.MIMEType),
    genai.NewPartFromText("Describe the key events in this video, providing both audio and visual details. " +
        "Include timestamps for salient moments."),
}

result, _ := client.Models.GenerateContent(
    ctx,
    "gemini-3.8-flash",
    []*genai.Content{genai.NewContentFromParts(parts, genai.RoleUser)},
    nil,
)
fmt.Println(result.Text())

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
      "contents": [{
        "parts":[
          {"file_data": {"file_uri": "'"${file_uri}"'", "mime_type": "'"${MIME_TYPE}"'"}},
          {"text": "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."}
        ]
      }]
    }' 2> /dev/null

Personalizzare l'elaborazione video

Puoi personalizzare l'elaborazione video nell'API Gemini impostando intervalli di ritaglio o fornendo un campionamento della frequenza dei fotogrammi personalizzato. Queste opzioni di personalizzazione sono supportate solo durante l'elaborazione del video in modalità "static".

Impostare gli intervalli di ritaglio

Puoi tagliare il video specificando videoMetadata con offset di inizio e fine.

Python

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-3.8-flash',
    contents=types.Content(
        parts=[
            types.Part(
                file_data=types.FileData(file_uri='https://www.youtube.com/watch?v=XEzRZ35urlk'),
                video_metadata=types.VideoMetadata(
                    start_offset='1250s',
                    end_offset='1570s'
                )
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

JavaScript

import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({});
const model = 'gemini-3.8-flash';

async function main() {
const contents = [
  {
    role: 'user',
    parts: [
      {
        fileData: {
          fileUri: 'https://www.youtube.com/watch?v=9hE5-98ZeCg',
          mimeType: 'video/*',
        },
        videoMetadata: {
          startOffset: '40s',
          endOffset: '80s',
        }
      },
      {
        text: 'Please summarize the video in 3 sentences.',
      },
    ],
  },
];

const response = await ai.models.generateContent({
  model,
  contents,
});

console.log(response.text)

}

await main();

Impostare una frequenza fotogrammi personalizzata

Puoi impostare il campionamento della frequenza fotogrammi personalizzata passando un argomento fps a videoMetadata.

Python

from google import genai
from google.genai import types

# Only for videos of size <20Mb
video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
response = client.models.generate_content(
    model='models/gemini-3.8-flash',
    contents=types.Content(
        parts=[
            types.Part(
                inline_data=types.Blob(
                    data=video_bytes,
                    mime_type='video/mp4'),
                video_metadata=types.VideoMetadata(fps=5)
            ),
            types.Part(text='Please summarize the video in 3 sentences.')
        ]
    )
)

JavaScript

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

const ai = new GoogleGenAI({});

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

const response = await ai.models.generateContent({
  model: "gemini-3.8-flash",
  contents: [
    {
      fileData: {
        fileUri: myfile.uri,
        mimeType: myfile.mimeType,
      },
      videoMetadata: {
        fps: 5,
      },
    },
    "Please summarize the video in 3 sentences.",
  ],
});

console.log(response.text);

Per impostazione predefinita, viene campionato 1 frame al secondo (f/s) dal video. Potresti voler impostare un valore FPS basso (< 1) per i video lunghi. Questa funzionalità è particolarmente utile per i video per lo più statici (ad es. lezioni). Utilizza una frequenza fotogrammi più alta per i video che richiedono un'analisi temporale granulare, ad esempio per comprendere azioni rapide o per il rilevamento del movimento ad alta velocità.

Formati video supportati

Gemini supporta i seguenti tipi MIME di formati video:

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

Dettagli tecnici sui video

  • Modelli e contesto supportati: tutti i modelli Gemini possono elaborare i dati video.
    • I modelli con una finestra contestuale di 1 milione di token possono elaborare video della durata massima di 3 ore per impostazione predefinita (a bassa risoluzione multimediale) o della durata massima di 1 ora ad alta risoluzione multimediale.
  • Modalità di elaborazione: Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite e i modelli successivi supportano due modalità di elaborazione video:
    • Statico: i frame vengono estratti a 1 FPS e inseriti nel contesto (valore predefinito per tutti i modelli). L'audio viene elaborato a 1 Kbps (singolo canale). I timestamp vengono aggiunti ogni secondo. Ideale per clip brevi o quando ogni fotogramma è importante (ad esempio per l'ispezione fotogramma per fotogramma). Tieni presente che le sequenze di azioni rapide potrebbero perdere dettagli a causa della frequenza di campionamento di 1 FPS.
    • Agentic: il modello naviga dinamicamente nel video, caricando la trascrizione e/o i frame e/o l'audio su richiesta. In questo modo, vengono utilizzati fino all'88% in meno di token per i contenuti nel formato lungo, anche se la navigazione potrebbe aumentare leggermente il tempo al primo token (TTFT) nei clip brevi (< 5 minuti) a causa del ragionamento interno e dei round trip degli strumenti prima dell'inizio della generazione. Le risposte includono le parti di chiamata allo strumento e di risposta MEDIA_PROCESSING per preservare il contesto del ragionamento nei vari turni. Ideale per i video nel formato lungo per ottimizzare i costi dei token e la qualità delle risposte. Supportato su Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash e 3.5 Flash Lite. Per maggiori dettagli, consulta la sezione Comprensione dei video agentica.
  • Calcolo dei token (modalità statica): ogni secondo di video viene tokenizzato come segue:
    • Singoli fotogrammi (campionati a 1 FPS):
      • Se media_resolution è impostato su basso, i frame vengono tokenizzati a 66 token per frame.
      • In caso contrario, i frame vengono tokenizzati a 258 token per frame.
    • Audio: 32 token al secondo.
    • Sono inclusi anche i metadati.
    • Totale: circa 100 token al secondo di video con risoluzione multimediale predefinita (bassa) o circa 300 token al secondo di video con risoluzione multimediale elevata.
  • Calcolo dei token (modalità agente): l'utilizzo dei token varia in base alla complessità dei contenuti e alla strategia di navigazione del modello. I token di ragionamento della navigazione generati durante l'esplorazione dei video vengono conteggiati come token di pensiero (thoughts_token_count), mentre i frame, l'audio e la trascrizione caricati su richiesta vengono conteggiati come token di prompt dello strumento (tool_use_prompt_token_count). L'elaborazione con agenti in genere utilizza fino all'88% in meno di token totali rispetto all'elaborazione statica per i contenuti nel formato lungo, perché il modello carica solo la trascrizione e/o i frame e/o l'audio necessari per rispondere al prompt (consulta la guida ai token).
  • Risoluzione dei contenuti multimediali: Gemini 3 introduce un controllo granulare dell'elaborazione multimodale della visione con il parametro media_resolution. Il parametro media_resolution determina il numero massimo di token allocati per ogni immagine di input o frame video. Risoluzioni più elevate migliorano la capacità del modello di leggere testi piccoli o identificare piccoli dettagli, ma aumentano l'utilizzo dei token e la latenza. I parametri media_resolution e media_processing sono indipendenti: puoi impostarli entrambi nella stessa parte del video.

Per maggiori dettagli sui calcoli dei token, consulta la guida ai token.

  • Formato del timestamp: quando fai riferimento a momenti specifici di un video all'interno del prompt, utilizza il formato MM:SS (ad es. 01:15 per 1 minuto e 15 secondi).
  • Posizionamento del prompt: se combini testo e un singolo video, posiziona il prompt testuale dopo la parte video nell'array contents.
  • Timeout per richieste lunghe: per i video che richiedono tempi di elaborazione prolungati o ragionamenti multi-step complessi, utilizza lo streaming (client.models.generate_content_stream). Le richieste sincrone non di streaming che subiscono tentativi di ripetizione del backend in condizioni di elevata domanda possono superare le finestre di validità della connessione o del token di autenticazione, il che può causare errori 401 Unauthorized o di timeout imprevisti. Lo streaming mantiene attiva la connessione e mostra il ragionamento intermedio e l'avanzamento della chiamata dello strumento.

Passaggi successivi

  • Risoluzione dei contenuti multimediali: controlla la risoluzione dei fotogrammi video per bilanciare qualità e utilizzo dei token.
  • Token: scopri come vengono tokenizzati i contenuti video nelle modalità di elaborazione statica e con agenti.
  • Istruzioni di sistema: Le istruzioni di sistema ti consentono di orientare il comportamento del modello in base alle tue esigenze e ai tuoi casi d'uso specifici.
  • API Files: scopri di più sul caricamento e sulla gestione dei file da utilizzare con Gemini.
  • Strategie di prompt dei file: l'API Gemini supporta i prompt con dati di testo, immagini, audio e video, noti anche come prompt multimodali.
  • Indicazioni per la sicurezza: a volte i modelli di AI generativa producono output inaspettati, ad esempio output imprecisi, di parte o offensivi. Il post-processing e la valutazione umana sono essenziali per limitare il rischio di danni derivanti da questi output.