Guida per gli sviluppatori di Gemini 3

Gemini 3 è la nostra famiglia di modelli più intelligente di sempre, basata su una base di ragionamento all'avanguardia. È progettata per dare vita a qualsiasi idea grazie a workflow agentici, codifica autonoma e attività multimodali complesse. Questa guida illustra le funzionalità principali della famiglia di modelli Gemini 3 e come sfruttarla al meglio.

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

Inizia con poche righe di codice:

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-pro-preview",
    input="Find the race condition in this multi-threaded C++ snippet: [code here]",
)

print(interaction.steps[-1].content[0].text)

JavaScript

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

const client = new GoogleGenAI({});

async function run() {
  const interaction = await client.interactions.create({
    model: "gemini-3.1-pro-preview",
    input: "Find the race condition in this multi-threaded C++ snippet: [code here]",
  });

  console.log(interaction.steps.at(-1).content[0].text);
}

run();

REST

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.1-pro-preview",
    "input": "Find the race condition in this multi-threaded C++ snippet: [code here]"
  }'

Scopri la serie Gemini 3

Gemini 3.1 Pro è ideale per le attività complesse che richiedono una vasta conoscenza del mondo e un ragionamento avanzato tra le modalità.

Gemini 3 Flash è il nostro ultimo modello della serie 3, con un'intelligenza di livello Pro alla velocità e al prezzo di Flash.

Nano Banana Pro (noto anche come Gemini 3 Pro Image) è il nostro modello di generazione di immagini di massima qualità, mentre Nano Banana 2 (noto anche come Gemini 3.1 Flash Image) è l'equivalente ad alto volume, ad alta efficienza e a un prezzo inferiore.

Gemini 3.1 Flash-Lite è il nostro modello di riferimento, progettato per l'efficienza in termini di costi e per le attività ad alto volume.

Tutti i modelli Gemini 3 sono attualmente in anteprima.

ID modello Finestra contestuale (input / output) Knowledge cutoff Prezzi (input / output)*
gemini-3.1-flash-lite-preview 1M / 64k Gennaio 2025 0,25 $ (testo, immagine, video), 0,50 $ (audio) / 1,50 $
gemini-3.1-flash-image-preview 128k / 32k Gennaio 2025 0,25 $ (input di testo) / 0,067 $ (output di immagini)**
gemini-3.1-pro-preview 1M / 64k Gennaio 2025 2 $ / 12 $ (<200k token)
4 $ / 18 $ (>200k token)
gemini-3-flash-preview 1M / 64k Gennaio 2025 0,50 $ / 3 $
gemini-3-pro-image-preview 65k / 32k Gennaio 2025 2 $ (input di testo) / 0,134 $ (output di immagini)**

* Salvo dove diversamente indicato, i prezzi si riferiscono a 1 milione di token. ** I prezzi delle immagini variano in base alla risoluzione. Per maggiori dettagli, consulta la pagina dei prezzi.

Per limiti, prezzi e informazioni aggiuntive dettagliati, 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 ragionamento

Per impostazione predefinita, i modelli della serie Gemini 3 utilizzano il ragionamento dinamico per analizzare i prompt. Puoi utilizzare il parametro thinking_level, che controlla la profondità massima del processo di ragionamento interno del modello prima che produca una risposta. Gemini 3 considera questi livelli come quote relative per il ragionamento anziché garanzie di token rigorose.

Se thinking_level non è specificato, Gemini 3 utilizzerà per impostazione predefinita high. Per risposte più rapide e a bassa latenza quando non è richiesto un ragionamento complesso, puoi limitare il livello di ragionamento del modello a low.

Livello di ragionamento Gemini 3.1 Pro Gemini 3.1 Flash-Lite Gemini 3 Flash Descrizione
minimal Non supportato Supportato (valore predefinito) Supportato Corrisponde all'impostazione "nessun ragionamento" per la maggior parte delle query. Il modello potrebbe ragionare in modo molto limitato per le attività di codifica complesse. Riduce al minimo la latenza per le applicazioni di chat o con throughput elevato. Tieni presente che minimal non garantisce che il ragionamento sia disattivato.
low Supportato Supportato Supportato Riduce al minimo la latenza e i costi. Ideale per l'esecuzione di istruzioni semplici, la chat o le applicazioni ad alta velocità effettiva.
medium Supportato Supportato Supportato Ragionamento bilanciato per la maggior parte delle attività.
high Supportato (valore predefinito, dinamico) Supportato (dinamico) Supportato (valore predefinito, dinamico) Massimizza la profondità del ragionamento. Il modello potrebbe impiegare molto più tempo per raggiungere un primo token di output (senza ragionamento), ma l'output sarà più accurato.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-pro-preview",
    input="How does AI work?",
    generation_config={"thinking_level": "low"},
)

