Comprensione dei video

Puoi aggiungere video alle richieste di Gemini per eseguire attività che richiedono la comprensione dei contenuti dei video inclusi. Questa pagina mostra come aggiungere video alle tue richieste a Gemini in Gemini Enterprise Agent Platform utilizzando la console Google Cloud e l'API Agent Platform.

Modelli supportati

La tabella seguente elenca i modelli che supportano la comprensione dei video:

Modelli Dettagli dei contenuti multimediali Tipi MIME
  • Durata massima del video (con audio): 10 secondi
  • Durata massima del video (senza audio): 10 secondi
  • Numero massimo di video per prompt: 3
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Durata massima del video (con audio): 15 secondi
  • Durata massima del video (senza audio): 15 secondi
  • Durata massima del video di input (comprensione dei video): 10 minuti
  • Durata massima del video di input (editing): 15 secondi
  • Durata massima del video di input (estensione): qualsiasi durata (vengono utilizzati fino agli ultimi 10 secondi)
  • Durata massima del video di input (upscaling): 15 secondi
  • Durata del video di output (generazione e modifica): da 3 a 15 secondi (da 3 a 10 secondi per il primo e l'ultimo frame)
  • Durata del video di output (estensione): da 3 a 10 secondi (concatenati fino agli ultimi 30 secondi del video di input)
  • Numero massimo di video per prompt: 3
  • Proporzioni supportate: 16:9, 9:16
  • Risoluzioni supportate: 360p, 720p, 1080p, 4K
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Durata massima del video (con audio): 10 secondi
  • Durata massima del video (senza audio): 10 secondi
  • Numero massimo di video per prompt: 3
  • Proporzioni supportate: 16:9, 9:16
  • Risoluzioni supportate: 360p, 720p, 1080p, 4K
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Numero massimo di file video di input per prompt: 10
  • Numero massimo di URL di YouTube per richiesta: 1
  • Durata massima del video (senza audio): come supportato dalla finestra di contesto da 128.000 token (circa 25 minuti).
  • Dimensione massima della parte in linea: 256 MB
  • Dimensioni massime per file da Cloud Storage: 2 GiB meno 500 KiB
  • Dimensione massima per file da URL HTTP o HTTPS pubblici: 15 MiB
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Durata massima del video (con audio): circa 45 minuti
  • Durata massima del video (senza audio): circa 1 ora
  • Numero massimo di video per prompt: 10
  • Dimensione massima della parte incorporata (API GenerateContent): 256 MB
  • Dimensioni massime per file da Cloud Storage: 2 GiB meno 500 KiB
  • Dimensione massima per file da URL HTTP o HTTPS pubblici: 15 MiB
  • Token per frame con risoluzione predefinita: 70
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Risoluzione di input standard: 768 x 768 (1 FPS)
  • Risoluzione minima dell'output dell'avatar live: 704 x 1280 (verticale) o 1280 x 704 (orizzontale) a 24 FPS
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Numero massimo di file video di input per prompt: 10
  • Numero massimo di URL di YouTube per richiesta: 1
  • Durata massima del video (senza audio): supportata dalla finestra di contesto da 65.536 token (circa 12 minuti).
  • Dimensione massima della parte in linea: 256 MB
  • Dimensioni massime per file da Cloud Storage: 2 GiB meno 500 KiB
  • Dimensione massima per file da URL HTTP o HTTPS pubblici: 15 MiB
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Durata massima del video (con audio): circa 45 minuti
  • Durata massima del video (senza audio): circa 1 ora
  • Numero massimo di video per prompt: 10 (fino a 1 URL HTTP o HTTPS su endpoint non migrati)
  • Dimensione massima della parte in linea: 256 MB
  • Dimensioni massime per file da Cloud Storage: 2 GiB meno 500 KiB
  • Dimensione massima per file da URL HTTP o HTTPS pubblici: 15 MiB
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp
  • Risoluzione standard: 768 x 768
  • video/x-flv
  • video/quicktime
  • video/mpeg
  • video/mpegs
  • video/mpg
  • video/mp4
  • video/webm
  • video/wmv
  • video/3gpp

Per un elenco delle lingue supportate dai modelli Gemini, consulta le informazioni sui modelli Modelli Google. Per scoprire di più su come progettare prompt multimodali, consulta Progetta prompt multimodali. Se stai cercando un modo per utilizzare Gemini direttamente dalle tue app web e mobile, consulta gli SDK client Firebase AI Logic per le app Swift, Android, web, Flutter e Unity.

Limiti degli endpoint API e della finestra contestuale

I modelli Gemini 3 e successivi standard accettano fino a 3000 immagini e PDF combinati, 1000 file audio o 10 video per richiesta sia in generateContent che nell'API Interactions (fino a 6500 file multimodali combinati se sono inclusi file di testo normale). Gli endpoint Gemini 2.5 non migrati e gemini-3.1-pro-preview-customtools applicano i limiti legacy per le dimensioni dei file, le pagine PDF (1000) e il numero di URL HTTP o HTTPS. I limiti pratici delle richieste dipendono anche dall'endpoint API, dall'origine del file e dalla finestra di contesto:

  • Limite di URI dell'API Interactions per i file di Cloud Storage: le richieste dell'API Interactions supportano fino a 100 URI Cloud Storage (gs://) distinti per richiesta di interazione con il modello, inclusi gli URI trasferiti dai turni di conversazione precedenti tramite previous_interaction_id. Le richieste generateContent supportano gli URI gs:// fino al limite di elementi del modello.
  • Limiti per l'origine file, la parte incorporata e il payload della richiesta: i singoli file a cui viene fatto riferimento da Cloud Storage non possono superare i 2 GiB meno 500 KiB, mentre i file a cui viene fatto riferimento da URL HTTP o HTTPS pubblici non possono superare i 15 MiB. Su generateContent e streamGenerateContent, ogni allegato incorporato (inline_data) non può superare i 256 MB sui modelli Gemini 3 standard e successivi e il payload totale della richiesta HTTP o gRPC compressa non può superare i 500 MiB (la codifica base64 aggiunge un overhead di dimensioni di circa il 33%). Nell'API Interactions, il payload della richiesta HTTP compressa non può superare i 256 MiB per le richieste sincrone o in streaming; quando service_tier è impostato su deferred (che richiede che sia background sia store siano true), la richiesta non compressa non può superare i 9,75 MiB.
  • Finestra di contesto: il numero totale di token di tutti gli input multimodali e del testo in una richiesta non può superare il limite di token di input del modello (1.048.576 token su Gemini 3 standard e modelli successivi).

Aggiungi video a una richiesta

Puoi aggiungere uno o più video alla tua richiesta a Gemini e i video possono includere l'audio.

Video singolo

Il codice campione in ciascuna delle seguenti schede Stai seguendo mostra un modo diverso per identificare i contenuti di un video. Questo esempio funziona con tutti i modelli multimodali Gemini.

Console

Per inviare un prompt multimodale utilizzando la console Google Cloud , segui questi passaggi:

  1. Nella sezione Agent Platform della console Google Cloud , vai alla pagina Agent Studio.

    Vai ad Agent Studio

  2. Fai clic su Crea prompt.

  3. (Facoltativo) Configura il modello e i parametri:

    • Modello: seleziona un modello.
  4. (Facoltativo) Per configurare i parametri avanzati, fai clic su Avanzate e configura quanto segue:

    Fai clic per espandere le configurazioni avanzate

    • Top-K: utilizza il cursore o la casella di testo per inserire un valore per top-K.

      Top-K cambia il modo in cui il modello seleziona i token per l'output. Un top-K pari a 1 indica che il token successivo selezionato è il più probabile tra tutti i token nel vocabolario del modello (chiamato anche decodifica greedy). Un top-K pari a 3 indica, invece, che il token successivo viene selezionato tra i tre token più probabili (utilizzando la temperatura).

      Per ogni fase di selezione dei token, vengono campionati i token Top-K con le probabilità più alte. Quindi i token vengono ulteriormente filtrati in base a top-P e il token finale viene selezionato utilizzando il campionamento con temperatura.

      Specifica un valore più basso per risposte meno casuali e un valore più alto per risposte più casuali.

    • Top-P: utilizza il cursore o la casella di testo per inserire un valore per top-P. I token vengono selezionati dal più probabile al meno probabile, finché la somma delle probabilità non corrisponde al valore di top-P. Per ridurre al minimo la variabilità dei risultati, imposta Top-P su 0.
    • Numero massimo di risposte: utilizza il cursore o la casella di testo per inserire un valore per il numero di risposte da generare.
    • Risposte dinamiche: attiva questa opzione per stampare le risposte man mano che vengono generate.
    • Soglia del filtro di sicurezza: seleziona la soglia di probabilità di ricevere risposte potenzialmente dannose.
    • Abilita grounding: il grounding non è supportato per i prompt multimodali.
    • Regione: seleziona la regione che vuoi utilizzare.
    • Temperatura: utilizza il cursore o la casella di testo per inserire un valore per la temperatura.

          
      The temperature is used for sampling during response generation, which occurs when topP
      and topK are applied. Temperature controls the degree of randomness in token selection.
      Lower temperatures are good for prompts that require a less open-ended or creative response, while
      higher temperatures can lead to more diverse or creative results. A temperature of 0
      means that the highest probability tokens are always selected. In this case, responses for a given
      prompt are mostly deterministic, but a small amount of variation is still possible.
      
      

      If the model returns a response that's too generic, too short, or the model gives a fallback response, try increasing the temperature. If the model enters infinite generation, increasing the temperature to at least 0.1 may lead to improved results.

      1.0 is the recommended starting value for temperature. </li> <li>**Output token limit**: Use the slider or textbox to enter a value for the max output limit. Maximum number of tokens that can be generated in the response. A token is approximately four characters. 100 tokens correspond to roughly 60-80 words.

      Specify a lower value for shorter responses and a higher value for potentially longer responses.

      </li> <li>**Add stop sequence**: Optional. Enter a stop sequence, which is a series of characters that includes spaces. If the model encounters a stop sequence, the response generation stops. The stop sequence isn't included in the response, and you can add up to five stop sequences.</li> </ul>

  5. Fai clic su Inserisci contenuti multimediali e seleziona un'origine per il file.

    Carica

    Seleziona il file che vuoi caricare e fai clic su Apri.

    Tramite URL

    Inserisci l'URL del file che vuoi utilizzare e fai clic su Inserisci.

    YouTube

    Inserisci l'URL del video di YouTube che vuoi utilizzare e fai clic su Inserisci.

    Puoi utilizzare qualsiasi video pubblico o un video di proprietà dell'account che hai utilizzato per accedere alla console Google Cloud .

    Cloud Storage

    Seleziona il bucket e poi il file da importare dal bucket e fai clic su Seleziona.

    Google Drive

    1. Scegli un account e concedi ad Agent Studio il consenso per accedere al tuo account la prima volta che selezioni questa opzione. Puoi caricare più file con una dimensione totale massima di 10 MB. Un singolo file non può superare i 7 MB.
    2. Fai clic sul file che vuoi aggiungere.
    3. Fai clic su Seleziona.

      La miniatura del file viene visualizzata nel riquadro Prompt. Viene visualizzato anche il numero totale di token. Se i dati del prompt superano il limite di token, i token vengono troncati e non vengono inclusi nell'elaborazione dei dati.

  6. Inserisci il prompt testuale nel riquadro Prompt.

  7. (Facoltativo) Per visualizzare l'ID token in testo e gli ID token, fai clic sul conteggio dei token nel riquadro Prompt.

  8. Fai clic su Invia.

  9. (Facoltativo) Per salvare il prompt in I miei prompt, fai clic su Salva.

  10. (Facoltativo) Per ottenere il codice Python o un comando curl per il prompt, fai clic su Crea con il codice > Ottieni codice.

Python

Installa

pip install --upgrade google-genai

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK Google Gen AI con Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

from google import genai
from google.genai.types import HttpOptions, Part

client = genai.Client(http_options=HttpOptions(api_version="v1"))
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        Part.from_uri(
            file_uri="gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
            mime_type="video/mp4",
        ),
        "What is in the video?",
    ],
)
print(response.text)
# Example response:
# The video shows several people surfing in an ocean with a coastline in the background. The camera ...

Go

Scopri come installare o aggiornare l'Go.

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK Google Gen AI con Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithMuteVideo shows how to generate text using a video with no sound as the input.
func generateWithMuteVideo(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "What is in the video?"},
			{FileData: &genai.FileData{
				FileURI:  "gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
				MIMEType: "video/mp4",
			}},
		},
			Role: genai.RoleUser},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, nil)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// The video shows several surfers riding waves in an ocean setting. The waves are ...

	return nil
}

Java

Scopri come installare o aggiornare l'Java.

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK Google Gen AI con Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True


import com.google.genai.Client;
import com.google.genai.types.Content;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Part;

public class TextGenerationWithMuteVideo {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    generateContent(modelId);
  }

  // Generates text with mute video input
  public static String generateContent(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      GenerateContentResponse response =
          client.models.generateContent(
              modelId,
              Content.fromParts(
                  Part.fromUri(
                      "gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
                      "video/mp4"),
                  Part.fromText("What is in this video?")),
              null);

      System.out.print(response.text());
      // Example response:
      // This video features **surfers in the ocean**.
      //
      // The main focus is on **one individual who catches and rides a wave**, executing various
      // turns and maneuvers as the wave breaks and dissipates into whitewater...
      return response.text();
    }
  }
}

Node.js

Installa

