Comece a usar o Gemini 3

O Gemini 3 é nossa família de modelos mais inteligente até o momento, criada com base em 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 Gemini Enterprise Agent Platform, destacando os principais recursos e práticas recomendadas do Gemini 3.

Guia de início rápido

Antes de começar, é necessário fazer a autenticação na Gemini Enterprise Agent Platform usando uma chave de API ou credenciais padrão do aplicativo (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 do Google para Python versão 1.51.0 ou mais recente.

pip install --upgrade google-genai

Definir variáveis de ambiente para usar o SDK de IA generativa do Google com a Gemini Enterprise Agent Platform

Substitua o valor GOOGLE_CLOUD_PROJECT pelo ID do Google Cloud projeto. O modelo Gemini 3.1 Pro gemini-3.1-pro-preview e o modelo Gemini 3 Flash gemini-3-flash-preview só estão disponíveis em endpoints globais:

export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

Faça sua primeira solicitação

Por padrão, os modelos do Gemini 3 e o Gemini 3 Flash usam o raciocínio dinâmico para analisar os comandos. Para respostas mais rápidas e com menor latência quando o raciocínio complexo não é necessário, é possível restringir o thinking_level do modelo. O raciocínio baixo é 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.6-flash",
   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)

Testar tarefas de raciocínio complexo

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

Para tarefas mais lentas e de raciocínio alto:

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.6-flash",
  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 raciocínio

O Gemini 3 Flash apresenta dois novos níveis de raciocínio: MINIMAL e MEDIUM para oferecer ainda mais controle sobre como o modelo processa tarefas de raciocínio complexas.

MINIMAL oferece opções de orçamento de raciocínio quase zero para tarefas otimizadas para capacidade de processamento, em vez de raciocínio. MEDIUM permite um equilíbrio entre velocidade e raciocínio que permite 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 novos recursos e parâmetros disponíveis, além de links diretos para a documentação detalhada deles:

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

Nível de pensamento

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

  • MINIMAL: (somente Gemini 3 Flash e Gemini 3.1 Flash-Lite) restringe o modelo a usar o menor número possível de tokens para raciocínio e é mais adequado para tarefas de baixa complexidade que não se beneficiam de raciocínio extenso. MINIMAL é o mais próximo possível de um orçamento zero para raciocínio, mas ainda exige assinaturas de raciocínio.
  • LOW: restringe o modelo a usar menos tokens para raciocínio e é adequado para tarefas mais simples em que o raciocínio extenso não é necessário. LOW é ideal para tarefas de alta capacidade de processamento em que a velocidade é essencial.
  • MEDIUM: (somente Gemini 3 Flash, Gemini 3.1 Pro e Gemini 3.1 Flash-Lite) oferece uma abordagem equilibrada adequada para tarefas de complexidade moderada que se beneficiam do raciocínio, mas não exigem planejamento profundo e de várias etapas. Ele oferece mais capacidade de raciocínio do que LOW, mantendo uma latência menor do que HIGH.
  • HIGH: permite que o modelo use mais tokens para raciocínio e é adequado para comandos complexos que exigem raciocínio profundo, como planejamento de várias etapas, geração de código verificado ou cenários avançados de chamada de função. Esse é o nível padrão para modelos do Gemini 3 e do Gemini 3 Flash. Use essa configuração ao substituir tarefas que você pode ter usado anteriormente em modelos de raciocínio especializados.

Exemplo do SDK de IA generativa do Google

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.6-flash",
   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 com a OpenAI, os parâmetros padrão são mapeados automaticamente para equivalentes do Gemini 3:

  • reasoning_effort é mapeado para thinking_level.
  • none: é mapeado para thinking_level mínimo (somente Gemini 3 Flash).
  • medium: é mapeado para thinking_level médio para todos os modelos do Gemini 3.
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.6-flash",
    reasoning_effort="medium", # Map to thinking_level high.
    messages=[{"role": "user", "content": prompt}],
)

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

Resolução de 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 finos ou identificar pequenos detalhes, 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.

É possível 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 vai usar os padrões ideais com base no tipo de mídia.

Contagens de tokens

Esta tabela resume as contagens aproximadas de tokens para cada valor 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 finos em imagens, como o processamento de imagens de gravação de tela ou fotos de alta resolução.
high 1120 Tarefas de análise de imagem para garantir a qualidade máxima.
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 parte individual

É possível definir media_resolution por trecho de áudio individual:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
  model="gemini-3.6-flash",
  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)

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.6-flash",
  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 raciocínio

As assinaturas de raciocínio são tokens criptografados que preservam o estado de raciocínio do modelo durante conversas multiturno, especificamente 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 raciocínio atua como um "estado de salvamento", permitindo que o modelo retome a linha de raciocínio sem problemas depois que você fornecer o resultado da função.

Para mais informações, consulte Assinaturas de raciocínio.

Por que as assinaturas de raciocínio são importantes?

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

  • Continuidade do contexto: o modelo preserva o motivo pelo qual a ferramenta foi chamada.
  • 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 raciocínio são retornadas?

Os modelos do Gemini 3 e o Gemini 3 Flash aplicam validação mais rigorosa e tratamento atualizado em assinaturas de raciocínio que foram introduzidas originalmente no Gemini 2.5. Para garantir que o modelo mantenha o contexto em várias rodadas de uma conversa, é necessário retornar as assinaturas de raciocínio nas solicitações subsequentes.

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

