Veo 3 è ora disponibile nell'API Gemini. Scopri di più

Questa pagina è stata tradotta dall'API Cloud Translation.

Comprensione dei video

I modelli Gemini possono elaborare video, consentendo molti casi d'uso per gli sviluppatori all'avanguardia che in passato avrebbero richiesto modelli specifici del 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
Fare riferimento a timestamp specifici all'interno di un video

Gemini è stato creato per essere multimodale fin dall'inizio e continuiamo a spingere i confini di ciò che è possibile. Questa guida mostra come utilizzare l'API Gemini per generare risposte di testo in base agli input video.

Ingresso video

Puoi fornire video come input a Gemini nei seguenti modi:

Carica un file video utilizzando l'API File prima di effettuare una richiesta a generateContent. Utilizza questo metodo per file di dimensioni superiori a 20 MB, video più lunghi di circa 1 minuto o quando vuoi riutilizzare il file in più richieste.
Trasmetti i dati video in linea con la richiesta a generateContent. Utilizza questo metodo per file più piccoli (< 20 MB) e durate più brevi.
Includi un URL di YouTube direttamente nel prompt.

Caricare un file video

Puoi utilizzare l'API Files per caricare un file video. 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) sono superiori a 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.

Il seguente codice scarica il video di esempio, lo carica utilizzando l'API File, attende l'elaborazione e quindi utilizza il riferimento al file in una richiesta generateContent.

Python

from google import genai

client = genai.Client()

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

response = client.models.generate_content(
    model="gemini-2.5-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-2.5-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();

Vai

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-2.5-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-2.5-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 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 una dimensione totale della richiesta inferiore a 20 MB.

Ecco un esempio di fornitura di dati video in linea:

Python

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

response = client.models.generate_content(
    model='models/gemini-2.5-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.')
        ]
    )
)

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-2.5-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-2.5-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

Includere un URL di YouTube

L'API Gemini e AI Studio supportano gli URL di YouTube come Part di dati dei file. Puoi includere un URL di YouTube con un prompt che chiede al modello di riassumere, tradurre o interagire in altro modo con i contenuti del video.

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 è previsto alcun limite in base alla durata del video.
Per i modelli precedenti alla versione 2.5, puoi caricare un solo video per richiesta. Per i modelli successivi alla versione 2.5, puoi caricare un massimo di 10 video per richiesta.
Puoi caricare solo video pubblici (non privati o non in elenco).

L'esempio seguente mostra come includere un URL di YouTube con un prompt:

Python

response = client.models.generate_content(
    model='models/gemini-2.5-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.')
        ]
    )
)

JavaScript

import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-1.5-pro" });
const result = await model.generateContent([
  "Please summarize the video in 3 sentences.",
  {
    fileData: {
      fileUri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    },
  },
]);
console.log(result.response.text());

Vai

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-2.5-flash",
      contents,
      nil,
  )

  fmt.Println(result.Text())
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-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

Fare riferimento ai timestamp nei contenuti

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

Python

prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?" # Adjusted timestamps for the NASA video

JavaScript

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

Vai

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
         // Adjusted timestamps for the NASA video
        genai.NewPartFromText("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?"

Trascrivere il video e fornire descrizioni visive

I modelli Gemini possono trascrivere e fornire descrizioni visive dei contenuti video elaborando sia la traccia audio che i fotogrammi visivi. Per le descrizioni visive, il modello campiona il video a una velocità di 1 frame al secondo. Questa frequenza di campionamento può influire sul livello di dettaglio delle descrizioni, in particolare per i video con immagini in rapido cambiamento.

Python

prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

JavaScript

const prompt = "Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions.";

Vai

    prompt := []*genai.Part{
        genai.NewPartFromURI(currentVideoFile.URI, currentVideoFile.MIMEType),
        genai.NewPartFromText("Transcribe the audio from this video, giving timestamps for salient events in the video. Also " +
            "provide visual descriptions."),
    }

REST

PROMPT="Transcribe the audio from this video, giving timestamps for salient events in the video. Also provide visual descriptions."

Personalizzare l'elaborazione video

Puoi personalizzare l'elaborazione dei video nell'API Gemini impostando intervalli di ritaglio o fornendo un campionamento della frequenza dei fotogrammi personalizzato.

Impostare gli intervalli di ritaglio

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

Python

response = client.models.generate_content(
    model='models/gemini-2.5-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.')
        ]
    )
)

Impostare un frame rate personalizzato

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

Python

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

response = client.models.generate_content(
    model='models/gemini-2.5-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.')
        ]
    )
)

Per impostazione predefinita, viene campionato 1 frame al secondo (FPS) dal video. Potresti voler impostare un valore FPS basso (< 1) per i video lunghi. Questa opzione è particolarmente utile per i video per lo più statici (ad es. lezioni). Se vuoi acquisire più dettagli in immagini che cambiano rapidamente, valuta la possibilità di impostare un valore FPS più alto.

Formati video supportati

Gemini supporta i seguenti tipi MIME di formati video:

video/mp4
video/mpeg
video/mov
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 2.0 e 2.5 possono elaborare i dati video.
- I modelli con una finestra contestuale da 2 milioni di token possono elaborare video della durata massima di 2 ore alla risoluzione multimediale predefinita o di 6 ore alla risoluzione multimediale bassa, mentre i modelli con una finestra contestuale da 1 milione di token possono elaborare video della durata massima di 1 ora alla risoluzione multimediale predefinita o di 3 ore alla risoluzione multimediale bassa.
Elaborazione dell'API File: quando utilizzi l'API File, i video vengono campionati a 1 frame al secondo (FPS) e l'audio viene elaborato a 1 Kbps (canale singolo). I timestamp vengono aggiunti ogni secondo.
- Questi tassi sono soggetti a modifiche future per migliorare l'inferenza.
Calcolo dei token: ogni secondo di video viene tokenizzato nel seguente modo:
- Singoli fotogrammi (campionati a 1 FPS):
  - Se mediaResolution è 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 300 token al secondo di video alla risoluzione multimediale predefinita o 100 token al secondo di video alla risoluzione multimediale bassa.
Formato timestamp: quando fai riferimento a momenti specifici di un video nel prompt, utilizza il formato MM:SS (ad es. 01:15 per 1 minuto e 15 secondi).
Best practice:
- Per risultati ottimali, utilizza un solo video per richiesta di prompt.
- Se combini testo e un singolo video, inserisci il prompt di testo dopo la parte video nell'array contents.
- Tieni presente che le sequenze di azioni rapide potrebbero perdere dettagli a causa della frequenza di campionamento di 1 FPS. Se necessario, valuta la possibilità di rallentare questi clip.

Passaggi successivi

Questa guida mostra come caricare file video e generare output di testo dagli input video. Per saperne di più, consulta le seguenti risorse:

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, immagine, audio e video, noti anche come prompt multimodali.
Linee guida per la sicurezza: a volte i modelli di AI generativa producono output inattesi, ad esempio output imprecisi, distorti o offensivi. Il post-processing e la valutazione umana sono essenziali per limitare il rischio di danni derivanti da questi output.