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 contenuti multimediali in due modi:

• Per parte (modelli Gemini 4 e Gemini 3)

• A livello globale per un'intera richiesta generateContent (tutti i modelli multimodali)

Risoluzione dei contenuti multimediali per parte (Gemini 4 e Gemini 3)

Gemini 4 e Gemini 3 ti consentono di impostare la risoluzione dei contenuti multimediali per 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. Questa impostazione sostituisce qualsiasi configurazione globale per una parte specifica. Per le impostazioni predefinite, consulta la sezione Conteggi dei token.

from google import genai
from google.genai import types

# The media_resolution parameter for parts is available in the v1beta API version.
client = genai.Client(
  http_options={
      'api_version': 'v1beta',
  }
)

# Replace with your image data
with open('path/to/image1.jpg', 'rb') as f:
    image_bytes_1 = f.read()

# Create parts with different resolutions
image_part_high = types.Part.from_bytes(
    data=image_bytes_1,
    mime_type='image/jpeg',
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_HIGH
)

model_name = 'gemini-4-argon'

response = client.models.generate_content(
    model=model_name,
    contents=["Describe these images:", image_part_high]
)
print(response.text)

// Example: Setting per-part media resolution in JavaScript
import { GoogleGenAI, MediaResolution, Part } from '@google/genai';
import * as fs from 'fs';
import { Buffer } from 'buffer'; // Node.js

const ai = new GoogleGenAI({ httpOptions: { apiVersion: 'v1beta' } });

// Helper function to convert local file to a Part object
function fileToGenerativePart(path, mimeType, mediaResolution) {
    return {
        inlineData: { data: Buffer.from(fs.readFileSync(path)).toString('base64'), mimeType },
        mediaResolution: { 'level': mediaResolution }
    };
}

async function run() {
    // Create parts with different resolutions
    const imagePartHigh = fileToGenerativePart('img.png', 'image/png', Part.MediaResolutionLevel.MEDIA_RESOLUTION_HIGH);
    const model_name = 'gemini-4-argon';
    const response = await ai.models.generateContent({
        model: model_name,
        contents: ['Describe these images:', imagePartHigh]
        // Global config can still be set, but per-part settings will override
        // config: {
        //   mediaResolution: MediaResolution.MEDIA_RESOLUTION_MEDIUM
        // }
    });
    console.log(response.text);
}
run();

# Replace with paths to your images
IMAGE_PATH="path/to/image.jpg"

# Base64 encode the images
BASE64_IMAGE1=$(base64 -w 0 "$IMAGE_PATH")

MODEL_ID="gemini-4-argon"

echo '{
    "contents": [{
      "parts": [
        {"text": "Describe these images:"},
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": "'"$BASE64_IMAGE1"'",
          },
          "media_resolution": {"level": "MEDIA_RESOLUTION_HIGH"}
        }
      ]
    }]
  }' > request.json

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/${MODEL_ID}:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Risoluzione dei contenuti multimediali globale

Puoi impostare una risoluzione predefinita per tutte le parti multimediali di una richiesta utilizzando GenerationConfig. Questa opzione è supportata da tutti i modelli multimodali. Se una richiesta include sia impostazioni globali sia per parte, l'impostazione per parte ha la precedenza per l'elemento specifico.

from google import genai
from google.genai import types

client = genai.Client()

# Prepare standard image part
with open('image.jpg', 'rb') as f:
    image_bytes = f.read()
image_part = types.Part.from_bytes(data=image_bytes, mime_type='image/jpeg')

# Set global configuration
config = types.GenerateContentConfig(
    media_resolution=types.MediaResolution.MEDIA_RESOLUTION_HIGH
)

response = client.models.generate_content(
    model='gemini-3.8-flash',
    contents=["Describe this image:", image_part],
    config=config
)
print(response.text)

import { GoogleGenAI, MediaResolution } from '@google/genai';
import * as fs from 'fs';

const ai = new GoogleGenAI({ });

async function run() {
   // ... (Image loading logic) ...

   const response = await ai.models.generateContent({
      model: 'gemini-3.8-flash',
      contents: ["Describe this image:", imagePart],
      config: {
         mediaResolution: MediaResolution.MEDIA_RESOLUTION_HIGH
      }
   });
   console.log(response.text);
}
run();

# ... (Base64 encoding logic) ...

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [...],
    "generation_config": {
      "media_resolution": "MEDIA_RESOLUTION_HIGH"
    }
  }'

Valori di risoluzione disponibili

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

• MEDIA_RESOLUTION_UNSPECIFIED: l'impostazione predefinita. Il conteggio dei token per questo livello varia in modo significativo tra Gemini 3 e i modelli Gemini precedenti.
• MEDIA_RESOLUTION_LOW: conteggio dei token inferiore, con conseguente elaborazione più rapida e costi inferiori, ma con meno dettagli.
• MEDIA_RESOLUTION_MEDIUM: un equilibrio tra dettagli, costi e latenza.
• MEDIA_RESOLUTION_HIGH: conteggio dei token più elevato, che fornisce più dettagli al modello, a scapito di una maggiore latenza e di costi più elevati.
• MEDIA_RESOLUTION_ULTRA_HIGH (solo per parte): conteggio dei token più elevato, necessario per casi d'uso specifici come l'utilizzo del computer.

Tieni presente che MEDIA_RESOLUTION_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 contenuti multimediali (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 contenuti multimediali per famiglia di modelli.

Modelli Gemini 3

Modelli Gemini 2.5

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 opzione per gli scenari in cui costi e 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 contenuti multimediali. Questa opzione è spesso necessaria per l'analisi visiva complessa, la lettura di grafici o la comprensione di documenti densi.
• ULTRA HIGH : disponibile solo per l'impostazione per parte. Opzione consigliata per casi d'uso specifici come l'utilizzo del computer o quando i test mostrano un miglioramento netto rispetto a HIGH.
• Controllo per parte (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 contenuti multimediali consigliate per ogni tipo di contenuti multimediali supportato.

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

Relazione con le modalità di elaborazione video

I parametri media_resolution ed elaborazione 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 impostare entrambi gli input video. Ad esempio, potresti utilizzare l'elaborazione agentica con una risoluzione dei contenuti multimediali bassa per ridurre al minimo l'utilizzo totale dei token per un video lungo.

Per maggiori dettagli sulle modalità di elaborazione video, consulta la guida Comprensione dei video agentica.

Riepilogo della compatibilità delle versioni

• L'enumerazione MediaResolution è disponibile per tutti i modelli che supportano l'input multimediale.
• I conteggi dei token associati a ogni livello di enumerazione differiscono tra i modelli Gemini 4 / Gemini 3 e le versioni precedenti di Gemini.
• L'impostazione di media_resolution sui singoli oggetti Part è supportata sui modelli Gemini 4 e Gemini 3.

Passaggi successivi

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