Como processar assinaturas de raciocínio?

Há duas maneiras principais de processar assinaturas de raciocínio: automaticamente usando os SDKs de IA generativa do Google ou a API OpenAI, ou manualmente se você estiver interagindo diretamente com a API.

Tratamento automatizado (recomendado)

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

Exemplo de chamada de função manual

Ao usar o SDK de IA generativa do Google, as assinaturas de raciocínio são processadas automaticamente anexando a resposta completa do modelo em solicitações de modelo 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.6-flash",
   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="user",
        parts=[
            types.Part.from_function_response(
                name=function_call.name,
                response=function_response_data,
            )
        ],
    )
]

response_2 = client.models.generate_content(
   model="gemini-3.6-flash",
   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 do Google na chamada de função automática, as assinaturas de raciocínio 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.6-flash",
    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 raciocínio são processadas automaticamente anexando a resposta completa do modelo em solicitações de modelo 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": "user",
        "tool_call_id": tool_call_1.id,
        "content": json.dumps(result_1),
    }
)

response2 = client.chat.completions.create(
    model="gemini-3.6-flash",
    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.

Tratamento manual

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

É necessário 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 "<Function Call> no bloco de conteúdo <index of contents array> está faltando um thought_signature".

Respostas de funções multimodais

A chamada de função multimodal permite que os usuários tenham respostas de função que contenham objetos multimodais, permitindo uma melhor utilização das capacidades de chamada de função do modelo. A chamada de função padrão só oferece suporte a 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.6-flash",
    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="user",
    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.6-flash",
  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

É possível usar argumentos de chamada de função parcial de streaming para melhorar a experiência de streaming no uso de ferramentas. Esse recurso pode ser ativado definindo 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.6-flash",
   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 geralmente 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.

A mudança da temperatura (definindo-a como menor que 1.0) pode levar a um comportamento inesperado, como looping ou desempenho degradado, principalmente em tarefas matemáticas ou de raciocínio complexas.

Recursos compatíveis

Os modelos do Gemini 3 também oferecem suporte aos seguintes recursos:

Práticas recomendadas para comandos

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

  • Instruções precisas:seja conciso nos comandos de entrada. O Gemini 3 responde melhor a instruções diretas e claras. Ele pode analisar demais técnicas de engenharia de comandos detalhadas ou excessivamente complexas usadas para modelos mais antigos.
  • Detalhes da saída:por padrão, o Gemini 3 é menos detalhado e prefere fornecer respostas diretas e eficientes. Se o caso de uso exigir uma pessoa mais conversadora ou "falante", é necessário direcionar explicitamente o modelo no comando (por exemplo, "Explique isso como um assistente amigável e falante").
  • Embasamento:para casos de uso de embasamento, recomendamos o uso das seguintes instruções do desenvolvedor: 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.
  • Usar a ferramenta Pesquisa Google:ao usar a ferramenta Pesquisa Google, o Gemini 3 Flash pode, às vezes, confundir a data / hora atual com eventos em 2024. Isso pode resultar na formulação de consultas de pesquisa para o ano errado. Para garantir que o modelo utilize 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 de conhecimento: para determinadas consultas, o Gemini 3 Flash se beneficia de ser informado explicitamente sobre o limite de conhecimento. Esse é o caso quando a ferramenta Pesquisa Google está desativada e a consulta exige explicitamente que o modelo seja capaz de identificar 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.
  • Usar 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, enquanto a resolução mais baixa permite otimizar o custo e a latência de 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 thinking_level parâmetro para controlar a quantidade de raciocínio interno que o modelo realiza (baixo ou alto) e para equilibrar a qualidade da resposta, a complexidade do raciocínio, a latência e o custo.
  • Configurações de temperatura:se o código atual definir explicitamente temperature (especialmente para valores baixos de 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 looping ou degradação de desempenho em tarefas complexas.
  • Assinaturas de raciocínio: para modelos do Gemini 3, se uma assinatura de raciocínio for esperada em uma rodada, mas não 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 de multimodalidade:as contagens de tokens para entradas multimodais (imagens, vídeo, áudio) são uma estimativa com base na media_resolution escolhida. Assim, o resultado da chamada de API count_tokens pode não corresponder aos tokens consumidos finais. O uso preciso para faturamento só está disponível após a execução em 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 de mídia.
  • Entendimento de PDF e documentos:a resolução de OCR padrão para PDFs mudou. Se você dependeu de um comportamento específico para a análise de documentos densos, teste a nova media_resolution: "high" configuração 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 IMAGE em vez de DOCUMENT.
  • Segmentação de imagens:a segmentação de imagens não é compatível com os modelos do Gemini 3. Para cargas de trabalho que exigem segmentação de imagens integrada, recomendamos continuar usando o Gemini 2.5 Flash com o raciocínio desativado.
  • Respostas de funções multimodais: para modelos do Gemini 3, é possível incluir dados de imagem e PDF em respostas de função.

Perguntas frequentes

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

  2. 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.

  3. O gemini-3.1-pro-preview oferece suporte à saída de imagem? Não.

  4. O gemini-3.1-pro-preview oferece suporte à API Gemini Live? Não.

A seguir