Guida per gli sviluppatori di Gemini 3

Gemini 3 è la nostra famiglia di modelli più intelligente finora, basata su un ragionamento all'avanguardia. È progettato per dare vita a qualsiasi idea padroneggiando workflow agentici, programmazione autonoma e attività multimodali complesse. Questa guida illustra le funzionalità principali della famiglia di modelli Gemini 3 e come sfruttarle al meglio.

Pensiero elevato/dinamico Pensiero basso

Gemini 3 Pro utilizza per impostazione predefinita il pensiero dinamico per ragionare sui prompt. Per risposte più rapide e con una latenza inferiore quando non è necessario un ragionamento complesso, puoi limitare il livello di pensiero del modello a low.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
)

print(response.text)

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

const ai = new GoogleGenAI({});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
  });

  console.log(response.text);
}

run();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Find the race condition in this multi-threaded C++ snippet: [code here]"}]
    }]
  }'

Esplora

Esplora la nostra raccolta di app Gemini 3 per scoprire come il modello gestisce il ragionamento avanzato, la programmazione autonoma e le attività multimodali complesse.

Scopri Gemini 3

Gemini 3 Pro è il primo modello della nuova serie. gemini-3-pro-preview è ideale per le attività complesse che richiedono un'ampia conoscenza del mondo e un ragionamento avanzato tra le varie modalità.

* I prezzi si basano su 1 milione di token. I prezzi indicati si riferiscono al testo standard; le tariffe per l'input multimodale possono variare.

Per informazioni dettagliate sui limiti di frequenza, sui prezzi dei batch e su ulteriori informazioni, consulta la pagina dei modelli.

Nuove funzionalità dell'API in Gemini 3

Gemini 3 introduce nuovi parametri progettati per offrire agli sviluppatori un maggiore controllo su latenza, costi e fedeltà multimodale.

Livello di pensiero

Il parametro thinking_level controlla la profondità massima del processo di ragionamento interno del modello prima che produca una risposta. Gemini 3 considera questi livelli come allocazioni relative per il ragionamento, anziché garanzie rigide di token. Se thinking_level non è specificato, Gemini 3 Pro utilizzerà high come valore predefinito.

• low: riduce al minimo la latenza e i costi. Ideale per applicazioni semplici di follow-up delle istruzioni, chat o ad alto rendimento
• medium: (disponibile a breve), non supportato al lancio
• high (predefinito): massimizza la profondità del ragionamento. Il modello potrebbe impiegare molto più tempo per raggiungere il primo token, ma l'output sarà più ragionato.

Risoluzione dei contenuti multimediali

Gemini 3 introduce un controllo granulare sull'elaborazione della visione multimodale tramite il parametro media_resolution. Risoluzioni più elevate migliorano la capacità del modello di leggere testi piccoli o identificare piccoli dettagli, ma aumentano l'utilizzo di token e la latenza. Il parametro media_resolution determina il numero massimo di token allocati per ogni immagine di input o frame video.

Ora puoi impostare la risoluzione su media_resolution_low, media_resolution_medium o media_resolution_high per ogni parte multimediale o a livello globale (tramite generation_config). Se non specificato, il modello utilizza i valori predefiniti ottimali in base al tipo di contenuti multimediali.

Impostazioni consigliate

from google import genai
from google.genai import types
import base64

# The media_resolution parameter is currently only available in the v1alpha API version.
client = genai.Client(http_options={'api_version': 'v1alpha'})

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents=[
        types.Content(
            parts=[
                types.Part(text="What is in this image?"),
                types.Part(
                    inline_data=types.Blob(
                        mime_type="image/jpeg",
                        data=base64.b64decode("..."),
                    ),
                    media_resolution={"level": "media_resolution_high"}
                )
            ]
        )
    ]
)

print(response.text)

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

// The media_resolution parameter is currently only available in the v1alpha API version.
const ai = new GoogleGenAI({ apiVersion: "v1alpha" });

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: [
      {
        parts: [
          { text: "What is in this image?" },
          {
            inlineData: {
              mimeType: "image/jpeg",
              data: "...",
            },
            mediaResolution: {
              level: "media_resolution_high"
            }
          }
        ]
      }
    ]
  });

  console.log(response.text);
}

run();

curl "https://generativelanguage.googleapis.com/v1alpha/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        { "text": "What is in this image?" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "..."
          },
          "mediaResolution": {
            "level": "media_resolution_high"
          }
        }
      ]
    }]
  }'

Temperatura

Per Gemini 3, ti consigliamo vivamente di mantenere il parametro di temperatura sul valore predefinito di 1.0.

Mentre i modelli precedenti spesso traevano vantaggio dalla regolazione della temperatura per controllare la creatività rispetto al determinismo, le funzionalità di ragionamento di Gemini 3 sono ottimizzate per l'impostazione predefinita. La modifica della temperatura (impostandola su un valore inferiore a 1.0) può comportare un comportamento imprevisto, ad esempio un ciclo o un rendimento ridotto, in particolare in attività matematiche o di ragionamento complesse.

Firme dei pensieri

Gemini 3 utilizza le firme del pensiero per mantenere il contesto del ragionamento tra le chiamate API. Queste firme sono rappresentazioni criptate del processo di pensiero interno del modello. Per garantire che il modello mantenga le sue capacità di ragionamento, devi restituire queste firme al modello nella tua richiesta esattamente come sono state ricevute:

• Chiamata di funzioni (rigorosa): l'API applica una convalida rigorosa del "turno corrente". Le firme mancanti genereranno un errore 400.
• Testo/Chat:la convalida non è strettamente applicata, ma l'omissione delle firme peggiorerà la qualità del ragionamento e delle risposte del modello.

Chiamata di funzione (convalida rigorosa)

Quando Gemini genera un functionCall, si basa sul thoughtSignature per elaborare correttamente l'output dello strumento nel turno successivo. Il "Turno attuale" include tutti i passaggi del modello (functionCall) e dell'utente (functionResponse) che si sono verificati dall'ultimo messaggio Utente text standard.

• Chiamata di una singola funzione:la parte functionCall contiene una firma. Devi restituirlo.
• Chiamate di funzioni parallele:solo la prima parte functionCall dell'elenco conterrà la firma. Devi restituire le parti nell'ordine esatto in cui le hai ricevute.
• Multistep (sequenziale): se il modello chiama uno strumento, riceve un risultato e chiama un altro strumento (nello stesso turno), entrambe le chiamate di funzione hanno firme. Devi restituire tutte le firme accumulate nella cronologia.

Testo e streaming

Per la generazione di chat o testi standard, la presenza di una firma non è garantita.

• Non in streaming: l'ultima parte dei contenuti della risposta potrebbe contenere un thoughtSignature, anche se non è sempre presente. Se uno viene restituito, devi rimandarlo indietro per mantenere le migliori prestazioni.
• Streaming: se viene generata una firma, potrebbe arrivare in un blocco finale che contiene una parte di testo vuota. Assicurati che l'analizzatore di stream controlli le firme anche se il campo di testo è vuoto.

Esempi di codice

// Model Response (Turn 1, Step 1)
  {
    "role": "model",
    "parts": [
      {
        "functionCall": { "name": "check_flight", "args": {...} },
        "thoughtSignature": "<Sig_A>" // SAVE THIS
      }
    ]
  }

// User Request (Turn 1, Step 2)
[
  { "role": "user", "parts": [{ "text": "Check flight AA100..." }] },
  { 
    "role": "model", 
    "parts": [
      { 
        "functionCall": { "name": "check_flight", "args": {...} }, 
        "thoughtSignature": "<Sig_A>" // REQUIRED
      } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": { "name": "check_flight", "response": {...} } }] }
]

// Model Response (Turn 1, Step 3)
{
  "role": "model",
  "parts": [
    {
      "functionCall": { "name": "book_taxi", "args": {...} },
      "thoughtSignature": "<Sig_B>" // SAVE THIS
    }
  ]
}

// User Request (Turn 1, Step 4)
[
  // ... previous history ...
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "check_flight", ... }, "thoughtSignature": "<Sig_A>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] },
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "book_taxi", ... }, "thoughtSignature": "<Sig_B>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] }
]

