Abra a documentação oficial do Gemini — especialmente páginas como a de geração de imagens Nano Banana — e você pode notar que, no topo da página, apareceu um seletor: de um lado, Interactions API; do outro, generateContent API. Isso não é só uma simples mudança na documentação; é o Google colocando oficialmente a Interactions API em GA (disponibilidade geral) em junho de 2026 e recomendando que todos os novos projetos priorizem essa opção. Neste artigo, juntamos a documentação oficial e os resultados de testes reais no gateway da APIYI para explicar de uma vez as diferenças centrais, as lacunas de capacidade e as recomendações práticas de uso.
Valor principal: depois de ler este artigo, você vai entender claramente as diferenças entre Interactions API e generateContent em termos de filosofia de design, gerenciamento de estado e cobertura de funcionalidades, além de saber qual paradigma escolher ao chamar o Gemini via proxy da APIYI.
Diferenças centrais entre Interactions API e generateContent
Vamos direto ao ponto: essas duas APIs não são apenas uma relação de versão nova versus antiga, mas sim duas filosofias de design diferentes. O generateContent segue um modelo sem estado, de “uma requisição, uma resposta”; o cliente precisa manter sozinho todo o histórico da conversa. Já a Interactions API joga o gerenciamento de estado para o servidor e redesenha toda a interação em torno do novo conceito de “Interaction”.
A documentação oficial define uma Interaction como “uma rodada completa de conversa ou tarefa”, composta internamente por uma sequência de etapas executadas em ordem temporal, incluindo o processo de raciocínio do modelo, chamadas de ferramentas e os resultados retornados, além da saída final do modelo. Isso significa que a Interactions API foi pensada desde o início para conversas com várias rodadas e tarefas do tipo agent, e não apenas para perguntas e respostas pontuais.
Isso também explica por que o Google escolheu a expressão “disponibilidade geral” em vez de simplesmente “nova funcionalidade”. A Interactions API entrou em beta público em dezembro de 2025 e foi oficialmente anunciada como GA em junho de 2026. O blog oficial deixa claro: “Recomendamos que todos os novos projetos e aplicativos usem a Interactions API”. Ao mesmo tempo, toda a documentação oficial já mostra por padrão esse novo paradigma, e o Google está incentivando SDKs de terceiros e parceiros do ecossistema a adotá-lo como interface padrão. Em outras palavras, não se trata de uma atualização opcional qualquer, mas de uma redefinição do jeito de chamar o Gemini — com um guia de migração para permitir uma transição gradual, sem obrigar uma mudança brusca.
| Dimensão de comparação | generateContent (legacy) | Interactions API |
|---|---|---|
| Status atual | Legado, mas totalmente suportado | GA oficial desde junho de 2026 |
| Recomendação oficial | Projetos existentes podem continuar usando | Recomendado para todos os novos projetos |
| Método principal | generateContent | interactions.create / get / delete |
| Filosofia de design | Requisição única sem estado | Rodadas de tarefa com estado centradas em Interaction |
| Novas capacidades futuras | Ainda recebe novos modelos da linha principal | Capacidades de agent de ponta chegam primeiro |
🎯 Dica técnica: se você está chamando modelos Gemini pelo gateway da APIYI (apiyi.com), vale a pena conferir por alguns minutos, comparando com a documentação oficial, qual paradigma seu projeto está usando agora. Aí você decide se precisa migrar, evitando achar que o código antigo ficou obsoleto só porque a documentação passou a exibir a Interactions API por padrão.
Diferenças essenciais entre o modo de requisição e o gerenciamento de estado
Entender a diferença entre os dois passa por uma pergunta central: quem vai manter o histórico da conversa? O generateContent exige que o cliente junte manualmente todo o array de mensagens anteriores a cada requisição; mesmo na décima rodada, você precisa reenviar, intacto, o conteúdo das nove anteriores. É um jeito simples e direto, mas conforme a conversa cresce, o corpo da requisição fica cada vez maior, e o histórico repetido também entra na conta de tokens.
A Interactions API oferece uma saída elegante: você pega o interaction id retornado na chamada anterior e passa como parâmetro previous_interaction_id na próxima requisição. Aí o servidor busca automaticamente o histórico completo da conversa, e o cliente não precisa mais concatenar e reenviar tudo na mão. A documentação oficial também traz o parâmetro background=true para tarefas longas e o recurso de “etapas de execução observáveis”, que ajudam tanto na depuração quanto na exibição do processo intermediário do modelo na UI — algo especialmente útil em produtos no estilo de agent.
Só que gerenciar estado no servidor também tem seu custo. Por padrão, o parâmetro store vem como true, então o sistema mantém os registros de interação — contas pagas por 55 dias e contas gratuitas por apenas 1 dia. Se, por privacidade ou conformidade, você definir store=false, até dá para desativar o armazenamento, mas aí você perde ao mesmo tempo a continuidade via previous_interaction_id e a execução em segundo plano. É um ponto de troca que vale pensar antes.
Do ponto de vista de custo, a proposta de valor é bem clara: com o estado mantido no servidor, o histórico da mesma conversa não precisa ser recarregado e recontado como input token em toda chamada, então a taxa de cache aproveitado sobe bastante. A própria documentação resume isso como “menor custo e maior taxa de cache”. Em cenários como chatbot de atendimento e perguntas e respostas sobre documentos longos, essa diferença aparece bastante quando o volume de chamadas aumenta. Já em geração única ou processamento em lote, que são naturalmente stateless, essa vantagem de custo quase não faz diferença.
Tem outro detalhe fácil de passar batido: tools, system_instruction e generation_config — incluindo campos como thinking_level e temperature — são parâmetros definidos por requisição. Mesmo usando previous_interaction_id para continuar a conversa anterior, essas configurações não são herdadas automaticamente; você precisa reenviá-las de forma explícita toda vez.
| Capacidade | generateContent | Interactions API |
|---|---|---|
| Manutenção do histórico da conversa | Cliente concatena manualmente todo o histórico | Servidor busca automaticamente via previous_interaction_id |
| Execução em segundo plano para tarefas longas | Não suporta | Suporta background=true |
| Visibilidade das etapas intermediárias de execução | É preciso analisar por conta própria | Oferece observable execution steps |
| Política de retenção de registros | Não se aplica | Retenção padrão: 55 dias para pagantes / 1 dia para grátis |
| Herança de ferramentas e parâmetros de geração | Enviar explicitamente a cada vez | Enviar explicitamente a cada vez, sem herança automática |
💡 Sugestão de escolha: para projetos que exigem conversas multi-turno frequentes ou fluxos de agent, o gerenciamento de estado da Interactions API realmente economiza bastante código de cola. Mas, se o seu caso é mais de geração pontual, essa vantagem talvez nem apareça. Nesse caso, vale testar primeiro com pouco tráfego na plataforma APIYI apiyi.com e só depois decidir se compensa migrar.
O que cada uma consegue fazer: quem já suporta o quê
A Interactions API é um paradigma novo, mas a documentação oficial também deixa claro o que ainda não está disponível. E isso precisa entrar na decisão de arquitetura — não dá para olhar só para o “novo” e assumir que ele já cobre tudo.
O texto oficial diz que a Interactions API ainda não suporta o campo video metadata em compreensão de vídeo, nem Batch API, nem o automatic function calling do Python, nem explicit caching. Por outro lado, o cache implícito via previous_interaction_id é suportado. Já o generateContent oferece suporte completo a saída em streaming, function calling, Batch API, cache explícito e entrada multimodal completa, incluindo texto, imagem, áudio, vídeo e documentos.
| Capacidade | generateContent | Interactions API |
|---|---|---|
| Batch API | ✅ Suporta | ❌ Ainda não suporta |
| Cache explícito (explicit caching) | ✅ Suporta | ⚠️ Apenas cache implícito |
Campo video metadata |
✅ Suporta | ❌ Ainda não suporta |
| Automatic function calling em Python | ✅ Suporta | ❌ Ainda não suporta |
| Saída em streaming / function calling | ✅ Suporta | ✅ Suporta |
| Custo declarado e taxa de cache | Cobrança padrão | A empresa diz ter menor custo e maior taxa de acerto de cache |
Usando a geração de imagens Nano Banana como exemplo, a diferença mais visível entre os dois paradigmas está em como você extrai o resultado. A Interactions API oferece propriedades práticas como interaction.output_image e interaction.output_text, que já trazem diretamente a última imagem ou o último bloco de texto gerado. No generateContent, por outro lado, o caminho é mais baixo nível: você percorre o array candidates[0].content.parts e precisa identificar manualmente o tipo de cada part. Para projetos que já têm a lógica de parsing do generateContent pronta, essa diferença de estrutura normalmente significa uma refatoração considerável, não só trocar o endpoint e seguir em frente.
Essas lacunas não são detalhes secundários. Batch API costuma ser a peça central de projetos sensíveis a custo que processam tarefas offline em lote; se você migrar e descobrir que o novo paradigma não suporta isso, na prática vai ter que redesenhar toda a esteira de processamento offline. Já o cache explícito impacta diretamente o custo em cenários de contexto longo: se o seu negócio reaproveita várias vezes um system prompt fixo ou materiais de referência, sem cache explícito você perde o controle fino sobre o que será cacheado e por quanto tempo. É por isso que a documentação oficial mantém as duas linhas técnicas lado a lado, em vez de aposentar o generateContent de vez — pelo menos até essas capacidades serem completadas, ele continua insubstituível.
🔧 Dica prática: se o seu negócio depende fortemente de Batch API para processamento em lote ou de cache explícito para reduzir custo, migrar agora para a Interactions API pode te fazer perder essas capacidades. O ideal é continuar acompanhando o ritmo das atualizações do guia de migração da documentação oficial, em vez de trocar o código de produção às pressas.
APIYI网关实测：当前该用哪个范式
结论先说：截至 2026 年 7 月 4 日的实测，通过 APIYI 网关调用 Gemini，仍然应该继续使用 generateContent 原生格式。
APIYI 技术团队针对 Interactions API 的关键路径做了直接测试，覆盖了两种主流鉴权方式，结果如下。
| 测试端点 | 鉴权方式 | 结果 |
|---|---|---|
| POST /v1beta2/interactions | Bearer token | ❌ 404（无效 URL） |
| POST /v1beta/interactions | Bearer token | ❌ 404（无效 URL） |
| POST /v1beta2/interactions | x-goog-api-key header | ❌ 404（无效 URL） |
| POST /v1beta/models/{model}:generateContent | Bearer token | ✅ 正常返回 |
APIYI 官方文档原话是：“APIYI 网关暂不支持 Interactions API 中转——/v1beta2/interactions 与 /v1beta/interactions 路径均返回 404”，并给出明确建议：“通过 APIYI 调用 Gemini 请继续使用 generateContent 原生格式”。这也是为什么 APIYI 站内目前所有 Gemini 相关文档都统一基于 generateContent 格式编写，这样能保证读者复制代码就能直接跑通，不会遇到路径 404 的问题。
需要强调的是，这是一个动态状态，而不是永久限制。随着 Interactions API 逐渐成为官方默认范式，网关侧后续大概率会跟进支持；届时 APIYI 会更新对应文档。目前可以关注 docs.apiyi.com/api-capabilities/gemini/interactions-api 这个页面，获取最新的支持状态，不需要每次都自己动手测试端点。
这组测试结果也提醒了一个容易被忽视的现实：官方文档层面的“正式可用”，和某个具体中转网关或第三方 SDK 是否已经完成适配，完全是两回事。开发者如果只看官方文档的默认展示，直接照抄 Interactions API 的代码示例塞进现有的中转配置里，大概率会先撞上 404，再花时间排查到底是自己的代码写错了，还是网关本身还没跟上。遇到类似情况时，先确认自己的调用链路（直连官方还是经第三方中转）对新范式的支持状态，往往比反复检查业务代码更快定位问题。
🚀 快速开始: 如果你现在就想验证自己的 Gemini 调用链路是否正常，推荐直接使用 APIYI apiyi.com 的 generateContent 格式接入，该平台提供统一的 base_url，支持文本、图片等多种 Gemini 模型的调用，不需要额外处理认证细节。
该怎么选：场景化决策建议
结合前面的能力对比和实测结论，给出一份简单的场景化建议表。
| 使用场景 | 推荐方案 | 理由 |
|---|---|---|
| 通过 APIYI 网关调用 Gemini | generateContent | 网关当前仅支持该格式，Interactions API 路径返回404 |
| 依赖 Batch API 批量处理 | generateContent | Interactions API 暂不支持 Batch API |
| 需要显式缓存降低成本 | generateContent | Interactions API 目前只有隐式缓存 |
| 构建多轮对话 agent，直连官方API | 可评估 Interactions API | 服务端状态管理能省去历史拼接逻辑 |
| 需要观察模型中间执行步骤调试 | Interactions API | 提供 observable execution steps 原生支持 |
| 现有项目已用 generateContent 跑通 | 暂不迁移 | legacy 仍完全支持，短期内还会获得新模型 |
简单来说，是否迁移不取决于“新不新”，而取决于你的具体依赖是否被 Interactions API 完整覆盖，以及你调用 Gemini 的链路（直连官方还是经中转网关）当前是否已经支持这套新范式。对大多数经 APIYI 中转调用的开发者来说，现阶段维持 generateContent 是更稳妥的选择。
Perguntas frequentes
P1: O generateContent vai ser descontinuado? Ainda vale a pena criar novos projetos com ele?
No curto prazo, não. A documentação oficial deixa claro que, embora o generateContent tenha sido marcado como legacy, ele “ainda tem suporte completo” e continuará recebendo novos modelos Gemini principais no futuro previsível. Se você estiver chamando o Gemini pela APIYI apiyi.com, hoje em dia não há problema nenhum em desenvolver novos projetos com base no generateContent; não precisa ficar preocupado só porque a documentação passa a mostrar o Interactions API por padrão.
P2: Quando o gateway da APIYI vai dar suporte ao Interactions API?
Ainda não existe um cronograma fechado. Isso depende do quanto esse novo paradigma vai se popularizar no ecossistema oficial e do andamento da adaptação no lado do gateway. Recomendamos acompanhar as atualizações da documentação oficial da plataforma APIYI apiyi.com. Assim que houver suporte a proxy do Interactions API, a documentação correspondente será atualizada na hora — sem necessidade de ficar testando repetidamente o status dos endpoints por conta própria.
P3: Dá para misturar as duas APIs no mesmo projeto?
Tecnicamente, desde que a cadeia de chamada suporte isso, os dois paradigmas podem coexistir. Por exemplo, dá para usar o generateContent para lidar com tarefas em lote do Batch API e, ao mesmo tempo, testar o Interactions API em cenários de conversa multi-turno quando estiver acessando a API oficial diretamente. Mas, ao chamar pela gateway da APIYI, como o caminho do Interactions API atualmente retorna 404, a recomendação é padronizar por enquanto no formato generateContent, para evitar que o mesmo projeto fique com duas lógicas de chamada diferentes e aumente o custo de manutenção.
Resumo
Depois que o Interactions API foi oficializado em junho de 2026, ele realmente passou a representar a direção de longo prazo do Google para chamadas ao Gemini. Recursos como gerenciamento de estado no servidor e etapas de execução observáveis são bem atraentes para apps do tipo agent. Mas ainda existem lacunas claras em relação a Batch API, cache explícito e metadados de vídeo. O generateContent continua totalmente suportado e ainda deve receber atualizações no curto prazo. Mais importante: nos testes feitos ao chamar o Gemini pela gateway da APIYI, até agora todos os caminhos relacionados ao Interactions API retornam 404, e o generateContent é o único formato que funciona no momento. Se você precisa chamar a série Gemini de forma estável e confiável, a recomendação é integrar via formato nativo generateContent usando a APIYI apiyi.com. Quando o gateway passar a suportar o novo paradigma, a documentação será atualizada rapidamente.
Os dados testados neste artigo e a validação das informações oficiais foram feitos pela equipe técnica da APIYI. Se você quiser saber mais detalhes sobre as chamadas da série Gemini, fale com o suporte técnico pelo APIYI apiyi.com.
Referências
-
Google AI for Developers – Visão geral da Interactions API: conceito de Interaction, métodos principais e descrição das capacidades
- Link:
ai.google.dev/gemini-api/docs/interactions-overview
- Link:
-
Google AI for Developers – generateContent（Legado）: status de suporte da API legada e escopo de capacidades
- Link:
ai.google.dev/gemini-api/docs/interactions
- Link:
-
Documentação oficial da APIYI – Status de suporte da Gemini Interactions API: resultados de endpoint testados no gateway e recomendações de uso
- Link:
docs.apiyi.com/api-capabilities/gemini/interactions-api
- Link:
