Comece a usar o 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 oferece um caminho consolidado e prático para começar a usar o Gemini 3 na Vertex AI, destacando os principais recursos e práticas recomendadas do Gemini 3.

Guia de início rápido

Antes de começar, autentique na Vertex AI usando uma chave de API ou o Application Default Credentials (ADC). Consulte métodos de autenticação para mais informações.

Instalar o SDK de IA generativa do Google

Os recursos da API Gemini 3 exigem o SDK de IA generativa para Python versão 1.51.0 ou mais recente.

pip install --upgrade google-genai

Definir variáveis de ambiente para usar o SDK da IA generativa com a Vertex AI

Substitua o valor GOOGLE_CLOUD_PROJECT pelo ID do projeto Google Cloud . Os modelos de pré-lançamento do Gemini 3 Pro gemini-3-pro-preview e do Gemini 3 Flash gemini-3-flash-preview estão disponíveis apenas em endpoints globais:

export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

Faça sua primeira solicitação

Por padrão, o Gemini 3 Pro e o Gemini 3 Flash usam o raciocínio dinâmico para responder aos comandos. Para respostas mais rápidas e com menor latência quando não é necessário um raciocínio complexo, é possível restringir o thinking_level do modelo. O pensamento lento é ideal para tarefas de alta capacidade de processamento em que a velocidade é fundamental.

Para respostas rápidas e de baixa latência:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3-pro-preview",
   contents="How does AI work?",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.LOW # For fast and low latency response
       )
   ),
)
print(response.text)

Faça tarefas de raciocínio complexo

O Gemini 3 é excelente em raciocínio avançado. Para tarefas complexas, como planejamento em várias etapas, geração de código verificada ou uso avançado de ferramentas, use níveis de pensamento altos. Use essas configurações para tarefas que antes exigiam modelos de raciocínio especializados.

Para tarefas mais lentas e que exigem mais raciocínio:

from google import genai
from google.genai import types

client = genai.Client()

prompt = """
You are tasked with implementing the classic Thread-Safe Double-Checked Locking (DCL) Singleton pattern in modern C++. This task is non-trivial and requires specialized concurrency knowledge to prevent memory reordering issues.

Write a complete, runnable C++ program named `dcl_singleton.cpp` that defines a class `Singleton` with a private constructor and a static `getInstance()` method.

Your solution MUST adhere to the following strict constraints:
1. The Singleton instance pointer (`static Singleton*`) must be wrapped in `std::atomic` to correctly manage memory visibility across threads.
2. The `getInstance()` method must use `std::memory_order_acquire` when reading the instance pointer in the outer check.
3. The instance creation and write-back must use `std::memory_order_release` when writing to the atomic pointer.
4. A standard `std::mutex` must be used only to protect the critical section (the actual instantiation).
5. The `main` function must demonstrate safe, concurrent access by launching at least three threads, each calling `Singleton::getInstance()`, and printing the address of the returned instance to prove all threads received the same object.
"""

response = client.models.generate_content(
  model="gemini-3-pro-preview",
  contents=prompt,
  config=types.GenerateContentConfig(
      thinking_config=types.ThinkingConfig(
          thinking_level=types.ThinkingLevel.HIGH # Dynamic thinking for high reasoning tasks
      )
  ),
)
print(response.text)

Outros níveis de pensamento

O Gemini 3 Flash apresenta dois novos níveis de pensamento: MINIMAL e MEDIUM. Assim, você tem ainda mais controle sobre como o modelo lida com tarefas complexas de raciocínio.

O MINIMAL oferece opções de orçamento de pensamento quase zero para tarefas otimizadas para capacidade, em vez de raciocínio. O MEDIUM permite um equilíbrio entre velocidade e raciocínio, o que possibilita alguma capacidade de raciocínio, mas ainda prioriza operações de baixa latência.

Novos recursos da API

O Gemini 3 apresenta melhorias poderosas na API e novos parâmetros projetados para oferecer aos desenvolvedores controle granular sobre desempenho (latência, custo), comportamento do modelo e fidelidade multimodal.

Esta tabela resume os principais recursos e parâmetros disponíveis, além de links diretos para a documentação detalhada:

