Guia para desenvolvedores do Gemini 3

O Gemini 3 é nossa família de modelos mais inteligente até o momento, criada com base em um raciocínio de última geração. Ele foi projetado para dar vida a qualquer ideia, dominando fluxos de trabalho agênticos, programação autônoma e tarefas multimodais complexas. Este guia aborda os principais recursos da família de modelos Gemini 3 e como aproveitar ao máximo.

Pensamento dinâmico/alto Pensamento baixo

O Gemini 3 Pro usa o pensamento dinâmico por padrão para analisar os comandos. Para respostas mais rápidas e com menor latência quando não é necessário um raciocínio complexo, você pode restringir o nível de pensamento do modelo 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]"}]
    }]
  }'

Explorar

Confira nossa coleção de apps do Gemini 3 para saber como o modelo lida com raciocínio avançado, programação autônoma e tarefas multimodais complexas.

Conheça o Gemini 3

O Gemini 3 Pro é o primeiro modelo da nova série. O gemini-3-pro-preview é a melhor opção para tarefas complexas que exigem conhecimento amplo do mundo e raciocínio avançado em várias modalidades.

* O preço é por 1 milhão de tokens. Os preços listados são para texto padrão. As taxas de entrada multimodal podem variar.

Para limites de taxa detalhados, preços em lote e outras informações, consulte a página de modelos.

Novos recursos da API no Gemini 3

O Gemini 3 apresenta novos parâmetros projetados para dar aos desenvolvedores mais controle sobre latência, custo e fidelidade multimodal.

Nível de pensamento

O parâmetro thinking_level controla a profundidade máxima do processo de raciocínio interno do modelo antes de gerar uma resposta. O Gemini 3 trata esses níveis como permissões relativas para pensar, e não como garantias estritas de token. Se thinking_level não for especificado, o Gemini 3 Pro vai usar high como padrão.

• low: minimiza a latência e o custo. Ideal para seguir instruções simples, conversar ou aplicativos de alta capacidade de processamento
• medium: (em breve), não disponível no lançamento
• high (padrão): maximiza a profundidade do raciocínio. O modelo pode levar muito mais tempo para alcançar um primeiro token, mas a saída será mais bem fundamentada.

Resolução da mídia

O Gemini 3 apresenta controle granular sobre o processamento de visão multimodal usando o parâmetro media_resolution. Resoluções mais altas melhoram a capacidade do modelo de ler textos pequenos ou identificar detalhes pequenos, mas aumentam o uso de tokens e a latência. O parâmetro media_resolution determina o número máximo de tokens alocados por imagem de entrada ou frame de vídeo.

Agora é possível definir a resolução como media_resolution_low, media_resolution_medium ou media_resolution_high por parte de mídia individual ou globalmente (via generation_config). Se não for especificado, o modelo usará padrões ideais com base no tipo de mídia.

Configurações recomendadas

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

Para o Gemini 3, recomendamos manter o parâmetro de temperatura no valor padrão de 1.0.

Embora os modelos anteriores geralmente se beneficiassem do ajuste da temperatura para controlar a criatividade em relação ao determinismo, as capacidades de raciocínio do Gemini 3 são otimizadas para a configuração padrão. Mudar a temperatura (definindo-a abaixo de 1,0) pode levar a um comportamento inesperado, como looping ou desempenho degradado, principalmente em tarefas matemáticas ou de raciocínio complexas.

Assinaturas de pensamento

O Gemini 3 usa assinaturas de pensamento para manter o contexto de raciocínio em todas as chamadas de API. Essas assinaturas são representações criptografadas do processo de raciocínio interno do modelo. Para garantir que o modelo mantenha as capacidades de raciocínio, retorne essas assinaturas ao modelo na sua solicitação exatamente como foram recebidas:

• Chamada de função (estrita): a API aplica validação estrita na "rodada atual". A falta de assinaturas vai resultar em um erro 400.
• Texto/Chat:a validação não é estritamente aplicada, mas omitir assinaturas vai prejudicar o raciocínio do modelo e a qualidade da resposta.

Chamada de função (validação estrita)

Quando o Gemini gera um functionCall, ele depende do thoughtSignature para processar a saída da ferramenta corretamente na próxima vez. O "Turno atual" inclui todas as etapas do modelo (functionCall) e do usuário (functionResponse) que ocorreram desde a última mensagem padrão Usuário text.

• Chamada de função única:a parte functionCall contém uma assinatura. Você precisa devolver o dispositivo.
• Chamadas de função paralelas:apenas a primeira parte functionCall na lista vai conter a assinatura. Devolva as peças na ordem exata em que foram recebidas.
• Várias etapas (sequencial): se o modelo chamar uma ferramenta, receber um resultado e chamar outra ferramenta (na mesma vez), ambas as chamadas de função terão assinaturas. Você precisa retornar todas as assinaturas acumuladas no histórico.

Texto e streaming

Para conversas padrão ou geração de texto, a presença de uma assinatura não é garantida.

• Não streaming: a parte final do conteúdo da resposta pode conter um thoughtSignature, embora nem sempre esteja presente. Se um for retornado, envie-o de volta para manter o melhor desempenho.
• Streaming: se uma assinatura for gerada, ela poderá chegar em um bloco final que contém uma parte de texto vazia. Verifique se o analisador de fluxo procura assinaturas mesmo que o campo de texto esteja vazio.

Exemplos de código

// 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." }] 
  }
]

Migração de outros modelos