npm install @google/genai

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK Google Gen AI con Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateText(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash-lite',
    contents: [
      {
        role: 'user',
        parts: [
          {
            fileData: {
              mimeType: 'video/mp4',
              fileUri:
                'gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4',
            },
          },
          {
            text: 'What is in the video?',
          },
        ],
      },
    ],
    config: {
      mediaResolution: 'MEDIA_RESOLUTION_LOW',
    },
  });

  console.log(response.text);

  // Example response:
  // The video shows several people surfing in an ocean with a coastline in the background. The camera ...

  return response.text;
}

REST

Dopo aver configurato l'ambiente, puoi utilizzare REST per testare un prompt testuale. L'esempio seguente invia una richiesta all'endpoint del modello del publisher.

API GenerateContent

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto.
  • FILE_URI: l'URI o l'URL del file da includere nel prompt. I valori accettati includono:
    • URI del bucket Cloud Storage: l'oggetto deve essere leggibile pubblicamente o risiedere nello stesso progetto Google Cloud che invia la richiesta.
    • URL HTTP: l'URL del file deve essere leggibile pubblicamente e non può superare i 15 MiB per file. I modelli Gemini 3 standard e successivi accettano fino a 3000 immagini e PDF combinati, 1000 file audio o 10 video per richiesta (fino a 6500 file totali se sono inclusi file di testo normale). Gli endpoint Gemini 2.5 non migrati e gemini-3.1-pro-preview-customtools limitano gli URL HTTP o HTTPS a 10 immagini, 1 file audio o 1 video per richiesta.
    • URL del video di YouTube: il video di YouTube deve essere di proprietà dell'account che hai utilizzato per accedere alla console Google Cloud o essere pubblico. È supportato un solo URL di video di YouTube per richiesta.

    Quando specifichi un fileURI, devi anche specificare il tipo di media (mimeType) del file. Se i Controlli di servizio VPC sono abilitati, non è supportata la specifica di un URL di un file multimediale per fileURI.

    Se non hai un file video in Cloud Storage, puoi utilizzare il seguente file disponibile pubblicamente: gs://cloud-samples-data/video/animals.mp4 con un tipo MIME video/mp4. Per visualizzare questo video, apri il file MP4 di esempio.

  • MIME_TYPE: il tipo di media del file specificato nei campi data o fileUri. I valori accettati includono:

    Fai clic per espandere i tipi MIME

    • application/pdf
    • audio/mpeg
    • audio/mp3
    • audio/wav
    • image/png
    • image/jpeg
    • image/webp
    • text/plain
    • video/mov
    • video/mpeg
    • video/mp4
    • video/mpg
    • video/avi
    • video/wmv
    • video/mpegps
    • video/flv
  • TEXT: le istruzioni di testo da includere nel prompt. Ad esempio: What is in the video?

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

