API Interactions

A API Interactions é a maneira mais simples e eficiente de criar com modelos e agentes do Gemini. Desde junho de 2026, ela está disponível para todos os usuários e é recomendada para todos os novos projetos. Embora agora seja considerada legada, a API generateContent original ainda tem 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 em uma única interação, 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 um padrão unificados para chamar modelos padrão do Gemini e agentes especializados diretamente (como a Pesquisa avançada e agentes gerenciados personalizados).
  • Novas funcionalidades prontas 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, além de execução em segundo plano para tarefas de longa duração usando background=true.
  • Custo menor com taxas de acerto de cache mais altas: ao usar conversas de várias rodadas, o gerenciamento de estado opcional do lado do servidor permite um cache de contexto mais eficiente em várias rodadas, reduzindo os custos de token.
  • Onde os novos recursos são lançados: a partir de agora, todos os novos modelos, recursos multimodais, ferramentas e recursos de agente 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. É possível ativar o comportamento sem estado definindo store=false. Consulte a seção retenção de dados para mais detalhes.

Primeiros passos

Guias de recursos

Confira estes guias para conhecer os recursos específicos da API Interactions. Use a chave nessas páginas para alternar entre a API generateContent e a API Interactions:

Como a API Interactions funciona

A API Interactions se concentra em um recurso principal: o Interaction. Um Interaction representa uma rodada completa em uma conversa ou tarefa. Ele 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 reflexões do modelo, chamadas de ferramentas e resultados do lado do servidor ou do cliente (como function_call e function_result) e o model_output final. O recurso armazenado (recuperado via 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 parâmetro previous_interaction_id 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 de conversas (entradas e saídas) usando previous_interaction_id. Os outros parâmetros são no escopo da interação e se aplicam apenas à interação específica que você está gerando:

  • 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. O 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 as interações por 55 dias.
  • Nível sem custo financeiro: o sistema retém as 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 para qualquer interação. No entanto, store=false é incompatível com a execução em segundo plano e impede o uso de previous_interaction_id em turnos subsequentes.

É possível excluir as interações armazenadas a qualquer momento usando o método de exclusão encontrado na Referência da API. Só é possível excluir interações se você souber o ID delas.

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

O sistema processa objetos de interação de acordo com os termos.

Práticas recomendadas

  • Taxa de acerto de cache: o armazenamento em cache implícito é compatível com os modos com e sem estado. Consulte o guia de início rápido. Usar 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 o desempenho e reduz os custos.
  • Interações combinadas: você pode combinar interações de agente e modelo 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.5 Flash Modelo gemini-3.5-flash
Pré-lançamento do Gemini 3.1 Pro Modelo gemini-3.1-pro-preview
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
Imagem do Gemini 3.1 Flash 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
Prévia de clipes do Lyria 3 Modelo lyria-3-clip-preview
Pré-lançamento do Lyria 3 Pro Modelo lyria-3-pro-preview
Prévia do Deep Research Agente deep-research-preview-04-2026
Prévia do Deep Research Agente deep-research-max-preview-04-2026
Prévia do Antigravity Agente antigravity-preview-05-2026

SDKs

Use a versão mais recente dos SDKs da IA generativa do Google para acessar a API Interactions.

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

Saiba mais sobre como instalar os SDKs na página Bibliotecas.

Limitações

  • MCP remoto: o Gemini 3 não é compatível com MCP remoto, mas isso vai estar disponível em breve.
  • Compatibilidade de modelos com várias interações: ao misturar modelos diferentes em uma conversa (com ou sem estado), os modelos subsequentes precisam aceitar as modalidades de saída dos modelos anteriores como entrada. Por exemplo, se você gerar uma imagem usando o gemini-3.1-flash-image, não poderá continuar essa conversa com um modelo que não aceita entradas de imagem, como um modelo somente de texto ou um modelo de geração de música como o Lyria.

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

Feedback

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

A seguir