Novo recurso/mudança na API Documentação
Modelo: gemini-3-pro-preview Card de modelo Model Garden
Nível de pensamento Pensar
Resolução da mídia Compreensão de imagens Compreensão de vídeo Compreensão de áudio Compreensão de documentos
Assinatura de pensamento Assinaturas de pensamento
Temperatura Referência da API
Respostas de função multimodal Chamada de função: respostas de função multimodal
Chamada de função de streaming Chamada de função: streaming de chamada de função

Nível de pensamento

O parâmetro thinking_level permite especificar um orçamento de pensamento para a geração de respostas do modelo. Ao selecionar um dos dois estados, você pode equilibrar explicitamente as compensações entre qualidade da resposta e complexidade e latência do raciocínio e custo.

  • MINIMAL: (somente Gemini 3 Flash) restringe o modelo a usar o mínimo possível de tokens para pensar e é melhor usado em tarefas de baixa complexidade que não se beneficiariam de um raciocínio extenso. MINIMAL é o mais próximo possível de um orçamento zero para pensar, mas ainda requer assinaturas de pensamento.
  • LOW: restringe o modelo para usar menos tokens no pensamento e é adequado para tarefas mais simples em que não é necessário um raciocínio extenso. O LOW é ideal para tarefas de alta capacidade de processamento em que a velocidade é essencial.
  • MEDIUM: (somente Gemini 3 Flash) oferece uma abordagem equilibrada adequada para tarefas de complexidade moderada que se beneficiam do raciocínio, mas não exigem um planejamento profundo e de várias etapas. Ela oferece mais capacidade de raciocínio do que LOW e mantém uma latência menor do que HIGH.
  • HIGH: permite que o modelo use mais tokens para pensar e é adequado para comandos complexos que exigem raciocínio profundo, como planejamento de várias etapas, geração de código verificada ou cenários avançados de chamada de função. Esse é o nível padrão do Gemini 3 Pro e do Gemini 3 Flash. Use essa configuração ao substituir tarefas que antes dependiam de modelos de raciocínio especializados.

Exemplo do SDK de IA generativa

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]",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.HIGH # Default, dynamic thinking
       )
   ),
)
print(response.text)

Exemplo de 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 3:

  • reasoning_effort é mapeado para thinking_level.
  • none: mapeia para thinking_level minimal (somente Gemini 3 Flash).
  • medium: corresponde ao nível thinking_level médio para o Gemini 3 Flash e thinking_level alto para o Gemini 3 Pro.
import openai
from google.auth import default
from google.auth.transport.requests import Request

credentials, _ = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])

client = openai.OpenAI(
    base_url=f"https://aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/global/endpoints/openapi",
    api_key=credentials.token,
)

prompt = """
Write a bash script that takes a matrix represented as a string with
format '[1,2],[3,4],[5,6]' and prints the transpose in the same format.
"""

response = client.chat.completions.create(
    model="gemini-3-pro-preview",
    reasoning_effort="medium", # Map to thinking_level high.
    messages=[{"role": "user", "content": prompt}],
)

print(response.choices[0].message.content)

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, página de PDF ou frame de vídeo.

Você pode definir a resolução como low, medium ou high globalmente (usando generation_config) ou para partes de mídia individuais. A resolução ultra_high só pode ser definida para partes de mídia individuais. Se não for especificado, o modelo usará padrões ideais com base no tipo de mídia.

Contagem de tokens

Esta tabela resume as contagens aproximadas de tokens para cada valor de media_resolution e tipo de mídia.

Resolução de mídia Imagem Vídeo PDF
UNSPECIFIED (padrão) 1120 70 560
LOW 280 70 280 + Texto
MEDIUM 560 70 560 + texto
HIGH 1120 280 1120 + texto
ULTRA_HIGH 2240 N/A N/A
Resolução de mídia Máximo de tokens Orientação de uso
ultra_high 2240 Tarefas que exigem análise de detalhes minuciosos em imagens, como processamento de imagens estáticas de gravações de tela ou fotos de alta resolução.
high 1120 Tarefas de análise de imagens para garantir a máxima qualidade.
medium 560
low Imagem: 280 Vídeo: 70 Suficiente para a maioria das tarefas. Observação:para vídeo, low é um máximo de 70 tokens por frame.