print(interaction.steps[-1].content[0].text)

JavaScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.1-pro-preview",
    input: "How does AI work?",
    generation_config: {
      thinking_level: "low",
    },
  });

console.log(interaction.steps.at(-1).content[0].text);

REST

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.1-pro-preview",
    "input": "How does AI work?",
    "generation_config": {
      "thinking_level": "low"
    }
  }'

Temperatura

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

Mentre i modelli precedenti spesso beneficiavano della 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 loop o prestazioni ridotte, in particolare nelle attività di ragionamento o matematiche complesse.

Firme di ragionamento

I modelli Gemini 3 utilizzano le firme di ragionamento per mantenere il contesto di ragionamento tra le chiamate API. Queste firme sono rappresentazioni criptate del processo di ragionamento interno del modello.

  • Modalità con stato (consigliata): quando utilizzi l'API Interactions in modalità con stato (fornendo previous_interaction_id), il server gestisce automaticamente la cronologia delle conversazioni e le firme di ragionamento.
  • Modalità senza stato: se gestisci manualmente la cronologia delle conversazioni, devi includere i blocchi di ragionamento con le relative firme nelle richieste successive per convalidarne l'autenticità.

Per informazioni dettagliate, consulta la pagina Firme di ragionamento.

Output strutturati con gli strumenti

I modelli Gemini 3 ti consentono di combinare gli output strutturati con gli strumenti integrati, tra cui Grounding con la Ricerca Google, Contesto URL, Esecuzione del codice e Chiamata di funzione.

Python

from google import genai
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()

interaction = client.interactions.create(
    model="gemini-3.1-pro-preview",
    input="Search for all details for the latest Euro.",
    tools=[
        {"type": "google_search"},
        {"type": "url_context"}
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": MatchResult.model_json_schema()
    },
)

result = MatchResult.model_validate_json(interaction.steps[-1].content[0].text)
print(result)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as z from "zod";

const matchJsonSchema = {
  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"]
};

const matchSchema = z.fromJSONSchema(matchJsonSchema);

const client = new GoogleGenAI({});

async function run() {
  const interaction = await client.interactions.create({
    model: "gemini-3.1-pro-preview",
    input: "Search for all details for the latest Euro.",
    tools: [
      { type: "google_search" },
      { type: "url_context" }
    ],
    response_format: {
        type: "text",
        mime_type: "application/json",
        schema: matchJsonSchema
    },
  });

  const match = matchSchema.parse(JSON.parse(interaction.steps.at(-1).content[0].text));
  console.log(match);
}

run();

REST

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.1-pro-preview",
    "input": "Search for all details for the latest Euro.",
    "tools": [
      {"type": "google_search"},
      {"type": "url_context"}
    ],
    "response_format": {
        "type": "text",
        "mime_type": "application/json",
        "schema": {
            "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"]
        }
    }
  }'

Generazione di immagini

Gemini 3.1 Flash Image e Gemini 3 Pro Image ti consentono di generare e modificare immagini da prompt di testo. Utilizza il ragionamento per "pensare" a un prompt e può recuperare dati in tempo reale, come previsioni del meteo o grafici azionari, prima di utilizzare il grounding della Ricerca Google per generare immagini ad alta fedeltà.

Funzionalità nuove e migliorate:

  • Rendering di testo e 4K:genera testo e diagrammi nitidi e leggibili con risoluzioni fino a 2K e 4K.
  • Generazione basata su grounding:utilizza lo strumento google_search per verificare i fatti e generare immagini basate su informazioni del mondo reale. Grounding con la Ricerca immagini Google disponibile per Gemini 3.1 Flash Image.
  • Modifica conversazionale:modifica le immagini in più passaggi semplicemente chiedendo le modifiche (ad es. "Rendi lo sfondo un tramonto"). Questo workflow si basa sulle firme di ragionamento per preservare il contesto visivo tra i turni.