cat > request.json << 'EOF'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
EOF

Quindi esegui questo comando per inviare la richiesta REST:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent"

PowerShell

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

@'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Quindi esegui questo comando per inviare la richiesta REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente.

API Interactions

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto
  • FILE_URI: l'URI o l'URL del file da includere nel prompt. I valori accettati includono:
    • URI del bucket Cloud Storage: l'oggetto deve essere leggibile pubblicamente o risiedere nello stesso progetto Google Cloud che invia la richiesta.
    • URL HTTP: l'URL del file deve essere leggibile pubblicamente e non può superare i 15 MiB per file. I modelli Gemini 3 standard e successivi accettano fino a 3000 immagini e PDF combinati, 1000 file audio o 10 video per richiesta (fino a 6500 file totali se sono inclusi file di testo normale). Gli endpoint Gemini 2.5 non migrati e gemini-3.1-pro-preview-customtools limitano gli URL HTTP o HTTPS a 10 immagini, 1 file audio o 1 video per richiesta.
    • URL del video di YouTube: il video di YouTube deve essere di proprietà dell'account che hai utilizzato per accedere alla console Google Cloud o essere pubblico. È supportato un solo URL di video di YouTube per richiesta.

    Quando specifichi un fileURI, devi anche specificare il tipo di media (mimeType) del file. Se i Controlli di servizio VPC sono abilitati, non è supportata la specifica di un URL di un file multimediale per fileURI.

    Se non hai un file video in Cloud Storage, puoi utilizzare il seguente file disponibile pubblicamente: gs://cloud-samples-data/video/animals.mp4 con un tipo MIME video/mp4. Per visualizzare questo video, apri il file MP4 di esempio.

  • MIME_TYPE: il tipo di media del file specificato nei campi data o fileUri. I valori accettati includono:

    Fai clic per espandere i tipi MIME

    • application/pdf
    • audio/mpeg
    • audio/mp3
    • audio/wav
    • image/png
    • image/jpeg
    • image/webp
    • text/plain
    • video/mov
    • video/mpeg
    • video/mp4
    • video/mpg
    • video/avi
    • video/wmv
    • video/mpegps
    • video/flv
  • TEXT: le istruzioni di testo da includere nel prompt. Ad esempio: What is in the video?

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

cat > request.json << 'EOF'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "uri": "FILE_URI",
          "mime_type": "MIME_TYPE"
        },
        {
          "type": "text",
          "text": "TEXT"
        }
      ]
    }
  ]
}
EOF

Quindi esegui questo comando per inviare la richiesta REST:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions"

PowerShell

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

@'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "uri": "FILE_URI",
          "mime_type": "MIME_TYPE"
        },
        {
          "type": "text",
          "text": "TEXT"
        }
      ]
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

Quindi esegui questo comando per inviare la richiesta REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente.

Nell'URL di questo esempio, tieni presente quanto segue:
  • Utilizza il metodo generateContent per richiedere che la risposta venga restituita dopo che è stata generata completamente. Per ridurre la percezione della latenza per un pubblico umano, trasmetti la risposta mentre viene generata utilizzando il metodo streamGenerateContent.
  • L'ID del modello multimodale si trova alla fine dell'URL prima del metodo (ad esempio, gemini-3.5-flash). Questo esempio potrebbe supportare anche altri modelli.
  • Quando utilizzi un endpoint API regionale (ad esempio us-central1), la regione dell'URL dell'endpoint determina dove viene elaborata la richiesta. Qualsiasi località in conflitto nel percorso della risorsa viene ignorata.

Video con audio

Di seguito viene mostrato come riassumere un file video con audio e restituire i capitoli con i timestamp. Questo esempio funziona con tutti i modelli multimodali Gemini che supportano video con audio.

Python

Installa

pip install --upgrade google-genai

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK Google Gen AI con Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

from google import genai
from google.genai.types import HttpOptions, Part

client = genai.Client(http_options=HttpOptions(api_version="v1"))
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents=[
        Part.from_uri(
            file_uri="gs://cloud-samples-data/generative-ai/video/ad_copy_from_video.mp4",
            mime_type="video/mp4",
        ),
        "What is in the video?",
    ],
)
print(response.text)
# Example response:
# The video shows several people surfing in an ocean with a coastline in the background. The camera ...

REST

Dopo aver configurato l'ambiente, puoi utilizzare REST per testare un prompt testuale. L'esempio seguente invia una richiesta all'endpoint del modello del publisher.

