API Interactions

A API Interactions é a melhor maneira de criar com modelos e agentes do Gemini. Desde junho de 2026, ela está disponível para todos e é recomendada para todos os novos projetos. Embora agora seja considerada legada, a API generateContent original continua com suporte total.

Por que usar a API Interactions?

  • Interface universal para todos os aplicativos: projetada como a interface padrão para todos os casos de uso, incluindo geração de texto de turno único, compreensão multimodal, saídas estruturadas, orquestração de ferramentas e fluxos de trabalho de agentes.
  • API única para modelos e agentes: um endpoint e padrão unificados para chamar modelos padrão do Gemini e agentes especializados diretamente (como Deep Research e agentes gerenciados personalizados).
  • Novos recursos prontos para uso: recursos como estado de conversa opcional do lado do servidor usando previous_interaction_id, etapas de execução observáveis para depuração e renderização da interface, e execuçãoem segundo plano para tarefas de longa duração usando background=true.
  • Custo menor com taxas de ocorrência em cache mais altas: ao usar conversas multiturno, o gerenciamento de estado opcional do lado do servidor permite um armazenamento em cache de contexto mais eficiente em todos os turnos, reduzindo os custos de token.
  • Onde os novos recursos são lançados: no futuro, todos os novos modelos, recursos multimodais capacidades, ferramentas e recursos de agentes serão lançados na API Interactions.

Por padrão, a API Interactions armazena solicitações para que você possa aproveitar os recursos de gerenciamento de estado do lado do servidor usando previous_interaction_id. Você pode ativar o comportamento sem estado definindo store=false. Consulte a seção de retenção de dados para detalhes.

Primeiros passos

  • Configure seu agente de programação: conecte-se ao MCP dos documentos do Gemini e instale a habilidade gemini-api-dev para dar ao seu assistente acesso direto aos documentos mais recentes para desenvolvedores e às práticas recomendadas. Para conferir as etapas detalhadas, consulte o guia Configurar seu agente de programação.
  • Migrar de generateContent: se você tiver uma integração, siga o guia de migração para fazer a transição para a API Interactions.
  • Começar: siga as etapas no guia de início rápido da API Interactions.

Guias de recursos

Conheça os recursos específicos da API Interactions nestes guias. Você pode usar o botão de alternância nessas páginas para alternar entre a API generateContent e a API Interactions:

Como a API Interactions funciona

A API Interactions é centrada em um recurso principal: o Interaction. Uma Interaction representa um turno completo em uma conversa ou tarefa. Ela funciona como um registro de sessão, contendo todo o histórico de uma interação como uma sequência cronológica de etapas de execução. Essas etapas incluem ideias do modelo, chamadas e resultados de ferramentas do lado do servidor ou do lado do cliente (como function_call e function_result) e a model_output final. O recurso armazenado (recuperado por interactions.get) também inclui etapas user_input para contexto completo, embora a resposta interactions.create retorne apenas etapas geradas pelo modelo.

Ao fazer uma chamada para interactions.create, você está criando um novo recurso Interaction.

Gerenciamento de estado do lado do servidor

Você pode usar o id de uma interação concluída em uma chamada subsequente usando o previous_interaction_id parâmetro para continuar a conversa. O servidor usa esse ID para recuperar o histórico da conversa, evitando que você precise reenviar todo o histórico do chat.

O parâmetro previous_interaction_id preserva apenas o histórico da conversa (entradas e saídas) usando previous_interaction_id. Os outros parâmetros são com escopo de interação e se aplicam apenas à interação específica que você está gerando no momento:

  • tools
  • system_instruction
  • generation_config (incluindo thinking_level, temperature etc.)

Isso significa que você precisa especificar esses parâmetros novamente em cada nova interação se quiser que eles sejam aplicados. Esse gerenciamento de estado do lado do servidor é opcional. Você também pode operar no modo sem estado enviando o histórico completo da conversa em cada solicitação.

Armazenamento e retenção de dados

Por padrão, a API armazena todos os objetos de interação (store=true) para simplificar o uso de recursos de gerenciamento de estado do lado do servidor (com previous_interaction_id), execução em segundo plano (usando background=true) e fins de observabilidade.

  • Nível pago: o sistema retém interações por 55 dias.
  • Nível sem custo financeiro: o sistema retém interações por 1 dia.

Se não quiser isso, defina store=false na sua solicitação. Esse controle é separado do gerenciamento de estado. Você pode desativar o armazenamento de qualquer interação. No entanto, observe que store=false é incompatível com a execução em segundo plano e impede o uso de previous_interaction_id para turnos subsequentes.