Per dettagli completi su proporzioni, workflow di modifica e opzioni di configurazione , consulta la guida alla generazione di immagini.

Python

from google import genai
import base64

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-pro-image-preview",
    input="Generate an infographic of the current weather in Tokyo.",
    tools=[{"type": "google_search"}],
    response_format={
        "type": "image",
        "aspect_ratio": "16:9",
        "image_size": "4K"
    }
)

from PIL import Image
import io

image_blocks = [content_block for content_block in interaction.steps[-1].content if content_block.type == "image"]
if image_blocks:
    image_data = base64.b64decode(image_blocks[0].data)
    image = Image.open(io.BytesIO(image_data))
    image.save('weather_tokyo.png')
    image.show()

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const client = new GoogleGenAI({});

async function run() {
  const interaction = await client.interactions.create({
    model: "gemini-3-pro-image-preview",
    input: "Generate a visualization of the current weather in Tokyo.",
    tools: [{ type: "google_search" }],
    response_format: {
      type: "image",
      aspect_ratio: "16:9",
      image_size: "4K"
    }
  });

  for (const contentBlock of interaction.steps.at(-1).content) {
    if (contentBlock.type === "image") {
      const buffer = Buffer.from(contentBlock.data, "base64");
      fs.writeFileSync("weather_tokyo.png", buffer);
    }
  }
}

run();

REST

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-pro-image-preview",
    "input": "Generate a visualization of the current weather in Tokyo.",
    "tools": [{"type": "google_search"}],
    "response_format": {
        "type": "image",
        "aspect_ratio": "16:9",
        "image_size": "4K"
    }
  }'

Risposta di esempio

Meteo Tokyo

Esecuzione del codice con le immagini

Gemini 3 Flash può trattare la visione come un'indagine attiva, non solo come uno sguardo statico. Combinando il ragionamento con l'esecuzione del codice, il modello formula un piano, quindi scrive ed esegue codice Python per ingrandire, ritagliare, annotare o manipolare in altro modo le immagini passo dopo passo per basare visivamente le risposte.

Casi d'uso:

  • Zoom e ispeziona:il modello rileva implicitamente quando i dettagli sono troppo piccoli (ad es. la lettura di un indicatore o di un numero di serie distanti) e scrive codice per ritagliare e riesaminare l'area a una risoluzione più alta.
  • Matematica e tracciamento visivi:il modello può eseguire calcoli in più passaggi utilizzando il codice (ad es. la somma delle voci di un documento o la generazione di un grafico Matplotlib dai dati estratti).
  • Annotazione delle immagini:il modello può disegnare frecce, riquadri di delimitazione o altre annotazioni direttamente sulle immagini per rispondere a domande spaziali come "Dove deve andare questo articolo?".

Per attivare il ragionamento visivo, configura l'esecuzione del codice come strumento. Il modello utilizzerà automaticamente il codice per manipolare le immagini, se necessario.

Python

from google import genai
from google.genai import types
import requests
from PIL import Image
import io
import base64

image_path = "https://goo.gle/instrument-img"
image_bytes = requests.get(image_path).content
image = types.Part.from_bytes(data=image_bytes, mime_type="image/jpeg")

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        image,
        "Zoom into the expression pedals and tell me how many pedals are there?"
    ],
    tools=[{"type": "code_execution"}],
)

from IPython.display import display
from PIL import Image
import io

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
            elif content_block.type == "image":
                 display(Image.open(io.BytesIO(base64.b64decode(content_block.data))))
    elif step.type == "code_execution_call":
        print(step.code)
    elif step.type == "code_execution_result":
        print(step.output)

JavaScript

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

const client = new GoogleGenAI({});

