Novidades do Gemini 3.5 Flash

O Gemini 3.5 Flash está em disponibilidade geral (GA), é estável e está pronto para uso em produção em grande escala. Como nosso modelo Flash mais inteligente, ele oferece desempenho de ponta sustentado em execução agêntica, programação e tarefas de longo prazo em grande escala.

Este guia contém uma visão geral das melhorias, mudanças na API e orientações de migração do Gemini 3.5 Flash.

Novo modelo

O Gemini 3.5 Flash oferece suporte à janela de contexto de 1 milhão de tokens, 65 mil tokens de saída máxima, raciocínio e o mesmo conjunto de ferramentas e recursos da plataforma do Gemini 3 Flash. No momento, Uso de computador está indisponível.

Para especificações completas, consulte a visão geral dos modelos. Para saber os preços, consulte a página de preços.

Guia de início rápido

Todos os exemplos neste guia usam a API GenerateContent. A API Interactions também é compatível. As mesmas opções de configuração e recomendações se aplicam.

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Explain how parallel agentic execution works in three sentences.",
)
print(response.text)

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Explain how parallel agentic execution works in three sentences.",
  });
  console.log(response.text);
}

main();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Explain how parallel agentic execution works in three sentences."}]
    }]
  }'

O que há de novo

• Performance de ponta sustentada:nosso modelo Flash mais inteligente, otimizado para tarefas de programação e agênticas em grande escala.
• Execução agêntica:implantação de subagentes, solução de problemas e loops agênticos rápidos em grande escala.
• Programação:ciclos de programação iterativos, exploração rápida e prototipagem para testar caminhos alternativos e explorar soluções de forma dinâmica.
• Horizonte longo:fluxos de trabalho de várias etapas e uso de ferramentas em grande escala.
• Preservação de ideias:o modelo mantém o raciocínio intermediário em conversas de várias etapas automaticamente. Nenhuma mudança na API é necessária.
• Novo nível de esforço padrão:o esforço de pensamento padrão mudou de high para medium. Consulte Novo nível de esforço padrão para mais detalhes.
• Melhoria no raciocínio do low:o low agora está muito melhor para tarefas de código e de agente que exigem menos etapas, oferecendo alta qualidade com menor latência e custo.
• Versão GA:modelo estável para uso em produção escalonada.

Como escolher o modelo de Flash certo

O Gemini 3.5 Flash é nosso modelo Flash mais inteligente e avançado. No entanto, diferentes casos de uso podem ter requisitos de custo e latência diferentes.

• Gemini 3.1 Flash-Lite: para tarefas de baixo custo e alto volume que não exigem a profundidade de raciocínio avançada do 3.5 Flash, recomendamos usar o Gemini 3.1 Flash-Lite. É um modelo estável e de longo prazo otimizado para eficiência. Consulte o guia do desenvolvedor do Flash Lite para mais detalhes.
• Pré-lançamento do Gemini 3 Flash: recomendamos migrar para o 3.5 Flash para ter estabilidade de GA e raciocínio aprimorado. No entanto, o Gemini 3 Flash (pré-lançamento) continua disponível para desenvolvedores que querem continuar testando com o modelo de pré-lançamento.

Mudanças no comportamento

Novo nível de esforço padrão: medium

O esforço de pensamento padrão agora é medium, mudando de high no pré-lançamento do Gemini 3 Flash. medium gera resultados muito bons em uma ampla variedade de tarefas, além de ser mais rápido e econômico. Para problemas complexos, o high incentiva o modelo a pensar mais profundamente.

Para substituir o padrão, defina thinking_level na sua configuração:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Prove that the square root of 2 is irrational.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="high")
    ),
)

print(response.text)

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: "Prove that the square root of 2 is irrational.",
    config: {
      thinkingConfig: {
        thinkingLevel: "HIGH",
      },
    },
  });
  console.log(response.text);
}

main();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Prove that the square root of 2 is irrational."}]
    }],
    "generationConfig": {
      "thinkingConfig": {
        "thinkingLevel": "HIGH"
      }
    }
  }'

A tabela a seguir mostra quais níveis de pensamento são compatíveis com cada modelo:

Preservação de ideias

O modelo mantém o raciocínio intermediário em conversas de várias etapas automaticamente. Quando presente no histórico de conversas, o contexto de raciocínio é mantido, o que melhora o desempenho em tarefas complexas de várias etapas, como depuração iterativa e refatoração de código. Nenhuma mudança de API necessária:

• API Interactions: as reflexões já são preservadas automaticamente. Nenhuma mudança no comportamento.
• API GenerateContent: a partir do Gemini 3.5 Flash, o modelo usa o contexto de raciocínio de todas as interações anteriores quando há assinaturas de pensamento no histórico de conversas. Para ativar isso, transmita o histórico de conversas completo e não modificado (incluindo assinaturas de pensamento) em contents. Os SDKs fazem isso automaticamente.

Atualizações de parâmetros e práticas recomendadas no Gemini 3.x

As informações a seguir se aplicam a todos os modelos do Gemini 3.x, incluindo o Gemini 3.5 Flash.

• temperature, top_p, top_k: recomendamos não mudar os valores padrão. Os recursos de raciocínio do Gemini 3 são otimizados para as configurações padrão.
• Use thinking_level em vez de thinking_budget
• Correspondência de respostas de chamadas de função: id, name e a contagem de respostas precisam corresponder às chamadas anteriores.
• Respostas de funções multimodais: inclua conteúdo multimodal dentro da resposta da função, não fora dela.
• Instruções inline nas respostas de função: adicione ao texto de resposta da função, não como partes separadas.
• Reduza chamadas de ferramentas desnecessárias: use níveis de pensamento mais baixos ou teste instruções do sistema para reduzir as chamadas de ferramentas em fluxos de trabalho de agentes.

Consulte as seções abaixo para saber como atualizar seu código.

Parâmetros de amostragem (não recomendado)

temperature, top_p e top_k não são mais recomendados para todos os modelos do Gemini 3.x. As capacidades de raciocínio do Gemini 3 são otimizadas para as configurações padrão. Remova esses parâmetros de todas as solicitações.

# ⚠️ Remove these parameters (not recommended)
config = types.GenerateContentConfig(
    temperature=0.7,
    top_p=0.9,
    top_k=40
)

Para garantir o determinismo, recomendamos definir uma instrução do sistema com regras explícitas para seu caso de uso específico.

thinking_budget (não recomendado)

O parâmetro numérico bruto thinking_budget não é mais recomendado em todos os modelos do Gemini 3.x. Em vez disso, use o enum de string thinking_level.

# ⚠️ Before (not recommended)
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_budget=7500)
)

# ✅ After
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_level="medium")
)

Valores disponíveis: minimal, low, medium (padrão) e high.

Chamada de função: correspondência restrita de respostas

A API Interactions já gera erros em respostas de função incompatíveis. A API GenerateContent ainda não gera erros, mas respostas incompatíveis fazem com que o modelo retorne respostas vazias com finish_reason: STOP na maioria dos casos. Siga sempre estas convenções:

# ✅ Include matching id and name in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result},
                id=tool_call.id,
            )
        ]),
    ],
)

// ✅ Include matching id and name in the function response
const functionResponsePart = {
  functionResponse: {
    name: toolCall.name,
    response: { result: result },
    id: toolCall.id,
  },
};

const finalResponse = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: [
    ...previousContents,
    { role: "model", parts: [{ functionCall: toolCall }] },
    { role: "user", parts: [functionResponsePart] },
  ],
  config: config,
});

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "..."}]},
      {"role": "model", "parts": [{"functionCall": {"name": "my_function", "args": {...}}}]},
      {"role": "user", "parts": [{"functionResponse": {"name": "my_function", "id": "call_id", "response": {"result": "..."}}}]}
    ]
  }'

Respostas de funções multimodais

Muitas vezes, os clientes fornecem imagens fora da resposta da função. Isso pode levar a um comportamento inesperado do modelo (por exemplo, vazamento de pensamento) e resultar em saídas de menor qualidade. Siga a recomendação na documentação da API Multimodal Function Responses e inclua conteúdo multimodal nas partes da resposta da função que você envia ao modelo. O modelo pode processar esse conteúdo multimodal na próxima vez para produzir uma resposta mais completa.

