Se a sua equipe já usa CC Switch ou um plano de controle no estilo NewAPI, a maneira mais rápida de ativar o Gemini não é adicionar mais uma credencial de provedor em todo lugar. É definir uma rota upstream, uma regra de nomenclatura de modelo, uma checagem de uso e uma etapa de revisão de produção antes do rollout.
A Google agora documenta o acesso ao Gemini por meio de bibliotecas OpenAI alterando a chave de API, a URL base e o nome do modelo. Para acesso direto ao Gemini, a URL base compatível com OpenAI é https://generativelanguage.googleapis.com/v1beta/openai/. Para equipes que querem uma camada operacional única entre o Gemini e outros provedores, a Flatkey expõe uma rota única compatível com OpenAI em https://router.flatkey.ai/v1, e a linguagem atual da página inicial enfatiza uma chave, uma URL base e manter o seu SDK existente.
Este guia é para apps em produção, não para demos por hobby. O objetivo é ajudar você a conectar o Gemini de um jeito que possa ser revisado por engenharia, operações e segurança antes da mudança de tráfego.
Resposta rápida: o que deve mudar em produção?
Para um rollout de produção da Gemini API, trave cinco coisas antes de salvar o upstream:
| Item | Configuração direta do Gemini | Configuração com um gateway para clientes CC Switch ou no estilo NewAPI |
|---|---|---|
| Origem da autenticação | Chave da API Gemini do Google AI Studio ou do projeto importado do Google Cloud | Uma chave do gateway gerenciada em um só lugar |
| URL base | https://generativelanguage.googleapis.com/v1beta/openai/ | https://router.flatkey.ai/v1 |
| Modo de protocolo | Compatível com OpenAI | Compatível com OpenAI |
| Política de modelos | Lista aprovada de modelos Gemini | Lista aprovada de modelos Gemini mais política de fallback entre provedores |
| Verificação | Checagens de uso e faturamento do lado da Google | Log de requisições do gateway, quota, mapeamento de modelos e revisão downstream |
Se o seu app já suporta upstreams compatíveis com OpenAI, o Gemini normalmente é uma tarefa de roteamento e política, e não uma reescrita completa do SDK.
Por que esta checklist importa na sexta-feira, 17 de julho de 2026
Três fatos atuais tornam uma checklist de produção mais importante do que um quickstart:
- Os docs do Gemini da Google agora oferecem explicitamente suporte ao acesso por bibliotecas OpenAI, o que facilita para as equipes trocar endpoints sem reforçar a disciplina de revisão.
- A Google também afirma que novas chaves do AI Studio são criadas como chaves de autenticação por padrão e que chaves padrão serão rejeitadas em setembro de 2026, então o tipo de chave e a propriedade do projeto fazem parte da decisão de rollout.
- A linguagem pública de configuração ao vivo da Flatkey foca em uma chave, uma URL base e em manter o SDK existente, o que só é útil se a equipe também padronizar o mapeamento de campos, o logging e o rollback.
Antes de começar
Não abra o CC Switch ou o NewAPI primeiro. Comece com o contrato que você quer que o upstream cumpra.
Use esta lista mínima de preflight:
| Verificação | O que confirmar | Por que isso importa |
|---|---|---|
| Responsável | A equipe sabe quem é responsável pela criação da chave Gemini, rotação e quota | Evita desvios em contas compartilhadas |
| Tipo de rota | Você está usando um upstream compatível com OpenAI, não um adaptador personalizado misto | Mantém o mapeamento de campos simples |
| Lista de modelos | Você tem uma lista aprovada de IDs de modelos Gemini para este app | Evita desvios silenciosos de alias |
| Registro | Você sabe onde acontecerão os logs de requisição, uso e revisão de faturamento | Necessário para evidência da migração |
| Reversão | Você pode voltar rapidamente para o upstream ou para a política de modelos anterior | Necessário para implantação em fases |
Se você não tiver essas respostas, não está pronto para tratar a configuração como pronta para produção.
Mapeamento de campos para upstreams no estilo CC Switch ou NewAPI
Clientes diferentes rotulam campos de maneiras diferentes, mas o mapeamento de produção deve permanecer consistente.
| Campo do upstream | Valor para esta implantação | Observação de revisão |
|---|---|---|
| Tipo de provedor | Compatível com OpenAI | Use o modo genérico compatível com OpenAI, a menos que o cliente tenha um modo Gemini nativo validado que você pretenda operar |
| Chave de API | Chave Flatkey ou chave upstream aprovada | Mantenha-a em uma única origem de segredo, não em cópias locais por usuário |
| URL base | https://router.flatkey.ai/v1 | Use uma única rota para controle centralizado |
| Origem do modelo | Allowlist manual ou busca após salvar a rota | Revise os IDs de modelo retornados antes de expô-los ao app |
| Modelo padrão | Modelo de produção Gemini aprovado | Não aponte a produção para um modelo de pré-visualização por engano |
| Modelo de fallback | Opcional e intencional | Ative somente após passarem as verificações de nomenclatura do modelo e dos logs |
| Cabeçalhos | Autenticação bearer padrão, a menos que seu cliente documente campos extras | Evite gambiarras pontuais de cabeçalho que quebrem a portabilidade |
| Revisão de uso | Log de requisição mais painel de quota ou faturamento | Deve fazer parte da aprovação final |
Esta é a principal diferença operacional entre uma configuração direta do Gemini e uma configuração com gateway: o caminho do gateway reduz a dispersão de credenciais, mas aumenta a necessidade de um gate de revisão limpo, porque mais apps podem herdar o mesmo upstream.
Etapa 1: decida se este app precisa de Gemini direto ou de um único gateway
Use Gemini direto se o app for isolado, o responsável estiver claro e você não precisar de roteamento entre provedores neste momento.
Use um único gateway se qualquer um destes for verdadeiro:
- O mesmo cliente já interage com vários provedores.
- Mais de um engenheiro ou equipe vai gerenciar a integração.
- Você quer um único lugar para verificar uso, quotas ou logs de requisição.
- Você espera substituição de modelo, fallback ou expansão de provedor no futuro.
Para equipes no estilo CC Switch e NewAPI, o segundo caminho costuma ser mais fácil de dar suporte לאורך do tempo porque o cliente mantém uma única forma compatível com OpenAI enquanto a política de roteamento permanece upstream.
Etapa 2: fixe os IDs exatos dos modelos Gemini que você permitirá
Não use "Gemini" como um requisito vago. Aprove IDs exatos de modelos para este app e este ambiente.
Essa revisão deve responder:
- Qual modelo Gemini é o padrão em produção?
- Quais modelos são permitidos apenas para testes?
- Modelos de preview são permitidos em produção de qualquer forma?
- O app exibirá um seletor de modelo ou um único modelo fixo?
- Se o fallback estiver ativado, quais modelos não Gemini são permitidos e em que condição?
É aqui que muitas equipes criam incidentes evitáveis. Elas salvam o upstream corretamente e depois deixam a nomenclatura dos modelos solta o suficiente para que teste e produção se comportem de forma diferente.
Se você precisar de ajuda para alinhar os nomes dos modelos depois que a rota estiver ativa, consulte o guia existente Migração de API compatível com OpenAI antes de expor a integração aos usuários.
Etapa 3: salve um upstream e execute um smoke test antes de buscar modelos
Depois de inserir a chave de API e a URL base, faça um smoke test antes de importar ou expor a lista completa de modelos.
Seu smoke test deve confirmar:
| Teste | Resultado esperado |
|---|---|
| Auth | O upstream aceita a chave sem erros locais de credenciais |
| Route | Uma solicitação simples de conclusão de chat retorna da URL base configurada |
| Model | O ID exato do modelo Gemini é resolvido com sucesso |
| Logging | Você consegue encontrar a solicitação na superfície de revisão escolhida |
| Billing or quota | A solicitação fica visível onde a equipe espera evidências de uso |
Para equipes que padronizam em um gateway, isso importa mais do que a busca de modelos. Buscar uma lista de modelos prova que o cliente consegue ver nomes. Não prova que o caminho da solicitação em produção é revisável.
Etapa 4: revise o tipo de chave e a propriedade do projeto
Esta etapa é fácil de pular porque a solicitação pode já estar funcionando.
A orientação atual do Google sobre chaves é o motivo para não pular. O Google AI Studio agora cria chaves de autenticação por padrão, chaves padrão sem restrição já estão sendo restringidas de forma mais agressiva, e o Google afirma que a Gemini API rejeitará chaves padrão em setembro de 2026. Isso significa que equipes de produção devem tratar o tipo de chave como parte da prontidão para o rollout, e não como uma tarefa posterior de limpeza.
Use esta breve revisão:
| Pergunta | Resposta aceitável |
|---|---|
| Quem é o proprietário do projeto Gemini? | Proprietário ou equipe nomeados |
| Qual tipo de chave está em uso? | Chave de autenticação preferida para novas configurações de produção |
| Onde a chave é armazenada? | Gerenciador de segredos central ou segredo controlado da plataforma |
| Como ela será rotacionada? | Proprietário e processo documentados |
| O que acontece se o uso disparar? | Existe um alerta de faturamento ou um caminho de revisão de quota |
Se você centraliza por meio de um gateway, faça a mesma revisão para a chave do gateway e a conta do provedor downstream.
Passo 5: decida se o app deve expor o Gemini diretamente aos usuários
Não presuma que a resposta seja sim.
Em muitos apps em produção, o padrão melhor é:
- Roteie o Gemini primeiro upstream.
- Valide logs, latência e revisão de uso.
- Mantenha o modelo atrás de uma flag de recurso ou de uma allowlist interna.
- Exponha-o aos usuários finais somente depois que o gate de revisão for aprovado.
Isso é especialmente útil em ambientes no estilo CC Switch e NewAPI, em que uma alteração de configuração pode afetar vários operadores ou caminhos do app.
Passo 6: adicione um gate de revisão em produção
Esta é a parte que a maioria dos guias de configuração deixa de fora. Antes de o tráfego ser movido, exija um breve gate de revisão que alguém possa aprovar em uma única passada.
Use esta checklist exata:
| Item do gate de revisão | Condição de aprovação |
|---|---|
| Mapeamento de campos | A origem da chave da API, a URL base, o modo do provedor e o modelo padrão estão documentados |
| Evidência de smoke test | Uma solicitação bem-sucedida é registrada com a rota final |
| Allowlist de modelos | Apenas IDs de modelos Gemini aprovados estão disponíveis para o app |
| Visibilidade de uso | O caminho de revisão de logs de solicitação ou de faturamento está confirmado |
| Propriedade do segredo | O responsável pela chave e o caminho de rotação estão nomeados |
| Rollback | É possível restaurar rapidamente a política anterior de upstream ou de modelo |
| Escopo | A equipe sabe se essa alteração afeta um app, um workspace ou vários clientes |
Este é o documento de configuração mais curto que ainda protege a implantação.
Passo 7: decida como o fallback deve funcionar antes de ativá-lo
Se você estiver usando um gateway, a tentação é ativar o fallback imediatamente. Não faça isso, a menos que consiga responder a duas perguntas:
- Qual condição de falha deve acionar o fallback?
- O comportamento do modelo de fallback é aceitável para a mesma tarefa voltada ao usuário?
Para lançamentos em produção do Gemini, o fallback costuma ser mais seguro após a primeira migração, não durante ela. Primeiro prove a rota principal, depois adicione o fallback com sua própria evidência de teste.
Passo 8: valide a rota a partir do app, não apenas de um script local
Um teste local com curl é necessário. Não é suficiente.
Execute uma validação pelo caminho real da aplicação e confirme:
- O app usa o upstream pretendido.
- O modelo retornado é o modelo Gemini esperado.
- A observabilidade mostra a mesma solicitação.
- Qualquer comportamento de timeout, retry ou quota no nível do app ainda funciona.
É aqui que surgem problemas em produção quando o app tem variáveis de ambiente antigas, nomes de modelos em cache ou uma fonte de segredo diferente da do engenheiro que executou o primeiro teste.
Lançamento recomendado para equipes no estilo CC Switch e NewAPI
Use um rollout em etapas que mantenha o plano de controle simples:
- Adicione um upstream compatível com OpenAI e capaz de usar Gemini.
- Teste um modelo Gemini aprovado.
- Confirme os logs e a revisão de uso.
- Exponha o modelo apenas para usuários internos.
- Adicione fallback somente depois que a rota principal estiver estável.
- Expanda para mais apps somente depois que o primeiro app passar pelo gate de revisão.
A mensagem de roteamento ao vivo da Flatkey é útil aqui porque a mesma URL base pode permanecer no lugar enquanto sua política de modelos se torna mais restritiva ao longo do tempo. Se você estiver comparando custo ou impacto de procurement antes do rollout, a página de preços ao vivo é a próxima verificação certa.
Documento curto de configuração que você pode aprovar internamente
Se você quiser um handoff revisável, copie esta estrutura para sua nota interna de configuração:
| Field | Value |
|---|---|
| App name | |
| Upstream owner | |
| Provider mode | OpenAI-compatible |
| Base URL | https://router.flatkey.ai/v1 |
| API key source | |
| Approved Gemini model IDs | |
| Fallback enabled | Yes or No |
| Usage review surface | |
| Billing or quota review surface | |
| Rollback action | |
| Reviewer | |
| Approval date |
Essa é estrutura suficiente para aprovar um rollout do Gemini sem transformar a configuração em um longo memorando de arquitetura.
Se sua equipe também usa Claude Code no mesmo plano de controle, o artigo ao vivo CC Switch Claude Code setup with Flatkey and NewAPI é um complemento útil porque mostra o mesmo padrão operacional do lado do cliente.
FAQ
Qual é o padrão de URL base mais seguro para um rollout de Gemini em produção em um cliente compatível com OpenAI?
O padrão mais seguro é uma URL base revisada por ambiente. Para acesso direto ao Gemini, o Google documenta https://generativelanguage.googleapis.com/v1beta/openai/. Para um rollout por gateway centralizado, use a única rota de gateway aprovada e mantenha esse valor sob controle de configuração.
Devo usar uma credencial Gemini separada para cada cliente CC Switch ou NewAPI?
Normalmente não. Para equipes em produção, uma única origem controlada de segredo é mais segura do que credenciais locais espalhadas. A compensação é que você precisa adicionar um gate de revisão porque mais clientes podem herdar a mesma rota.
Preciso substituir meu SDK para usar o Gemini em um app compatível com OpenAI?
Normalmente não. A documentação atual do Gemini do Google dá suporte explícito a bibliotecas OpenAI ao alterar a chave, a URL base e o nome do modelo. O trabalho real é validar a política de rota, a nomenclatura do modelo, o logging e a responsabilidade.
O que mudou sobre as chaves da API Gemini em 2026?
Em vigor a partir de sexta-feira, 17 de julho de 2026, o Google AI Studio cria novas chaves como chaves de autenticação por padrão, avisa que chaves padrão sem restrições não são aceitáveis para uso de longo prazo e afirma que a Gemini API rejeitará chaves padrão em setembro de 2026. As equipes devem revisar o tipo de chave antes da migração para produção.
Quando devo ativar o fallback para o Gemini?
Depois que a rota principal do Gemini estiver estável. Primeiro, verifique um modelo Gemini aprovado por meio do caminho final da aplicação. Em seguida, adicione fallback somente se a condição de disparo e o comportamento do modelo de backup forem aceitáveis para o mesmo fluxo de trabalho.
O que devo inspecionar antes de aprovar o documento de configuração?
Inspecione a URL base exata, a origem da chave, os IDs dos modelos Gemini aprovados, um log de solicitação bem-sucedida, a área de revisão de uso e a ação de reversão. Se qualquer um desses itens estiver ausente, a configuração não estará pronta para aprovação em produção.
