I modelli Gemini possono elaborare i video, consentendo molti casi d'uso di frontiera per gli sviluppatori 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 da video con una durata massima di 90 minuti
- Rispondere alle domande sui contenuti video
- Fare riferimento a timestamp specifici all'interno di un video
Gemini è stato progettato 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.
Prima di iniziare
Prima di chiamare l'API Gemini, assicurati di aver installato l'SDK che preferisci e di avere configurato e pronto all'uso una chiave API Gemini.
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 di dimensioni inferiori (fino a 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 file video. Questo esempio utilizza il breve film della NASA "Jupiter's Great Red Spot Shrinks and Grows". Crediti: Goddard Space Flight Center (GSFC)/David Ladd (2018).
"La Grande Macchia Rossa di Giove si restringe e si espande" è di dominio pubblico e non mostra persone identificabili. (Linee guida per l'utilizzo di immagini e contenuti multimediali della NASA).
Il codice seguente scarica il video di esempio, lo carica utilizzando l'API File,
attende che venga elaborato e poi utilizza il riferimento del file in
una richiesta generateContent
.
Python
from google import genai
client = genai.Client(api_key="GOOGLE_API_KEY")
myfile = client.files.upload(file="path/to/sample.mp4")
response = client.models.generate_content(
model="gemini-2.0-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({ apiKey: "GOOGLE_API_KEY" });
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.0-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
file, err := client.UploadFileFromPath(ctx, "path/to/sample.mp4", nil)
if err != nil {
log.Fatal(err)
}
defer client.DeleteFile(ctx, file.Name)
model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
genai.FileData{URI: file.URI},
genai.Text("Summarize this video. Then create a quiz with an answer key based on the information in this video."))
if err != nil {
log.Fatal(err)
}
printResponse(resp)
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?key=${GOOGLE_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.0-flash:generateContent?key=$GOOGLE_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 scoprire di più su come utilizzare i file multimediali, consulta API Files.
Passare i dati video in linea
Anziché caricare un file video utilizzando l'API File, puoi passare video di dimensioni ridotte direttamente nella richiesta a generateContent
. È adatto per i video più brevi di dimensioni inferiori 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.0-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({ apiKey: "GOOGLE_API_KEY" });
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.0-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.0-flash:generateContent?key=$GOOGLE_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
Includi un URL di YouTube
L'API Gemini e AI Studio supportano gli URL di YouTube come dati di file Part
. Puoi includere un URL di YouTube con un prompt che chiede al modello di riassumere, tradurre o interagire in altro modo con i contenuti video.
Limitazioni:
- Non puoi caricare più di 8 ore di video di YouTube al giorno.
- Puoi caricare un solo 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.0-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
ctx := context.Background()
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("GOOGLE_API_KEY")))
if err != nil {
log.Fatal(err)
}
defer client.Close()
model := client.GenerativeModel("gemini-2.0-flash")
resp, err := model.GenerateContent(ctx,
genai.FileData{URI: "https://www.youtube.com/watch?v=9hE5-98ZeCg"},
genai.Text("Please summarize the video in 3 sentences."))
if err != nil {
log.Fatal(err)
}
// Handle the response of generated text.
for _, c := range resp.Candidates {
if c.Content != nil {
fmt.Println(*c.Content)
}
}
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=$GOOGLE_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
Fai riferimento ai timestamp nei contenuti
Puoi porre domande su punti temporali specifici all'interno del video utilizzando i timestamp del tipo 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.FileData{URI: currentVideoFile.URI, MIMEType: currentVideoFile.MIMEType},
// Adjusted timestamps for the NASA video
genai.Text("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 i video e fornire descrizioni visive
I modelli Gemini possono trascrivere e fornire descrizioni visive dei contenuti video elaborando sia la traccia audio sia i fotogrammi video. Per le descrizioni visive, il modello campiona il video a una frequenza di 1 frame al secondo. Questa frequenza di campionamento può influire sul livello di dettaglio delle descrizioni, soprattutto per i video con immagini in rapida evoluzione.
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.FileData{URI: currentVideoFile.URI, MIMEType: currentVideoFile.MIMEType},
genai.Text("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."
Formati video supportati
Gemini supporta i seguenti tipi MIME di formato 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 di 2 milioni di token possono elaborare video fino a 2 ore, mentre i modelli con una finestra contestuale di 1 milione di token possono elaborare video fino a 1 ora.
- 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 rapporti sono soggetti a modifiche in futuro per i miglioramenti dell'inferenza.
- Calcolo dei token: ogni secondo di video viene tokenizzato come segue:
- Singoli frame (campionati a 1 FPS): 258 token per frame.
- Audio: 32 token al secondo.
- Sono inclusi anche i metadati.
- Totale: circa 300 token per secondo di video.
- Formato 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). - 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 d'azione rapide potrebbero perdere dettagli a causa della frequenza di campionamento di 1 FPS. Valuta la possibilità di rallentare questi clip, se necessario.
Passaggi successivi
Questa guida mostra come caricare file video e generare output di testo da input video. Per saperne di più, consulta le seguenti risorse:
- Istruzioni di sistema: le istruzioni di sistema ti consentono di indirizzare 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 IA generativa producono output inaspettati, ad esempio imprecisi, biassati o offensivi. Il post-trattamento e la valutazione umana sono essenziali per limitare il rischio di danni derivanti da questi output.