Se você estiver transferindo um rastreamento de conversa de outro modelo (por exemplo, Gemini 2.5) ou injetar uma chamada de função personalizada que não foi gerada pelo Gemini 3, você não terá uma assinatura válida.

Para ignorar a validação estrita nesses cenários específicos, preencha o campo com esta string fictícia específica: "thoughtSignature": "context_engineering_is_the_way_to_go"

Saídas estruturadas com ferramentas

Com o Gemini 3, é possível combinar saídas estruturadas com ferramentas integradas, incluindo fundamentação com a Pesquisa Google, contexto de URL e execução de código.

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"]
        }
    }
  }'

Migrar do Gemini 2.5

O Gemini 3 é nossa família de modelos mais avançada até o momento e oferece uma melhoria gradual em relação ao Gemini 2.5 Pro. Ao migrar, considere o seguinte:

• Pensamento:se você usava engenharia de comandos complexa (como cadeia de pensamento) para forçar o Gemini 2.5 a raciocinar, teste o Gemini 3 com thinking_level: "high" e comandos simplificados.
• Configurações de temperatura:se o código atual definir explicitamente a temperatura (principalmente para valores baixos em saídas determinísticas), recomendamos remover esse parâmetro e usar o padrão do Gemini 3 de 1,0 para evitar possíveis problemas de loop ou degradação de desempenho em tarefas complexas.
• Compreensão de documentos e PDFs:a resolução padrão de OCR para PDFs mudou. Se você dependia de um comportamento específico para a análise de documentos densos, teste a nova configuração media_resolution_high para garantir a precisão contínua.
• Consumo de tokens:a migração para os padrões do Gemini 3 Pro pode aumentar o uso de tokens para PDFs, mas diminuir o uso de tokens para vídeos. Se as solicitações excederem a janela de contexto devido a resoluções padrão mais altas, recomendamos reduzir explicitamente a resolução da mídia.
• Segmentação de imagens:os recursos de segmentação de imagens (retorno de máscaras no nível do pixel para objetos) não são compatíveis com o Gemini 3 Pro. Para cargas de trabalho que exigem segmentação de imagem nativa, recomendamos continuar usando o Gemini 2.5 Flash com o modo de pensamento desativado ou o Gemini Robotics-ER 1.5.

Compatibilidade com a OpenAI

Para usuários que utilizam a camada de compatibilidade do OpenAI, os parâmetros padrão são mapeados automaticamente para equivalentes do Gemini:

• reasoning_effort (OAI) é mapeado para thinking_level (Gemini). Observe que o meio reasoning_effort é mapeado para o alto thinking_level.

Práticas recomendadas para a solicitação

O Gemini 3 é um modelo de raciocínio, o que muda a forma como você precisa dar comandos.

• Instruções precisas:seja conciso nos comandos de entrada. O Gemini 3 responde melhor a instruções diretas e claras. Ela pode analisar demais técnicas de engenharia de comandos detalhadas ou complexas usadas em modelos mais antigos.
• Nível de detalhe da saída:por padrão, o Gemini 3 é menos detalhista e prefere fornecer respostas diretas e eficientes. Se o caso de uso exigir uma persona mais conversacional ou "falante", você precisará direcionar explicitamente o modelo no comando (por exemplo, "Explique isso como um assistente simpático e falante").
• Gerenciamento de contexto:ao trabalhar com conjuntos de dados grandes (por exemplo, livros inteiros, bases de código ou vídeos longos), coloque suas instruções ou perguntas específicas no final do comando, depois do contexto dos dados. Ancore o raciocínio do modelo nos dados fornecidos começando sua pergunta com uma frase como "Com base nas informações acima...".

Saiba mais sobre estratégias de design de comandos no guia de engenharia de comandos.

Perguntas frequentes

1. Qual é o corte de conhecimento do Gemini 3 Pro? O Gemini 3 tem um corte de conhecimento de janeiro de 2025. Para informações mais recentes, use a ferramenta Embasamento da pesquisa.

2. Quais são os limites da janela de contexto? O Gemini 3 Pro oferece suporte a uma janela de contexto de entrada de 1 milhão de tokens e até 64 mil tokens de saída.

3. Existe um nível sem custo financeiro para o Gemini 3 Pro? Você pode testar o modelo sem custos financeiros no Google AI Studio, mas, no momento, não há um nível sem custo financeiro disponível para gemini-3-pro-preview na API Gemini.

4. Meu código thinking_budget antigo ainda vai funcionar? Sim, thinking_budget ainda é compatível com versões anteriores, mas recomendamos migrar para thinking_level para ter um desempenho mais previsível. Não use os dois na mesma solicitação.

5. O Gemini 3 é compatível com a API Batch? Sim, o Gemini 3 é compatível com a API Batch.

6. O armazenamento em cache de contexto é compatível? Sim, o armazenamento em cache de contexto é compatível com o Gemini 3. O número mínimo de tokens necessário para iniciar o armazenamento em cache é de 2.048.

7. Quais ferramentas são compatíveis com o Gemini 3? O Gemini 3 é compatível com a Pesquisa Google, a Pesquisa de arquivos, a Execução de código e o Contexto de URL. Ele também é compatível com a chamada de função padrão para suas próprias ferramentas personalizadas. No momento, o Google Maps e o Uso de computador não são compatíveis.

Próximas etapas

• Comece a usar o manual do Gemini 3
• Confira o guia dedicado do Cookbook sobre níveis de pensamento e como migrar do orçamento de pensamento para os níveis de pensamento.