Definir media_resolution por peça individual

É possível definir media_resolution para cada parte de mídia individual:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model="gemini-3-pro-preview",
  contents=[
      types.Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png",
              mime_type="image/jpeg",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_HIGH # High resolution
          ),
      ),
      Part(
          file_data=types.FileData(
             file_uri="gs://cloud-samples-data/generative-ai/video/behind_the_scenes_pixel.mp4",
            mime_type="video/mp4",
          ),
          media_resolution=types.PartMediaResolution(
              level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_LOW # Low resolution
          ),
      ),
      "When does the image appear in the video? What is the context?",
  ],
)
print(response.text)

Como definir media_resolution globalmente

Também é possível definir media_resolution globalmente (usando GenerateContentConfig):

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model="gemini-3-pro-preview",
  contents=[
      types.Part(
          file_data=types.FileData(
              file_uri="gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png",
              mime_type="image/jpeg",
          ),
      ),
      "What is in the image?",
  ],
  config=types.GenerateContentConfig(
      media_resolution=types.MediaResolution.MEDIA_RESOLUTION_LOW, # Global setting
  ),
)
print(response.text)

Assinaturas de pensamento

As assinaturas de pensamento são tokens criptografados que preservam o estado de raciocínio do modelo durante conversas de várias rodadas, principalmente ao usar a chamada de função.

Quando um modelo de raciocínio decide chamar uma ferramenta externa, ele pausa o processo de raciocínio interno. A assinatura de pensamento funciona como um "estado de salvamento", permitindo que o modelo retome a cadeia de pensamento sem problemas assim que você fornecer o resultado da função.

Para mais informações, consulte Assinaturas de pensamento.

Por que as assinaturas de pensamento são importantes?

Sem assinaturas de pensamento, o modelo "esquece" as etapas específicas de raciocínio durante a fase de execução da ferramenta. Ao transmitir a assinatura de volta, você garante:

  • Continuidade do contexto: o modelo preserva o motivo da chamada da ferramenta.
  • Raciocínio complexo: permite tarefas de várias etapas em que a saída de uma ferramenta informa o raciocínio da próxima.

Onde as assinaturas de pensamento são retornadas?

O Gemini 3 Pro e o Gemini 3 Flash aplicam uma validação mais rigorosa e um tratamento atualizado nas assinaturas de pensamento, que foram introduzidas originalmente no Gemini 2.5. Para garantir que o modelo mantenha o contexto em vários turnos de uma conversa, retorne as assinaturas de pensamento nas solicitações subsequentes.

  • As respostas do modelo com uma chamada de função sempre retornam uma assinatura de pensamento, mesmo ao usar o nível de pensamento MINIMAL.
  • Quando há chamadas de função paralelas, a primeira parte da chamada de função retornada pela resposta do modelo tem uma assinatura de pensamento.
  • Quando há chamadas de função sequenciais (várias etapas), cada uma delas tem uma assinatura, e espera-se que os clientes transmitam a assinatura de volta.
  • As respostas do modelo sem uma chamada de função vão retornar uma assinatura de pensamento na última parte retornada pelo modelo.

Como lidar com assinaturas de pensamento?

Há duas maneiras principais de lidar com assinaturas de pensamento: automaticamente usando os SDKs de IA generativa ou a API OpenAI ou manualmente se você estiver interagindo diretamente com a API.

Processamento automatizado (recomendado)

Se você estiver usando os SDKs da IA generativa do Google (Python, Node.js, Go, Java) ou a API Chat Completions da OpenAI e utilizando os recursos padrão de histórico de chat ou anexando a resposta completa do modelo, os thought_signatures serão processados automaticamente. Não é necessário fazer nenhuma mudança no código.

Exemplo de chamada de função manual

Ao usar o SDK de IA generativa, as assinaturas de pensamento são processadas automaticamente anexando a resposta completa do modelo em solicitações sequenciais:

from google import genai
from google.genai import types

client = genai.Client()

# 1. Define your tool
get_weather_declaration = types.FunctionDeclaration(
   name="get_weather",
   description="Gets the current weather temperature for a given location.",
   parameters={
       "type": "object",
       "properties": {"location": {"type": "string"}},
       "required": ["location"],
   },
)
get_weather_tool = types.Tool(function_declarations=[get_weather_declaration])