async function main() {
  const imageUrl = "https://goo.gle/instrument-img";
  const response = await fetch(imageUrl);
  const imageArrayBuffer = await response.arrayBuffer();
  const base64ImageData = Buffer.from(imageArrayBuffer).toString("base64");

  const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: [
      {
        type: "image",
        mime_type: "image/jpeg",
        data: base64ImageData,
      },
      {
        type: "text",
        text: "Zoom into the expression pedals and tell me how many pedals are there?",
      },
    ],
    tools: [{ type: "code_execution" }],
  });

  for (const step of interaction.steps) {
    if (step.type === "model_output") {
      for (const contentBlock of step.content) {
        if (contentBlock.type === "text") {
          console.log("Text:", contentBlock.text);
        }
      }
    } else if (step.type === "code_execution_call") {
      console.log("Code:", step.code);
    } else if (step.type === "code_execution_result") {
      console.log("Output:", step.output);
    }
  }
}

main();

REST

IMG_URL="https://goo.gle/instrument-img"
MODEL="gemini-3-flash-preview"

MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)
if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then
  MIME_TYPE="image/jpeg"
fi

if [[ "$(uname)" == "Darwin" ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -b 0)
elif [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64)
else
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -w0)
fi

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "'$MODEL'",
      "input": [
            {
              "type": "image",
              "mime_type":"'"$MIME_TYPE"'",
              "data": "'"$IMAGE_B64"'"
            },
            {"type": "text", "text": "Zoom into the expression pedals and tell me how many pedals are there?"}
      ],
      "tools": [{"type": "code_execution"}]
    }'

Per maggiori dettagli sull'esecuzione del codice con le immagini, consulta Esecuzione del codice.

Risposte di funzione multimodali

La chiamata di funzione multimodale consente agli utenti di avere risposte di funzione contenenti oggetti multimodali, migliorando l'utilizzo delle funzionalità di chiamata di funzione del modello. La chiamata di funzione standard supporta solo le risposte di funzione basate su testo:

Python 

from google import genai
import requests
import base64

client = genai.Client()

# 1. Define the tool
get_image_tool = {
    "type": "function",
    "name": "get_image",
    "description": "Retrieves the image file reference for a specific order item.",
    "parameters": {
        "type": "object",
        "properties": {
            "item_name": {
                "type": "string",
                "description": "The name or description of the item ordered (e.g., 'instrument')."
            }
        },
        "required": ["item_name"],
    },
}

# 2. Send the request with tools
interaction_1 = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Show me the instrument I ordered last month.",
    tools=[get_image_tool],
)

# 3. Find the function call step
fc_step = next(s for s in interaction_1.steps if s.type == "function_call")
print(f"Tool Call: {fc_step.name}({fc_step.arguments})")

# Execute tool (fetch image)
image_path = "https://goo.gle/instrument-img"
image_bytes = requests.get(image_path).content
image_b64 = base64.b64encode(image_bytes).decode("utf-8")

# 4. Send multimodal function result back
interaction_2 = client.interactions.create(
    model="gemini-3-flash-preview",
    previous_interaction_id=interaction_1.id,
    input=[{
        "type": "function_result",
        "name": fc_step.name,
        "call_id": fc_step.id,
        "result": [
            {"type": "text", "text": "instrument.jpg"},
            {
                "type": "image",
                "mime_type": "image/jpeg",
                "data": image_b64,
            }
        ]
    }],
    tools=[get_image_tool]
)

model_output_step = next(s for s in interaction_2.steps if s.type == "model_output")
print(f"\nFinal model response: {model_output_step.content[0].text}")

JavaScript 

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

const client = new GoogleGenAI({});

// 1. Define the tool
const getImageTool = {
    type: 'function',
    name: 'get_image',
    description: 'Retrieves the image file reference for a specific order item.',
    parameters: {
        type: 'object',
        properties: {
            item_name: {
                type: 'string',
                description: "The name or description of the item ordered (e.g., 'instrument').",
            },
        },
        required: ['item_name'],
    },
};

// 2. Send the request with tools
const interaction1 = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Use the get_image tool to show me the instrument I ordered last month.',
    tools: [getImageTool],
});

// 3. Find the function call step
const fcStep = interaction1.steps.find(s => s.type === 'function_call');
console.log(`Tool Call: ${fcStep.name}(${JSON.stringify(fcStep.arguments)})`);

// Execute tool (fetch image)
const imageUrl = 'https://goo.gle/instrument-img';
const response = await fetch(imageUrl);
const imageArrayBuffer = await response.arrayBuffer();
const base64ImageData = Buffer.from(imageArrayBuffer).toString('base64');

// 4. Send multimodal function result back
const interaction2 = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    previous_interaction_id: interaction1.id,
    input: [{
        type: 'function_result',
        name: fcStep.name,
        call_id: fcStep.id,
        result: [
            { type: 'text', text: 'instrument.jpg' },
            {
                type: 'image',
                mime_type: 'image/jpeg',
                data: base64ImageData,
            }
        ]
    }],
    tools: [getImageTool]
});

console.log(`\nFinal model response: ${interaction2.steps.at(-1).content[0].text}`);

REST 

IMG_URL="https://goo.gle/instrument-img"

MIME_TYPE=$(curl -sIL "$IMG_URL" | grep -i '^content-type:' | awk -F ': ' '{print $2}' | sed 's/\r$//' | head -n 1)
if [[ -z "$MIME_TYPE" || ! "$MIME_TYPE" == image/* ]]; then
  MIME_TYPE="image/jpeg"
fi

# Check for macOS
if [[ "$(uname)" == "Darwin" ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -b 0)
elif [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64)
else
  IMAGE_B64=$(curl -sL "$IMG_URL" | base64 -w0)
fi

# 1. First interaction (triggers function call)
# 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-flash-preview", "input": "Show me the instrument I ordered last month.", "tools": [...] }'

# 2. Send multimodal function result back (Replace INTERACTION_ID and CALL_ID)
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-flash-preview",
    "previous_interaction_id": "INTERACTION_ID",
    "input": [{
      "type": "function_result",
      "name": "get_image",
      "call_id": "CALL_ID",
      "result": [
        { "type": "text", "text": "instrument.jpg" },
        {
          "type": "image",
          "mime_type": "'"$MIME_TYPE"'",
          "data": "'"$IMAGE_B64"'"
        }
      ]
    }]
  }'

Combinare strumenti integrati e chiamata di funzione

Gemini 3 consente di utilizzare gli strumenti integrati (come la Ricerca Google, il contesto URL e altro) e gli strumenti di chiamata di funzione personalizzati nella stessa chiamata API, consentendo workflow più complessi.

Python

from google import genai
from google.genai import types

client = genai.Client()

getWeather = {
    "type": "function",
    "name": "getWeather",
    "description": "Gets the weather for a requested city.",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "The city and state, e.g. Utqiaġvik, Alaska",
            },
        },
        "required": ["city"],
    },
}

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is the northernmost city in the United States? What's the weather like there today?",
    tools=[
        {"type": "google_search"},
        getWeather
    ],
)

# Find the function call step
fc_step = next((s for s in interaction.steps if s.type == "function_call"), None)

if fc_step:
    # Simulate a function result
    result = {"response": "Very cold. 22 degrees Fahrenheit."}

    final_interaction = client.interactions.create(
        model="gemini-3-flash-preview",
        input=[
            {"type": "function_result", "name": fc_step.name, "call_id": fc_step.id, "result": result}
        ],
        tools=[
            {"type": "google_search"},
            getWeather
        ],
        previous_interaction_id=interaction.id,
    )

    print(final_interaction.steps[-1].content[0].text)

JavaScript

import { GoogleGenAI, Type } from '@google/genai';

const client = new GoogleGenAI({});

const getWeatherDeclaration = {
  type: 'function',
  name: 'getWeather',
  description: 'Gets the weather for a requested city.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      city: {
        type: Type.STRING,
        description: 'The city and state, e.g. Utqiaġvik, Alaska',
      },
    },
    required: ['city'],
  },
};

const interaction = await client.interactions.create({
  model: 'gemini-3-flash-preview',
  input: "What is the northernmost city in the United States? What's the weather like there today?",
  tools: [
    { type: "google_search" },
    getWeatherDeclaration
  ],
});

// Find the function call step
const fcStep = interaction.steps.find(s => s.type === 'function_call');

if (fcStep) {
  const result = { response: "Very cold. 22 degrees Fahrenheit." };

  const finalInteraction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: [
      { type: 'function_result', name: fcStep.name, call_id: fcStep.id, result: result }
    ],
    tools: [
      { type: "google_search" },
      getWeatherDeclaration
    ],
    previous_interaction_id: interaction.id,
  });

  console.log(finalInteraction.steps.at(-1).content[0].text);
}

Migrazione da Gemini 2.5

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

  • Ragionamento:se in precedenza utilizzavi tecniche di progettazione di prompt complesse (ad es. la catena di pensiero) per forzare il ragionamento di Gemini 2.5, prova Gemini 3 con thinking_level: "high" e prompt semplificati.
  • Impostazioni della temperatura:se il codice esistente imposta esplicitamente la temperatura (in particolare su valori bassi per gli output deterministici), ti consigliamo di rimuovere questo parametro e di utilizzare il valore predefinito di Gemini 3, ovvero 1.0, per evitare potenziali problemi di loop o un peggioramento del rendimento nelle attività complesse.
  • Comprensione di PDF e documenti:se ti affidi a un comportamento specifico per l'analisi di documenti densi, testa la nuova impostazione media_resolution_high per garantire la continuità dell'accuratezza.
  • Consumo di token:la migrazione alle impostazioni predefinite di Gemini 3 potrebbe aumentare l'utilizzo di token per i PDF, ma ridurlo per i video. Se le richieste ora superano la finestra contestuale a causa di risoluzioni predefinite più elevate, ti consigliamo di ridurre esplicitamente la risoluzione dei contenuti multimediali.
  • Segmentazione delle immagini:le funzionalità di segmentazione delle immagini (che restituiscono maschere a livello di pixel per gli oggetti) non sono supportate in Gemini 3 Pro o Gemini 3 Flash. Per i workload che richiedono la segmentazione delle immagini integrata, ti consigliamo di continuare a utilizzare Gemini 2.5 Flash con il ragionamento disattivato o Gemini Robotics-ER 1.6.
  • Utilizzo del computer: Gemini 3 Pro e Gemini 3 Flash supportano l'utilizzo del computer. A differenza della serie 2.5, non devi utilizzare un modello separato per accedere allo strumento Utilizzo del computer.
  • Supporto degli strumenti: la combinazione di strumenti integrati e chiamata di funzione è ora supportata per i modelli Gemini 3. Anche il grounding di Maps è ora supportato per i modelli Gemini 3 .

Compatibilità con OpenAI

Per gli utenti che utilizzano il livello di compatibilità con OpenAI, i parametri standard (il parametro reasoning_effort di OpenAI) vengono mappati automaticamente agli equivalenti di Gemini (thinking_level).

Best practice per la creazione di prompt

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

  • Istruzioni precise:usa prompt di input concisi. Gemini 3 risponde meglio a istruzioni dirette e chiare. Potrebbe analizzare eccessivamente le tecniche di progettazione di prompt verbose o eccessivamente complesse utilizzate per i modelli precedenti.
  • Verbosità dell'output:per impostazione predefinita, Gemini 3 è meno verboso e preferisce fornire risposte dirette ed efficienti. Se il tuo caso d'uso richiede una persona più conversazionale o "loquace", devi indirizzare esplicitamente il modello nel prompt (ad es. "Spiega questo come un assistente amichevole 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 precedenti...".

Scopri di più sulle strategie di progettazione dei prompt nella guida alla progettazione dei prompt.

Domande frequenti

  1. Qual è il knowledge cutoff per Gemini 3? I modelli Gemini 3 hanno un knowledge cutoff di gennaio 2025. Per informazioni più recenti, utilizza lo strumento Grounding della Ricerca.

  2. Quali sono i limiti della finestra contestuale? I modelli Gemini 3 supportano 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? Gemini 3 Flash gemini-3-flash-preview ha un livello senza costi nell'API Gemini. Puoi provare Gemini 3.1 Pro e 3 Flash senza costi in Google AI Studio, ma non è disponibile alcun livello senza costi per gemini-3.1-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 utilizzare 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.

  7. Quali strumenti sono supportati in Gemini 3? Gemini 3 supporta la Ricerca Google, il grounding con Google Maps, la Ricerca file, l'esecuzione del codice e il contesto URL. Supporta anche la chiamata di funzione standard per i tuoi strumenti personalizzati e in combinazione con gli strumenti integrati.

  8. Che cos'è gemini-3.1-pro-preview-customtools? Se utilizzi gemini-3.1-pro-preview e il modello ignora i tuoi strumenti personalizzati a favore di comandi bash, prova invece il modello gemini-3.1-pro-preview-customtools. Ulteriori informazioni [qui][customtools-model].