// User Request (Sending Parallel Results)
[
  {
    "role": "user",
    "parts": [
      { "text": "Check the weather in Paris and London." }
    ]
  },
  {
    "role": "model",
    "parts": [
      // 1. First Function Call has the signature
      {
        "functionCall": { "name": "check_weather", "args": { "city": "Paris" } },
        "thoughtSignature": "<Signature_A>" 
      },
      // 2. Subsequent parallel calls DO NOT have signatures
      {
        "functionCall": { "name": "check_weather", "args": { "city": "London" } }
      } 
    ]
  },
  {
    "role": "user",
    "parts": [
      // 3. Function Responses are grouped together in the next block
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "15C" } }
      },
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "12C" } }
      }
    ]
  }
]

// User Request (Follow-up question)
[
  { 
    "role": "user", 
    "parts": [{ "text": "What are the risks of this investment?" }] 
  },
  { 
    "role": "model", 
    "parts": [
      {
        "text": "I need to calculate the risk step-by-step. First, I'll look at volatility...",
        "thoughtSignature": "<Signature_C>" // Recommended to include
      }
    ]
  },
  { 
    "role": "user", 
    "parts": [{ "text": "Summarize that in one sentence." }] 
  }
]

Eseguire la migrazione da altri modelli

Se stai trasferendo una traccia della conversazione da un altro modello (ad es. Gemini 2.5) o inserendo una chiamata di funzione personalizzata non generata da Gemini 3, non avrai una firma valida.

Per ignorare la convalida rigorosa in questi scenari specifici, compila il campo con questa stringa fittizia specifica: "thoughtSignature": "context_engineering_is_the_way_to_go"

Output strutturati con strumenti

Gemini 3 ti consente di combinare gli output strutturati con strumenti integrati, tra cui Grounding con la Ricerca Google, Contesto URL ed Esecuzione di codice.

from google import genai
from google.genai import types
from pydantic import BaseModel, Field
from typing import List

class MatchResult(BaseModel):
    winner: str = Field(description="The name of the winner.")
    final_match_score: str = Field(description="The final match score.")
    scorers: List[str] = Field(description="The name of the scorer.")

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Search for all details for the latest Euro.",
    config={
        "tools": [
            {"google_search": {}},
            {"url_context": {}}
        ],
        "response_mime_type": "application/json",
        "response_json_schema": MatchResult.model_json_schema(),
    },  
)

result = MatchResult.model_validate_json(response.text)
print(result)

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});

const matchSchema = z.object({
  winner: z.string().describe("The name of the winner."),
  final_match_score: z.string().describe("The final score."),
  scorers: z.array(z.string()).describe("The name of the scorer.")
});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: "Search for all details for the latest Euro.",
    config: {
      tools: [
        { googleSearch: {} },
        { urlContext: {} }
      ],
      responseMimeType: "application/json",
      responseJsonSchema: zodToJsonSchema(matchSchema),
    },
  });

  const match = matchSchema.parse(JSON.parse(response.text));
  console.log(match);
}

run();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Search for all details for the latest Euro."}]
    }],
    "tools": [
      {"googleSearch": {}},
      {"urlContext": {}}
    ],
    "generationConfig": {
        "responseMimeType": "application/json",
        "responseJsonSchema": {
            "type": "object",
            "properties": {
                "winner": {"type": "string", "description": "The name of the winner."},
                "final_match_score": {"type": "string", "description": "The final score."},
                "scorers": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "The name of the scorer."
                }
            },
            "required": ["winner", "final_match_score", "scorers"]
        }
    }
  }'

Migrazione da Gemini 2.5

Gemini 3 è la nostra famiglia di modelli più avanzata finora e offre un miglioramento graduale rispetto a Gemini 2.5 Pro. Quando esegui la migrazione, tieni presente quanto segue:

• Pensiero:se in precedenza utilizzavi tecniche di ingegneria dei prompt complesse (come Chain-of-thought) per forzare Gemini 2.5 a ragionare, prova Gemini 3 con thinking_level: "high" e prompt semplificati.
• Impostazioni della temperatura:se il codice esistente imposta esplicitamente la temperatura (soprattutto su valori bassi per output deterministici), ti consigliamo di rimuovere questo parametro e di utilizzare il valore predefinito di Gemini 3 pari a 1.0 per evitare potenziali problemi di loop o un calo delle prestazioni per attività complesse.
• Comprensione di PDF e documenti:la risoluzione OCR predefinita per i PDF è cambiata. Se ti affidi a un comportamento specifico per l'analisi dei documenti densi, testa la nuova impostazione media_resolution_high per garantire una precisione continua.
• Utilizzo dei token:la migrazione alle impostazioni predefinite di Gemini 3 Pro potrebbe aumentare l'utilizzo dei token per i PDF, ma diminuirlo per i video. Se le richieste ora superano la finestra contestuale a causa delle risoluzioni predefinite più elevate, ti consigliamo di ridurre esplicitamente la risoluzione dei contenuti multimediali.
• Segmentazione delle immagini:le funzionalità di segmentazione delle immagini (restituzione di maschere a livello di pixel per gli oggetti) non sono supportate in Gemini 3 Pro. Per i carichi di lavoro che richiedono la segmentazione nativa delle immagini, ti consigliamo di continuare a utilizzare Gemini 2.5 Flash con la funzionalità di pensiero disattivata o Gemini Robotics-ER 1.5.

Compatibilità con OpenAI

Per gli utenti che utilizzano il livello di compatibilità OpenAI, i parametri standard vengono mappati automaticamente agli equivalenti di Gemini:

• reasoning_effort (OAI) corrisponde a thinking_level (Gemini). Tieni presente che la qualità reasoning_effort media corrisponde alla qualità thinking_level alta.

Best practice per la creazione di prompt

Gemini 3 è un modello di ragionamento che cambia il modo in cui devi creare i prompt.

• Istruzioni precise: sii conciso nei prompt di input. Gemini 3 risponde al meglio a istruzioni dirette e chiare. Potrebbe analizzare in modo eccessivo tecniche di prompt engineering complesse o prolisse utilizzate per i modelli precedenti.
• Livello di dettaglio dell'output:per impostazione predefinita, Gemini 3 è meno prolisso e preferisce fornire risposte dirette ed efficienti. Se il tuo caso d'uso richiede una persona più colloquiale o "loquace", devi indirizzare esplicitamente il modello nel prompt (ad es. "Spiega questo testo come se fossi un assistente cordiale e loquace".
• Gestione del contesto:quando lavori con set di dati di grandi dimensioni (ad es. libri interi, codebase o video lunghi), inserisci le istruzioni o le domande specifiche alla fine del prompt, dopo il contesto dei dati. Ancora il ragionamento del modello ai dati forniti iniziando la domanda con una frase come "In base alle informazioni riportate sopra…".

Scopri di più sulle strategie di progettazione dei prompt nella guida all'ingegneria dei prompt.

Domande frequenti

1. Qual è la data limite delle conoscenze per Gemini 3 Pro? Gemini 3 ha un limite di conoscenza di gennaio 2025. Per informazioni più recenti, utilizza lo strumento Ricerca basata su dati reali.

2. Quali sono i limiti della finestra contestuale? Gemini 3 Pro supporta una finestra contestuale di input di 1 milione di token e fino a 64.000 token di output.

3. Esiste un livello senza costi per Gemini 3 Pro? Puoi provare il modello senza costi in Google AI Studio, ma al momento non è disponibile alcun livello senza costi per gemini-3-pro-preview nell'API Gemini.

4. Il mio vecchio codice thinking_budget continuerà a funzionare? Sì, thinking_budget è ancora supportato per la compatibilità con le versioni precedenti, ma ti consigliamo di eseguire la migrazione a thinking_level per un rendimento più prevedibile. Non utilizzarli entrambi nella stessa richiesta.

5. Gemini 3 supporta l'API Batch? Sì, Gemini 3 supporta l'API Batch.

6. La memorizzazione nella cache del contesto è supportata? Sì, la memorizzazione nella cache del contesto è supportata per Gemini 3. Il numero minimo di token richiesto per avviare la memorizzazione nella cache è 2048 token.

7. Quali strumenti sono supportati in Gemini 3? Gemini 3 supporta la Ricerca Google, la Ricerca file, l'esecuzione di codice e il contesto URL. Supporta anche la chiamata di funzioni standard per i tuoi strumenti personalizzati. Tieni presente che Google Maps e Utilizzo del computer non sono attualmente supportati.

Passaggi successivi

• Inizia a utilizzare il Gemini 3 Cookbook
• Consulta la guida dedicata del Cookbook sui livelli di pensiero e su come eseguire la migrazione dal budget di pensiero ai livelli di pensiero.