Risoluzione dei contenuti multimediali

Il parametro media_resolution controlla il modo in cui l'API Gemini elabora gli input multimediali come immagini, video, audio e documenti PDF determinando il numero massimo di token allocati per gli input multimediali, consentendoti di bilanciare la qualità della risposta rispetto alla latenza e al costo. Mentre gli input visivi e di documenti scalano l'allocazione dei token in base all'impostazione della risoluzione, gli input audio vengono tokenizzati a una velocità fissa al secondo su tutti i livelli di risoluzione. Per le diverse impostazioni, i valori predefiniti e la loro corrispondenza con i token, consulta la sezione Conteggi dei token.

Puoi configurare la risoluzione dei media per i singoli oggetti multimediali (elementi di contenuti) all'interno della richiesta (modelli Gemini 4 e Gemini 3).

Risoluzione dei media per elemento di contenuti (modelli Gemini 4 e Gemini 3)

I modelli Gemini 4 e Gemini 3 ti consentono di impostare la risoluzione dei media per i singoli oggetti multimediali all'interno della richiesta, offrendo un'ottimizzazione granulare dell'utilizzo dei token. Puoi combinare i livelli di risoluzione in una singola richiesta. Ad esempio, puoi utilizzare l'alta risoluzione per un diagramma complesso e la bassa risoluzione per un'immagine contestuale semplice.

from google import genai

client = genai.Client()

myfile = client.files.upload(file="path/to/image.jpg")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Describe this image:"},
        {
            "type": "image",
            "uri": myfile.uri,
            "mime_type": myfile.mime_type,
            "resolution": "high"
        }
    ]
)
print(interaction.output_text)

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

const ai = new GoogleGenAI({});

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/image.jpg",
    config: { mime_type: "image/jpeg" },
  });

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "text", text: "Describe this image:" },
      {
        type: "image",
        uri: myfile.uri,
        mime_type: myfile.mimeType,
        resolution: "high"
      }
    ],
  });
  console.log(interaction.output_text);
}

await main();

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

Client client = new Client();

Content textContent = TextContent.builder().text("Describe the details in this high-resolution image.").build();
Content imageContent =
    ImageContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/image/scones.jpg")
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .build();

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

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

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

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

package main

import (
    "context"
    "fmt"
    "log"

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

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

    uploadedFile, err := client.Files.UploadFromPath(ctx, "path/to/image.jpg", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "Describe the details in this high-resolution image.",
                }),
                interactions.NewContent(interactions.ImageContent{
                    URI:        genai.Ptr(uploadedFile.URI),
                    MimeType:   interactions.ImageContentMimeType(uploadedFile.MIMEType).ToPointer(),
                    Resolution: interactions.MediaResolutionHigh.ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

# First upload the file using the Files API, then use the URI:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {"type": "text", "text": "Describe this image:"},
      {
        "type": "image",
        "uri": "YOUR_FILE_URI",
        "mime_type": "image/jpeg",
        "resolution": "high"
      }
    ]
  }'

Valori di risoluzione disponibili

L'API Gemini definisce i seguenti livelli per la risoluzione dei media:

• unspecified: l'impostazione predefinita. Il conteggio dei token per questo livello varia in modo significativo tra i modelli Gemini 4/3 e i modelli Gemini precedenti.
• low: conteggio dei token inferiore, con conseguente elaborazione più rapida e costi inferiori, ma con meno dettagli.
• medium: un equilibrio tra dettagli, costi e latenza.
• high: conteggio dei token più elevato, che fornisce più dettagli al modello, a scapito di una maggiore latenza e costi.
• ultra_high (solo per elemento di contenuti): conteggio dei token più elevato, necessario per casi d'uso specifici come l'utilizzo del computer.

Tieni presente che high offre prestazioni ottimali per la maggior parte dei casi d'uso.

Il numero esatto di token generati per ciascuno di questi livelli dipende sia dal tipo di media (immagine, video, audio, PDF) sia dalla versione del modello.

Conteggi dei token

Le tabelle seguenti riepilogano i conteggi approssimativi dei token per ogni valore media_resolution e tipo di media per famiglia di modelli.

Modelli Gemini 4 e Gemini 3

Scegliere la risoluzione giusta

• Valore predefinito (unspecified): inizia con il valore predefinito. È ottimizzato per un buon equilibrio tra qualità, latenza e costi per i casi d'uso più comuni.
• low: utilizza questa impostazione per gli scenari in cui i costi e la latenza sono fondamentali e i dettagli granulari sono meno importanti.
• medium / high: aumenta la risoluzione quando l'attività richiede la comprensione di dettagli complessi all'interno dei media. Questo è spesso necessario per l'analisi visiva complessa, la lettura di grafici o la comprensione di documenti densi.
• ultra_high : disponibile solo per l'impostazione per elemento di contenuti. Consigliato per casi d'uso specifici come l'utilizzo del computer o quando i test mostrano un miglioramento netto rispetto a high.
• Controllo per elemento di contenuti (Gemini 4 e Gemini 3): ottimizza l'utilizzo dei token. Ad esempio, in un prompt con più immagini, utilizza high per un diagramma complesso e low o medium per immagini contestuali più semplici.

Impostazioni consigliate

Di seguito sono elencate le impostazioni di risoluzione dei media consigliate per ogni tipo di media supportato.

Esegui sempre test e valuta l'impatto delle diverse impostazioni di risoluzione sulla tua applicazione per trovare il miglior compromesso tra qualità, latenza e costi.

Relazione con le modalità di elaborazione dei video

I parametri media_resolution ed `processing` controllano aspetti diversi dell'input video:

• media_resolution controlla la risoluzione di ogni frame (numero di token per frame).
• processing / media_processing controlla quali contenuti del video vengono caricati nel contesto.

Puoi impostarli entrambi sullo stesso input video. Ad esempio, potresti utilizzare l'elaborazione agentica con una risoluzione dei media bassa per ridurre al minimo l'utilizzo totale dei token per un video lungo.

Per informazioni dettagliate sulle modalità di elaborazione dei video, consulta la guida alla comprensione dei video agentici.

Riepilogo della compatibilità delle versioni

• L'impostazione di resolution sui singoli elementi di contenuti è supportata sui modelli Gemini 4 e Gemini 3.

Passaggi successivi

• Scopri di più sulle funzionalità multimodali dell'API Gemini nelle guide alla comprensione delle immagini, alla comprensione dei video, alla comprensione dell'audio, e alla comprensione dei documenti.