API GenerateContent

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto.
  • FILE_URI: l'URI o l'URL del file da includere nel prompt. I valori accettati includono:
    • URI del bucket Cloud Storage: l'oggetto deve essere leggibile pubblicamente o risiedere nello stesso progetto Google Cloud che invia la richiesta.
    • URL HTTP: l'URL del file deve essere leggibile pubblicamente e non può superare i 15 MiB per file. I modelli Gemini 3 standard e successivi accettano fino a 3000 immagini e PDF combinati, 1000 file audio o 10 video per richiesta (fino a 6500 file totali se sono inclusi file di testo normale). Gli endpoint Gemini 2.5 non migrati e gemini-3.1-pro-preview-customtools limitano gli URL HTTP o HTTPS a 10 immagini, 1 file audio o 1 video per richiesta.
    • URL del video di YouTube: il video di YouTube deve essere di proprietà dell'account che hai utilizzato per accedere alla console Google Cloud o essere pubblico. È supportato un solo URL di video di YouTube per richiesta.

    Quando specifichi un fileURI, devi anche specificare il tipo di media (mimeType) del file. Se i Controlli di servizio VPC sono abilitati, non è supportata la specifica di un URL di un file multimediale per fileURI.

    Se non hai un file video in Cloud Storage, puoi utilizzare il seguente file disponibile pubblicamente: gs://cloud-samples-data/generative-ai/video/pixel8.mp4 con un tipo MIME video/mp4. Per visualizzare questo video, apri il file MP4 di esempio.

  • MIME_TYPE: il tipo di media del file specificato nei campi data o fileUri. I valori accettati includono:

    Fai clic per espandere i tipi MIME

    • application/pdf
    • audio/mpeg
    • audio/mp3
    • audio/wav
    • image/png
    • image/jpeg
    • image/webp
    • text/plain
    • video/mov
    • video/mpeg
    • video/mp4
    • video/mpg
    • video/avi
    • video/wmv
    • video/mpegps
    • video/flv
  • TEXT Le istruzioni di testo da includere nel prompt. Ad esempio: Provide a description of the video. The description should also contain anything important which people say in the video.

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

cat > request.json << 'EOF'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
EOF

Quindi esegui questo comando per inviare la richiesta REST:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent"

PowerShell

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

@'
{
  "contents": {
    "role": "USER",
    "parts": [
      {
        "fileData": {
          "fileUri": "FILE_URI",
          "mimeType": "MIME_TYPE"
        }
      },
      {
        "text": "TEXT"
      }
    ]
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Quindi esegui questo comando per inviare la richiesta REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente.

API Interactions

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto
  • FILE_URI: l'URI o l'URL del file da includere nel prompt. I valori accettati includono:
    • URI del bucket Cloud Storage: l'oggetto deve essere leggibile pubblicamente o risiedere nello stesso progetto Google Cloud che invia la richiesta.
    • URL HTTP: l'URL del file deve essere leggibile pubblicamente e non può superare i 15 MiB per file. I modelli Gemini 3 standard e successivi accettano fino a 3000 immagini e PDF combinati, 1000 file audio o 10 video per richiesta (fino a 6500 file totali se sono inclusi file di testo normale). Gli endpoint Gemini 2.5 non migrati e gemini-3.1-pro-preview-customtools limitano gli URL HTTP o HTTPS a 10 immagini, 1 file audio o 1 video per richiesta.
    • URL del video di YouTube: il video di YouTube deve essere di proprietà dell'account che hai utilizzato per accedere alla console Google Cloud o essere pubblico. È supportato un solo URL di video di YouTube per richiesta.

    Quando specifichi un fileURI, devi anche specificare il tipo di media (mimeType) del file. Se i Controlli di servizio VPC sono abilitati, non è supportata la specifica di un URL di un file multimediale per fileURI.

    Se non hai un file video in Cloud Storage, puoi utilizzare il seguente file disponibile pubblicamente: gs://cloud-samples-data/generative-ai/video/pixel8.mp4 con un tipo MIME video/mp4. Per visualizzare questo video, apri il file MP4 di esempio.

  • MIME_TYPE: il tipo di media del file specificato nei campi data o fileUri. I valori accettati includono:

    Fai clic per espandere i tipi MIME

    • application/pdf
    • audio/mpeg
    • audio/mp3
    • audio/wav
    • image/png
    • image/jpeg
    • image/webp
    • text/plain
    • video/mov
    • video/mpeg
    • video/mp4
    • video/mpg
    • video/avi
    • video/wmv
    • video/mpegps
    • video/flv
  • TEXT Le istruzioni di testo da includere nel prompt. Ad esempio: Provide a description of the video. The description should also contain anything important which people say in the video.

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

cat > request.json << 'EOF'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "uri": "FILE_URI",
          "mime_type": "MIME_TYPE"
        },
        {
          "type": "text",
          "text": "TEXT"
        }
      ]
    }
  ]
}
EOF

Quindi esegui questo comando per inviare la richiesta REST:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions"

PowerShell

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

@'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "uri": "FILE_URI",
          "mime_type": "MIME_TYPE"
        },
        {
          "type": "text",
          "text": "TEXT"
        }
      ]
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

Quindi esegui questo comando per inviare la richiesta REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente.

Nell'URL di questo esempio, tieni presente quanto segue:
  • Utilizza il metodo generateContent per richiedere che la risposta venga restituita dopo che è stata generata completamente. Per ridurre la percezione della latenza per un pubblico umano, trasmetti la risposta mentre viene generata utilizzando il metodo streamGenerateContent.
  • L'ID del modello multimodale si trova alla fine dell'URL prima del metodo (ad esempio, gemini-3.5-flash). Questo esempio potrebbe supportare anche altri modelli.
  • Quando utilizzi un endpoint API regionale (ad esempio us-central1), la regione dell'URL dell'endpoint determina dove viene elaborata la richiesta. Qualsiasi località in conflitto nel percorso della risorsa viene ignorata.

Console