# ✅ Include multimodal content in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={
                    "result": "instrument.jpg",
                    "image": base64_image_data,
                },
                id=tool_call.id,
            )
        ]),
    ],
)

// ✅ Include multimodal content in the function response
const finalResponse = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: [
    ...previousContents,
    { role: "model", parts: [{ functionCall: toolCall }] },
    {
      role: "user",
      parts: [{
        functionResponse: {
          name: toolCall.name,
          id: toolCall.id,
          response: {
            result: "instrument.jpg",
            image: base64ImageData,
          },
        },
      }],
    },
  ],
  config: config,
});

Instruções in-line nas respostas de função

Muitas vezes, os clientes fornecem instruções adicionais com as respostas da função como Parts subsequentes. Isso pode levar a um comportamento inesperado do modelo (por exemplo, vazamento de pensamento) e resultar em saídas de menor qualidade. Em vez disso, adicione as instruções extras ao fim do texto de resposta da função, separadas por duas novas linhas.

# ✅ Append inline instructions to the end of the function response separated by two newlines
result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result_text},
                id=tool_call.id,
            )
        ]),
    ],
)

// ✅ Append inline instructions to the end of the function response separated by two newlines
const resultText = `${JSON.stringify(result)}\n\n<your inline instructions>`;

const finalResponse = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: [
    ...previousContents,
    { role: "model", parts: [{ functionCall: toolCall }] },
    {
      role: "user",
      parts: [{
        functionResponse: {
          name: toolCall.name,
          id: toolCall.id,
          response: { result: resultText },
        },
      }],
    },
  ],
  config: config,
});

Reduzir chamadas de ferramentas desnecessárias

Se você notar um uso excessivo de chamadas de função, duas técnicas podem ajudar a minimizar isso:

1. Comece reduzindo o nível de pensamento (medium, low ou minimal): níveis mais altos incentivam o modelo a usar mais ferramentas para explorar e verificar, então diminuir o nível pode reduzir as chamadas de ferramentas.

2. Adicione uma instrução do sistema:se o uso excessivo persistir depois de ajustar o nível de raciocínio, considere um comando que restrinja o uso da ferramenta. Exemplo:

   You have a limited action budget of <n> tool calls. Use them efficiently.
   

Lista de verificação de migração

Migrar do pré-lançamento do Gemini 3 Flash

• Atualizar nome do modelo: gemini-3-flash-preview → gemini-3.5-flash
• Conferir preços. O Gemini 3.5 Flash é mais caro do que o Gemini 3 Flash Preview. Se o caso de uso for muito sensível a custos, considere migrar para o Gemini 3.1 Flash-Lite. Consulte a página de preços para mais detalhes.
• Remova temperature, top_p e top_k da sua configuração (não é mais recomendado).
• Substitua thinking_budget por thinking_level.
• Adicione id e name correspondente a todas as partes FunctionResponse.
• Teste seus comandos. O esforço padrão mudou de high para medium. Verifique a qualidade, a velocidade e o custo.
• A preservação de ideias agora está ativada por padrão. O contexto de raciocínio é mantido em todas as interações, o que melhora a performance, mas pode aumentar o uso de tokens.
• Reduza as chamadas de ferramentas desnecessárias: comece diminuindo o nível de raciocínio (medium, low ou minimal) e adicione uma instrução do sistema para restringir o uso de ferramentas se o excesso persistir.
• No momento, o uso de computadores não está disponível no Gemini 3.5 Flash. Para cargas de trabalho de uso em computador, continue usando a prévia do Gemini 3 Flash.

Migrar do Gemini 2.5

Todas as opções acima, além das seguintes:

• Simplifique os comandos. Se você usou a engenharia de comandos com linha de raciocínio para forçar o raciocínio, tente thinking_level: "medium" ou "high" com comandos mais simples.
• Testar cargas de trabalho de PDF e mídia. Se você dependia de um comportamento específico para a análise de documentos densos, teste a configuração media_resolution_high para garantir a precisão contínua. A migração para os padrões do Gemini 3 também pode aumentar o uso de tokens para PDFs, mas diminuir para vídeos. Se as solicitações excederem a janela de contexto, reduza explicitamente o media_resolution. Consulte os documentos sobre resolução de mídia para mais detalhes.
• Use a combinação de ferramentas. A Pesquisa Google, o contexto de URL, a execução de código e as funções personalizadas podem ser usados na mesma solicitação.
• Se você estiver usando respostas de função multimodal, mova o conteúdo multimodal para dentro das partes de resposta da função, não ao lado delas.
• Se você usar instruções inline com respostas de função, anexe-as ao texto da resposta de função separadas por duas novas linhas, não como partes separadas.
• A segmentação de imagens não é compatível com o Gemini 3.x. Para cargas de trabalho de segmentação, continue usando o Gemini 2.5 Flash com o modo de pensamento desativado ou o Gemini Robotics-ER 1.6.

Recursos da família Gemini 3

O Gemini 3.5 Flash herda todas as funcionalidades da família Gemini 3, exceto o uso de computador. Recursos introduzidos no Gemini 3 que continuam disponíveis:

• Pensamento:contexto de raciocínio criptografado preservado em todas as chamadas de API. Automático na API Interactions; implícito em GenerateContent.
• Saídas estruturadas com ferramentas:combine o modo JSON com ferramentas integradas (pesquisa, contexto de URL, execução de código, chamadas de função).
• Respostas de funções multimodais:retornam imagens, áudio e outras mídias nos resultados de chamadas de função.
• Execução de código com imagens:execute códigos que processam e geram imagens.
• Uso combinado de ferramentas:use ferramentas integradas e chamada de função personalizada na mesma solicitação.
• Resolução de mídia:controle refinado sobre a alocação de tokens para entradas de imagem, vídeo e PDF. Os modelos do Gemini 3 oferecem suporte a configurações de resolução por item de conteúdo (low, medium, high, ultra_high) para comandos de fidelidade mista.
• Assinaturas de pensamento:representações criptografadas do raciocínio interno do modelo. Obrigatório para chamada de função em várias etapas. Gerenciado automaticamente pelos SDKs oficiais.

Práticas recomendadas para comandos

Os modelos do Gemini 3.x são de raciocínio, o que muda a forma como você precisa dar comandos.

• Instruções precisas:seja conciso. O Gemini 3.x responde melhor a instruções diretas e claras. Técnicas de engenharia de comandos detalhadas ou complexas projetadas para modelos mais antigos podem fazer com que o modelo analise demais.
• Nível de detalhe da saída:por padrão, o Gemini 3.x é menos detalhado e prefere respostas diretas e eficientes. Se o caso de uso exigir um tom de conversa, oriente o modelo explicitamente no comando (por exemplo, "Explique isso como um assistente amigável e falante").
• Gerenciamento de contexto:ao trabalhar com conjuntos de dados grandes (como 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. Para ancorar o raciocínio do modelo, comece sua pergunta com uma frase como "Com base nas informações anteriores...".

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

Limitações

• A segmentação de imagens não é compatível com o Gemini 3.x. Para cargas de trabalho de segmentação, continue usando o Gemini 2.5 Flash com o modo de pensamento desativado ou o Gemini Robotics-ER 1.6.

Perguntas frequentes

1. Qual é o limite de conhecimento do Gemini 3.5 Flash? O Gemini 3.5 Flash tem um limite 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.5 Flash oferece suporte a uma janela de contexto de entrada de 1 milhão de tokens e até 65 mil tokens de saída.

3. 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 uma performance mais previsível. Não use os dois na mesma solicitação.

4. O Gemini 3.5 Flash é compatível com a API Batch? Sim. Consulte o guia da API Batch para mais detalhes.

5. O armazenamento em cache de contexto é compatível? Sim, o armazenamento em cache de contexto é compatível.

6. Quais ferramentas são compatíveis? O Gemini 3.5 Flash é compatível com Pesquisa Google, Embasamento com o Google Maps, Pesquisa de arquivos, Execução de código, Contexto de URL e Chamada de função padrão, incluindo uso combinado de ferramentas. O Uso de computador não é compatível com o Gemini 3.5 Flash.

Próximas etapas

• Saiba mais sobre estratégias de design de comandos no guia de engenharia de comandos.
• Comece a usar o Livro de receitas do Gemini 3
• Saiba mais sobre otimização e inferência da API Gemini