Para projetos de nível pago, é possível configurar a janela de retenção no AI Studio para marcar automaticamente os registros para exclusão do armazenamento do projeto após 7, 14, 28 ou 55 dias. Uma retenção mais curta pode afetar a recuperação de conversas anteriores.

Você pode excluir interações armazenadas a qualquer momento usando o delete método de forma programática, que exige o ID da interação. Também é possível visualizar e gerenciar registros de interações armazenadas, incluindo a exclusão do armazenamento do projeto, no AI Studio.

Após o período de armazenamento expirar, seus dados serão excluídos automaticamente.

Os objetos de interações são processados de acordo com os termos.

Visualizar interações no AI Studio

A API armazena solicitações da API Interactions executadas com store=true para projetos no nível pago. É possível visualizá-las diretamente na página "Registros" do Google AI Studio. Consulte o guia de registros para mais informações.

Práticas recomendadas

  • Taxa de ocorrência em cache: o armazenamento em cache implícito é compatível com os modos com e sem estado (consulte o guia de início rápido). O uso de previous_interaction_id (com estado) para continuar conversas permite que o sistema utilize mais facilmente o armazenamento em cache implícito para o histórico da conversa, o que melhora a performance e reduz os custos.
  • Interações de combinação: você tem a flexibilidade de combinar interações de agentes e modelos em uma conversa. Por exemplo, você pode usar um agente especializado, como o Deep Research, para a coleta inicial de dados e, em seguida, usar um modelo padrão do Gemini para tarefas de acompanhamento, como resumir ou reformatar, vinculando essas etapas ao previous_interaction_id.

Modelos e agentes compatíveis

Nome do modelo Tipo ID do modelo
Gemini 3.8 Flash Modelo gemini-3.8-flash
Gemini 3.7 Flash Modelo gemini-3.7-flash
Gemini 3.6 Flash Modelo gemini-3.6-flash
Gemini 3.5 Flash Modelo gemini-3.5-flash
Pré-lançamento do Gemini 3.1 Pro Modelo gemini-3.1-pro-preview
Gemini 3.5 Flash Lite Modelo gemini-3.5-flash-lite
Gemini 3.1 Flash Lite Modelo gemini-3.1-flash-lite
Pré-lançamento do Gemini 3 Flash Modelo gemini-3-flash-preview
Gemini 2.5 Pro Modelo gemini-2.5-pro
Gemini 2.5 Flash Modelo gemini-2.5-flash
Gemini 2.5 Flash Lite Modelo gemini-2.5-flash-lite
Gemini 3 Pro Image Modelo gemini-3-pro-image
Gemini 3.1 Flash Image Modelo gemini-3.1-flash-image
Pré-lançamento do Gemini 3.1 Flash TTS Modelo gemini-3.1-flash-tts-preview
Gemma 4 31B IT Modelo gemma-4-31b-it
Gemma 4 26B MoE IT Modelo gemma-4-26b-a4b-it
Lyria 3.5 Modelo lyria-3.5
Pré-lançamento do Lyria 3 Clip Modelo lyria-3-clip-preview
Pré-lançamento do Lyria 3 Pro Modelo lyria-3-pro-preview
Pré-lançamento do Deep Research Agente deep-research-preview-04-2026
Pré-lançamento do Deep Research Agente deep-research-max-preview-04-2026
Pré-lançamento do Antigravity Agente antigravity-preview-05-2026

SDKs

Você pode usar a versão mais recente dos SDKs do Google GenAI para acessar a API Interactions.

  • No Python, esse é o pacote google-genai da versão 2.3.0 em diante.
  • No JavaScript, esse é o pacote @google/genai da versão 2.3.0 em diante.

Saiba como instalar os SDKs na página de bibliotecas.

Limitações

  • MCP remoto: o Gemini 3 não oferece suporte ao MCP remoto. Esse recurso será lançado em breve.
  • Compatibilidade de modelos multiturno: ao misturar modelos diferentes em uma conversa (com ou sem estado), os modelos subsequentes precisam oferecer suporte às modalidades de saída dos modelos anteriores como entrada. Por exemplo, se você gerar uma imagem usando gemini-3.1-flash-image, não será possível continuar essa conversa com um modelo que não aceite entradas de imagem (como um modelo somente de texto ou um modelo de geração de música como o Lyria).

Os recursos a seguir são compatíveis com a generateContent API, mas ainda não estão disponíveis na API Interactions:

Feedback

Seu feedback é fundamental para o desenvolvimento da API Interactions. Compartilhe suas ideias, relate bugs ou solicite recursos no fórum da comunidade de desenvolvedores de IA do Google.

A seguir