Per inviare un prompt multimodale utilizzando la console Google Cloud , segui questi passaggi:

  1. Nella sezione Agent Platform della console Google Cloud , vai alla pagina Agent Studio.

    Vai ad Agent Studio

  2. Fai clic su Crea prompt.

  3. (Facoltativo) Configura il modello e i parametri:

    • Modello: seleziona un modello.
  4. (Facoltativo) Per configurare i parametri avanzati, fai clic su Avanzate e configura quanto segue:

    Fai clic per espandere le configurazioni avanzate

    • Top-K: utilizza il cursore o la casella di testo per inserire un valore per top-K.

      Top-K cambia il modo in cui il modello seleziona i token per l'output. Un top-K pari a 1 indica che il token successivo selezionato è il più probabile tra tutti i token nel vocabolario del modello (chiamato anche decodifica greedy). Un top-K pari a 3 indica, invece, che il token successivo viene selezionato tra i tre token più probabili (utilizzando la temperatura).

      Per ogni fase di selezione dei token, vengono campionati i token Top-K con le probabilità più alte. Quindi i token vengono ulteriormente filtrati in base a top-P e il token finale viene selezionato utilizzando il campionamento con temperatura.

      Specifica un valore più basso per risposte meno casuali e un valore più alto per risposte più casuali.

    • Top-P: utilizza il cursore o la casella di testo per inserire un valore per top-P. I token vengono selezionati dal più probabile al meno probabile, finché la somma delle probabilità non corrisponde al valore di top-P. Per ridurre al minimo la variabilità dei risultati, imposta Top-P su 0.
    • Numero massimo di risposte: utilizza il cursore o la casella di testo per inserire un valore per il numero di risposte da generare.
    • Risposte dinamiche: attiva questa opzione per stampare le risposte man mano che vengono generate.
    • Soglia del filtro di sicurezza: seleziona la soglia di probabilità di ricevere risposte potenzialmente dannose.
    • Abilita grounding: il grounding non è supportato per i prompt multimodali.
    • Regione: seleziona la regione che vuoi utilizzare.
    • Temperatura: utilizza il cursore o la casella di testo per inserire un valore per la temperatura.

          
      The temperature is used for sampling during response generation, which occurs when topP
      and topK are applied. Temperature controls the degree of randomness in token selection.
      Lower temperatures are good for prompts that require a less open-ended or creative response, while
      higher temperatures can lead to more diverse or creative results. A temperature of 0
      means that the highest probability tokens are always selected. In this case, responses for a given
      prompt are mostly deterministic, but a small amount of variation is still possible.
      
      

      If the model returns a response that's too generic, too short, or the model gives a fallback response, try increasing the temperature. If the model enters infinite generation, increasing the temperature to at least 0.1 may lead to improved results.

      1.0 is the recommended starting value for temperature. </li> <li>**Output token limit**: Use the slider or textbox to enter a value for the max output limit. Maximum number of tokens that can be generated in the response. A token is approximately four characters. 100 tokens correspond to roughly 60-80 words.

      Specify a lower value for shorter responses and a higher value for potentially longer responses.

      </li> <li>**Add stop sequence**: Optional. Enter a stop sequence, which is a series of characters that includes spaces. If the model encounters a stop sequence, the response generation stops. The stop sequence isn't included in the response, and you can add up to five stop sequences.</li> </ul>

  5. Fai clic su Inserisci contenuti multimediali e seleziona un'origine per il file.

    Carica

    Seleziona il file che vuoi caricare e fai clic su Apri.

    Tramite URL

    Inserisci l'URL del file che vuoi utilizzare e fai clic su Inserisci.

    YouTube

    Inserisci l'URL del video di YouTube che vuoi utilizzare e fai clic su Inserisci.

    Puoi utilizzare qualsiasi video pubblico o un video di proprietà dell'account che hai utilizzato per accedere alla console Google Cloud .

    Cloud Storage

    Seleziona il bucket e poi il file da importare dal bucket e fai clic su Seleziona.

    Google Drive

    1. Scegli un account e concedi ad Agent Studio il consenso per accedere al tuo account la prima volta che selezioni questa opzione. Puoi caricare più file con una dimensione totale massima di 10 MB. Un singolo file non può superare i 7 MB.
    2. Fai clic sul file che vuoi aggiungere.
    3. Fai clic su Seleziona.

      La miniatura del file viene visualizzata nel riquadro Prompt. Viene visualizzato anche il numero totale di token. Se i dati del prompt superano il limite di token, i token vengono troncati e non vengono inclusi nell'elaborazione dei dati.

  6. Inserisci il prompt testuale nel riquadro Prompt.

  7. (Facoltativo) Per visualizzare l'ID token in testo e gli ID token, fai clic sul conteggio dei token nel riquadro Prompt.

  8. Fai clic su Invia.

  9. (Facoltativo) Per salvare il prompt in I miei prompt, fai clic su Salva.

  10. (Facoltativo) Per ottenere il codice Python o un comando curl per il prompt, fai clic su Crea con il codice > Ottieni codice.

Personalizza l'elaborazione dei video

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

Imposta gli intervalli di ritaglio

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

Imposta una frequenza fotogrammi personalizzata

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

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

Comprensione dei video agentica

La comprensione dei video agentica consente al modello di navigare dinamicamente nei contenuti video anziché dover elaborare ogni frame in modo statico. La comprensione dei video basata su agenti utilizza meno token rispetto all'elaborazione statica e può migliorare la qualità delle risposte. Ciò può comportare costi inferiori e risposte più rapide per i workload di video nel formato lungo.

Puoi utilizzare la comprensione dei video agentica e l'elaborazione statica per video diversi nella stessa richiesta. Ad esempio, se hai video nel formato lungo (come una lezione di un'ora) e contenuti video nel formato breve (come YouTube Shorts), puoi utilizzare la comprensione dei video basata su agenti sui video nel formato lungo per scegliere come target informazioni contestualmente pertinenti e l'elaborazione statica sui contenuti video nel formato breve per una precisione a livello di frame.

Il contesto del video deve essere preservato durante i vari passaggi di una conversazione:

  • API Interactions: per impostazione predefinita, le interazioni stateful conservano automaticamente il contesto del video quando utilizzi previous_interaction_id. Per le richieste stateless (quando non utilizzi previous_interaction_id), la risposta include steps che codificano il contesto del video. Devi passare questi passaggi al turno successivo per preservare il contesto.
  • API GenerateContent: devi passare la cronologia completa della conversazione (tutti i turni contents precedenti) in ogni richiesta successiva per preservare il contesto.

Se il contesto del video viene omesso in un turno successivo, il modello non può rispondere alle domande sul video senza rielaborarlo.

Modelli e tipi di file supportati

La comprensione dei video agentica è supportata nei seguenti modelli:

Fai clic per espandere i modelli supportati

Puoi utilizzare le seguenti fonti quando utilizzi la comprensione dei video agentica:

  • URL di YouTube
  • URI Cloud Storage
  • File video incorporati codificati in Base64

Quando utilizzare la comprensione dei video agentica

Utilizza la comprensione dei video agentica (media_processing = "AGENTIC") per i seguenti workload:

  • Domande e risposte e ricerca di video nel formato lungo: fai domande mirate o individua eventi specifici in lezioni, riunioni, registrazioni o video tutorial di un'ora senza tokenizzare ogni frame a risoluzione piena.
  • Ispezione visiva dettagliata: esegui lo zoom su timestamp o dettagli visivi specifici (ad esempio, lettura di testo di piccole dimensioni sullo schermo, slide o modifiche al tabellone segnapunti) all'interno di un video più lungo.
  • Confronto di più video: confronta più video in un'unica richiesta. Puoi utilizzare modalità di elaborazione diverse per ogni video all'interno della stessa richiesta.
  • Agenti basati su video: crea agenti che ragionano sui contenuti video con il supporto di conversazioni multi-turn. Il contesto del video viene conservato tra i turni senza rielaborazione.
  • Ottimizzazione dei costi per workload video lunghi: riduci il consumo di token per le applicazioni video nel formato lungo in cui solo un sottoinsieme di segmenti è pertinente al prompt.

Mantieni l'elaborazione statica predefinita (media_processing = "STATIC") quando:

  • Elaborazione di brevi clip: per i video brevi, l'elaborazione statica evita l'overhead della navigazione degli strumenti in più passaggi e in genere utilizza meno token con una latenza inferiore.
  • Elaborazione uniforme dell'intero video: il tuo workload richiede un'analisi uniforme frame per frame dell'intero clip, anziché un'ispezione mirata di segmenti specifici.

Utilizza la comprensione dei video agentica

Puoi attivare la comprensione dei video agentica impostando "processing": "agentic" nell'API Interactions o media_processing = "AGENTIC" nell'API GenerateContent:

Python

API GenerateContent

from google import genai
from google.genai import types

client = genai.Client()

# Example: Controlling media_processing explicitly
video_part = types.Part(
  file_data=types.FileData(
      file_uri="gs://my-bucket-name/sports_clip.mp4",
      mime_type="video/mp4",
  ),
  media_processing="agentic" # Options: "agentic", "static"
)

response = client.models.generate_content(
  model="gemini-3.7-flash",
  contents=[
      video_part,
      "Analyze the player's footwork right before the shot."
  ]
)
print(response.text)

API Interactions

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Example: Controlling video processing explicitly
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": "gs://my-bucket-name/sports_clip.mp4",
            "mime_type": "video/mp4",
            "processing": "agentic",  # Options: "agentic", "static"
        },
        {
            "type": "text",
            "text": "Analyze the player's footwork right before the shot.",
        },
    ],
    generation_config={
        "thinking_level": "medium",
    },
)
print(interaction.output_text)

REST

API GenerateContent

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

cat > request.json << 'EOF'
{
  "contents": [
    {
      "role": "USER",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "gs://my-bucket/lecture.mp4"
          },
          "mediaProcessing": "AGENTIC"
        },
        {
          "text": "Summarize the key takeaways."
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingLevel": "MEDIUM"
  }
}
EOF

Quindi esegui questo comando per inviare la richiesta REST:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.7-flash:generateContent"

PowerShell

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

@'
{
  "contents": [
    {
      "role": "USER",
      "parts": [
        {
          "fileData": {
            "mimeType": "video/mp4",
            "fileUri": "gs://my-bucket/lecture.mp4"
          },
          "mediaProcessing": "AGENTIC"
        },
        {
          "text": "Summarize the key takeaways."
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingLevel": "MEDIUM"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Quindi esegui questo comando per inviare la richiesta REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.7-flash:generateContent" | Select-Object -Expand Content

API Interactions

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

cat > request.json << 'EOF'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "mime_type": "video/mp4",
          "uri": "gs://my-bucket/lecture.mp4",
          "processing": "agentic"
        },
        {
          "type": "text",
          "text": "Summarize the key takeaways."
        }
      ]
    }
  ],
  "generation_config": {
    "thinking_level": "medium"
  }
}
EOF

Quindi esegui questo comando per inviare la richiesta REST:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions"

PowerShell

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