# 2. Send a message that triggers the tool
prompt = "What's the weather like in London?"
response = client.models.generate_content(
   model="gemini-3-pro-preview",
   contents=prompt,
   config=types.GenerateContentConfig(
       tools=[get_weather_tool],
       thinking_config=types.ThinkingConfig(include_thoughts=True)
   ),
)

# 4. Handle the function call
function_call = response.function_calls[0]
location = function_call.args["location"]
print(f"Model wants to call: {function_call.name}")

# Execute your tool (e.g., call an API)
# (This is a mock response for the example)
print(f"Calling external tool for: {location}")
function_response_data = {
   "location": location,
   "temperature": "30C",
}

# 5. Send the tool's result back
# Append this turn's messages to history for a final response.
# The `content` object automatically attaches the required thought_signature behind the scenes.
history = [
    types.Content(role="user", parts=[types.Part(text=prompt)]),
    response.candidates[0].content, # Signature preserved here
    types.Content(
        role="tool",
        parts=[
            types.Part.from_function_response(
                name=function_call.name,
                response=function_response_data,
            )
        ],
    )
]

response_2 = client.models.generate_content(
   model="gemini-3-pro-preview",
   contents=history,
   config=types.GenerateContentConfig(
        tools=[get_weather_tool],
        thinking_config=types.ThinkingConfig(include_thoughts=True)
   ),
)

# 6. Get the final, natural-language answer
print(f"\nFinal model response: {response_2.text}")
Exemplo de chamada de função automática

Ao usar o SDK de IA generativa na chamada de função automática, as assinaturas de pensamento são processadas automaticamente:


from google import genai
from google.genai import types

def get_current_temperature(location: str) -> dict:
    """Gets the current temperature for a given location.

    Args:
        location: The city and state, for example San Francisco, CA

    Returns:
        A dictionary containing the temperature and unit.
    """
    # ... (implementation) ...
    return {"temperature": 25, "unit": "Celsius"}

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="What's the temperature in Boston?",
    config=types.GenerateContentConfig(
            tools=[get_current_temperature],
    )
)

print(response.text) # The SDK handles the function call and thought signature, and returns the final text
Exemplo de compatibilidade com a OpenAI

Ao usar a API OpenAI Chat Completions, as assinaturas de pensamento são processadas automaticamente anexando a resposta completa do modelo em solicitações sequenciais:

...
# Append user prompt and assistant response including thought signatures
messages.append(response1.choices[0].message)

# Execute the tool
tool_call_1 = response1.choices[0].message.tool_calls[0]
result_1 = get_current_temperature(**json.loads(tool_call_1.function.arguments))

# Append tool response to messages
messages.append(
    {
        "role": "tool",
        "tool_call_id": tool_call_1.id,
        "content": json.dumps(result_1),
    }
)

response2 = client.chat.completions.create(
    model="gemini-3-pro-preview",
    messages=messages,
    tools=tools,
    extra_body={
        "extra_body": {
            "google": {
                "thinking_config": {
                    "include_thoughts": True,
                },
            },
        },
    },
)

print(response2.choices[0].message.tool_calls)

Confira o exemplo de código completo.

Manuseio manual

Se você estiver interagindo diretamente com a API ou gerenciando payloads JSON brutos, é necessário processar corretamente o thought_signature incluído na vez do modelo.

Você precisa retornar essa assinatura na parte exata em que ela foi recebida ao enviar o histórico de conversas de volta.

Se as assinaturas adequadas não forem retornadas, o Gemini 3 vai retornar um erro 400 "O bloco de conteúdo <índice da matriz de conteúdo> <Function Call> está sem um thought_signature".

Respostas de função multimodal

A chamada de função multimodal permite que os usuários tenham respostas de função que contenham objetos multimodais, melhorando a utilização dos recursos de chamada de função do modelo. A chamada de função padrão só é compatível com respostas de função baseadas em texto:

from google import genai
from google.genai import types

client = genai.Client()

# This is a manual, two turn multimodal function calling workflow:

# 1. Define the function tool
get_image_declaration = types.FunctionDeclaration(
   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., 'green shirt')."
            }
       },
       "required": ["item_name"],
   },
)
tool_config = types.Tool(function_declarations=[get_image_declaration])

# 2. Send a message that triggers the tool
prompt = "Show me the green shirt I ordered last month."
response_1 = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents=[prompt],
    config=types.GenerateContentConfig(
        tools=[tool_config],
    )
)

# 3. Handle the function call
function_call = response_1.function_calls[0]
requested_item = function_call.args["item_name"]
print(f"Model wants to call: {function_call.name}")

# Execute your tool (e.g., call an API)
# (This is a mock response for the example)
print(f"Calling external tool for: {requested_item}")

function_response_data = {
  "image_ref": {"$ref": "dress.jpg"},
}

function_response_multimodal_data = types.FunctionResponsePart(
   file_data=types.FunctionResponseFileData(
      mime_type="image/png",
      display_name="dress.jpg",
      file_uri="gs://cloud-samples-data/generative-ai/image/dress.jpg",
   )
)

# 4. Send the tool's result back
# Append this turn's messages to history for a final response.
history = [
  types.Content(role="user", parts=[types.Part(text=prompt)]),
  response_1.candidates[0].content,
  types.Content(
    role="tool",
    parts=[
        types.Part.from_function_response(
            name=function_call.name,
            response=function_response_data,
            parts=[function_response_multimodal_data]
        )
    ],
  )
]

response_2 = client.models.generate_content(
  model="gemini-3-pro-preview",
  contents=history,
  config=types.GenerateContentConfig(
      tools=[tool_config],
      thinking_config=types.ThinkingConfig(include_thoughts=True)
  ),
)

print(f"\nFinal model response: {response_2.text}")

Chamada de função de streaming

Você pode usar argumentos de chamada de função parcial de streaming para melhorar a experiência de streaming no uso de ferramentas. Para ativar esse recurso, defina explicitamente stream_function_call_arguments como true:

from google import genai
from google.genai import types

client = genai.Client()

get_weather_declaration = types.FunctionDeclaration(
  name="get_weather",
  description="Gets the current weather temperature for a given location.",
  parameters={
      "type": "object",
      "properties": {"location": {"type": "string"}},
      "required": ["location"],
  },
)
get_weather_tool = types.Tool(function_declarations=[get_weather_declaration])


for chunk in client.models.generate_content_stream(
   model="gemini-3-pro-preview",
   contents="What's the weather in London and New York?",
   config=types.GenerateContentConfig(
       tools=[get_weather_tool],
       tool_config = types.ToolConfig(
           function_calling_config=types.FunctionCallingConfig(
               mode=types.FunctionCallingConfigMode.AUTO,
               stream_function_call_arguments=True,
           )
       ),
   ),
):
   function_call = chunk.function_calls[0]
   if function_call and function_call.name:
       print(f"{function_call.name}")
       print(f"will_continue={function_call.will_continue}")

Exemplo de resposta do modelo:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "functionCall": {
              "name": "get_weather",
              "willContinue": true
            }
          }
        ]
      }
    }
  ]
}

Temperatura

  • Range for Gemini 3: 0.0 - 2.0 (default: 1.0)

Para o Gemini 3, é altamente recomendável manter o parâmetro temperature no valor padrão de 1.0.

Embora os modelos anteriores se beneficiassem da temperatura de ajuste 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 como menos de 1.0) pode levar a um comportamento inesperado, como loops ou desempenho degradado, principalmente em tarefas matemáticas ou de raciocínio complexas.

Recursos compatíveis

Os modelos do Gemini 3 também são compatíveis com os seguintes recursos:

Práticas recomendadas para comandos

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 verbosas ou muito 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ê precisa direcionar explicitamente o modelo no comando (por exemplo, "Explique isso como um assistente amigável e falante").
  • Fundamentação:para casos de uso de fundamentação, recomendamos usar as seguintes instruções para desenvolvedores: You are a strictly grounded assistant limited to the information provided in the User Context. In your answers, rely **only** on the facts that are directly mentioned in that context. You must **not** access or utilize your own knowledge or common sense to answer. Do not assume or infer from the provided facts; simply report them exactly as they appear. Your answer must be factual and fully truthful to the provided text, leaving absolutely no room for speculation or interpretation. Treat the provided context as the absolute limit of truth; any facts or details that are not directly mentioned in the context must be considered **completely untruthful** and **completely unsupported**. If the exact answer is not explicitly written in the context, you must state that the information is not available.
  • Usando a ferramenta Pesquisa Google:às vezes, o Gemini 3 Flash pode confundir a data / hora atual com eventos de 2024. Isso pode fazer com que o modelo formule consultas de pesquisa para o ano errado. Para garantir que o modelo use o período correto, reforce explicitamente a data atual em system instructions: For time-sensitive user queries that require up-to-date information, you MUST follow the provided current time (date and year) when formulating search queries in tool calls. Remember it is 2025 this year.
  • Limite do conhecimento: para determinadas consultas, o Gemini 3 Flash se beneficia de um limite de conhecimento explícito. Isso acontece quando a ferramenta Pesquisa Google está desativada e a consulta exige explicitamente que o modelo identifique os dados de corte no conhecimento paramétrico. Recomendação: adicione a seguinte cláusula a system instructions: Your knowledge cutoff date is January 2025.
  • Usando media_resolution: use o parâmetro media_resolution para controlar o número máximo de tokens que o modelo usa para representar uma imagem ou frames em vídeos. A alta resolução permite que o modelo capture detalhes em uma imagem e pode usar mais tokens por frame. Já a resolução mais baixa permite otimizar o custo e a latência para imagens com menos detalhes visuais.
  • Melhorar a análise de vídeo: use uma taxa de amostragem de frames por segundo (FPS) mais alta para vídeos que exigem análise temporal granular, como compreensão de ação rápida ou rastreamento de movimento de alta velocidade.

Considerações sobre a migração

Considere os seguintes recursos e restrições ao migrar:

  • Nível de pensamento: os modelos do Gemini 3 usam o parâmetro thinking_level para controlar a quantidade de raciocínio interno que o modelo realiza (baixo ou alto) e para equilibrar qualidade da resposta, complexidade do raciocínio, latência e custo.
  • Configurações de temperatura:se o código atual definir explicitamente temperature (especialmente para valores baixos em saídas determinísticas), é recomendável 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.
  • Assinaturas de pensamento: para modelos do Gemini 3, se uma assinatura de pensamento for esperada em uma rodada, mas não for fornecida, o modelo vai retornar um erro em vez de um aviso.
  • Resolução de mídia e tokenização: os modelos do Gemini 3 usam um comprimento de sequência variável para tokenização de mídia em vez de Pan e Scan, e têm novas resoluções padrão e custos de token para imagens, PDFs e vídeos.
  • Contagem de tokens para entrada multimodal:a contagem de tokens para entradas multimodais (imagens, vídeo, áudio) é uma estimativa baseada na media_resolution escolhida. Assim, o resultado da chamada da API count_tokens pode não corresponder aos tokens consumidos finais. O uso preciso para faturamento só fica disponível após a execução no usage_metadata da resposta.
  • Consumo de tokens:a migração para os padrões do Gemini 3 pode aumentar o uso de tokens para imagens e 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.
  • Entendimento de PDFs e documentos: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. Para modelos do Gemini 3, as contagens de tokens de PDF em usage_metadata são informadas na modalidade IMAGEM em vez de DOCUMENTO.
  • Segmentação de imagem:não é compatível com os modelos do Gemini 3. Para cargas de trabalho que exigem segmentação de imagem integrada, recomendamos continuar usando o Gemini 2.5 Flash com o modo de pensamento desativado.
  • Respostas de função multimodais: para modelos do Gemini 3, é possível incluir dados de imagem e PDF nas respostas de função.

Perguntas frequentes

  1. Qual é o corte de conhecimento do Gemini 3 Pro? O Gemini 3 tem um corte de conhecimento de janeiro de 2025.

  2. Em qual região o gemini-3-pro-preview está disponível no Google Cloud? Global.

  3. Quais são os limites da janela de contexto? Os modelos do Gemini 3 oferecem suporte a uma janela de contexto de entrada de 1 milhão de tokens e até 64 mil tokens de saída.

  4. O gemini-3-pro-preview aceita saída de imagem? Não.

  5. O gemini-3-pro-preview é compatível com a API Gemini Live? Não.

A seguir