@'
{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "video",
          "mime_type": "video/mp4",
          "uri": "gs://my-bucket/lecture.mp4",
          "processing": "agentic"
        },
        {
          "type": "text",
          "text": "Summarize the key takeaways."
        }
      ]
    }
  ],
  "generation_config": {
    "thinking_level": "medium"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Quindi esegui questo comando per inviare la richiesta REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" | Select-Object -Expand Content

La comprensione dei video agentica è impostata su STATIC o disattivata per impostazione predefinita per tutti i modelli supportati.

Regola la risoluzione dei contenuti multimediali

Puoi modificare MediaResolution per elaborare i tuoi video con meno token.

Imposta i parametri facoltativi del modello

Ogni modello ha un insieme di parametri facoltativi che puoi impostare. Per ulteriori informazioni, consulta Parametri di generazione dei contenuti.

Tokenizzazione dei video

Con Gemini 3, la tokenizzazione dei video utilizza una lunghezza di sequenza variabile, che sostituisce il metodo Pan and Scan utilizzato nei modelli precedenti per migliorare la qualità e la latenza.

Puoi specificare una risoluzione multimediale per gli input video, che influisce sulla tokenizzazione dei video e sul numero di token utilizzati per ogni video. Puoi impostare media_resolution in generationConfig in modo che venga applicato a tutti i contenuti multimediali della richiesta oppure impostarlo per singole parti multimediali, il che sostituirà l'impostazione di primo livello. La risoluzione predefinita per i video è di 70 token per frame.

Per i modelli Gemini 3 sono disponibili le seguenti risoluzioni:

  • MEDIA_RESOLUTION_HIGH: 280 token per frame
  • MEDIA_RESOLUTION_MEDIUM: 70 token per frame
  • MEDIA_RESOLUTION_LOW: 70 token per frame
  • MEDIA_RESOLUTION_UNSPECIFIED: 70 token per frame (predefinito)

Per i modelli precedenti a Gemini 3, ogni frame viene tokenizzato a 258 token per frame per la risoluzione predefinita o a 66 token per frame per la bassa risoluzione.

Questo esempio di codice mostra come regolare media_resolution:

API GenerateContent

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model="gemini-3.1-pro-preview",
  contents=[
      types.Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png",
              mime_type="image/jpeg",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_HIGH
          ),
      ),
      types.Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/video/behind_the_scenes_pixel.mp4",
              mime_type="video/mp4",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_LOW
          ),
      ),
      "When does the image appear in the video? What is the context?",
  ],
)
print(response.text)

API Interactions

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "image",
            "uri": "gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png",
            "mime_type": "image/png",
            "resolution": "high",  # Options: "low", "medium", "high", "ultra_high"
        },
        {
            "type": "video",
            "uri": "gs://cloud-samples-data/generative-ai/video/behind_the_scenes_pixel.mp4",
            "mime_type": "video/mp4",
            "resolution": "low",  # Options: "low", "medium", "high", "ultra_high"
        },
        {
            "type": "text",
            "text": "When does the image appear in the video? What is the context?",
        },
    ],
)
print(interaction.output_text)

Best practice

Quando utilizzi i video, segui queste best practice e informazioni per ottenere i risultati migliori:

  • Se il prompt contiene un singolo video, posizionalo prima del prompt di testo.
  • Se hai bisogno della localizzazione dei timestamp in un video con audio, chiedi al modello di generare timestamp che seguono il formato descritto in "Formato dei timestamp".

Per i modelli Gemini 3, tieni presente anche quanto segue:

  • Utilizza una frequenza di campionamento di frame al secondo (FPS) più elevata per i video che richiedono un'analisi temporale granulare, ad esempio per comprendere azioni rapide o rilevare movimenti ad alta velocità.

Limitazioni

Sebbene i modelli multimodali Gemini siano potenti in molti casi d'uso multimodali, è importante comprenderne i limiti:

  • Moderazione dei contenuti: i modelli si rifiutano di fornire risposte su video che violano le nostre norme sulla sicurezza.
  • Riconoscimento di suoni non vocali: i modelli che supportano l'audio potrebbero commettere errori nel riconoscimento di suoni non vocali.

Dettagli tecnici sui video

  • 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.

    • Queste tariffe sono soggette a modifiche in futuro per miglioramenti nell'inferenza.
  • Formato del timestamp: quando fai riferimento a momenti specifici di un video all'interno del prompt, il formato del timestamp dipende dalla frequenza di campionamento dei frame al secondo (FPS) del video:

    • Per frequenze di campionamento pari o inferiori a 1 FPS: utilizza il formato MM:SS, in cui le prime due cifre rappresentano i minuti e le ultime due i secondi. Se hai offset superiori a 1 ora, utilizza il formato H:MM:SS.

    • Per frequenze di campionamento superiori a 1 f/s: utilizza il formato MM:SS.sss o, se hai offset superiori a 1 ora, utilizza il formato H:MM:SS.sss, descritto di seguito:

      • La prima cifra rappresenta l'ora.
      • Le seconde due cifre rappresentano i minuti.
      • Le ultime due cifre rappresentano i secondi.
      • Le ultime tre cifre rappresentano i millisecondi.
  • Best practice:

    • Per risultati ottimali, utilizza un solo video per ogni richiesta di prompt.

    • Se combini testo e un singolo video, inserisci il prompt testuale dopo la parte del video nell'array contents.

    • Tieni presente che le sequenze d'azione rapide potrebbero perdere dettagli a causa della frequenza di campionamento di 1 FPS. Se necessario, valuta la possibilità di rallentare questi clip.

Passaggi successivi