Como obter uma chave da Google Gemini API (2026): crie, teste e proteja sua chave para produção
Para obter uma chave da Google Gemini API, entre no Google AI Studio com uma conta Google, aceite os termos, abra a página Chaves de API e clique em Criar chave de API; novos usuários recebem automaticamente um projeto padrão do Google Cloud e uma chave. Criar uma chave é gratuito, e vários modelos Gemini, incluindo Gemini 3.8 Flash e Gemini 3.5 Flash-Lite, oferecem um nível gratuito. Desde 28 de maio de 2026, toda nova chave criada no AI Studio é uma "chave de autorização" vinculada a uma conta de serviço, e a Gemini API rejeita chaves antigas sem restrições. Por isso, uma chave que funcionava no ano passado pode precisar ser substituída (documentação de chaves de API do Google, consultada em 27 de outubro de 2026).
Este guia é para desenvolvedores independentes e equipes pequenas que querem colocar uma chave Gemini para funcionar em minutos e usá-la com segurança em produção. Ele aborda as etapas, os novos tipos de chave, o nível gratuito, uma primeira requisição com curl, Python e Node.js, os erros mais comuns e um checklist para produção. Se você está comparando custos, nosso guia de preços da Gemini API traz a tabela completa.
Como obter uma chave da Gemini API, passo a passo
- Abra o Google AI Studio. Acesse aistudio.google.com/apikey e entre com a conta Google que você quer usar para o faturamento ou como proprietária do projeto.
- Aceite os termos. Se você é um novo usuário, o AI Studio cria um projeto padrão do Google Cloud e uma chave de API depois que você aceita os Termos de Serviço. Você pode renomear o projeto depois, na visualização Projetos.
- Escolha ou importe um projeto. Se você já usa o Google Cloud, o AI Studio não cria um projeto padrão. Abra Painel → Projetos → Importar projetos e selecione o projeto do Cloud desejado.
- Crie a chave. Na página Chaves de API, clique em Criar chave de API e escolha o projeto. Por padrão, novas chaves são chaves de autorização.
- Copie a chave e armazene-a imediatamente. Coloque-a em uma variável de ambiente ou em um gerenciador de segredos, sem salvá-la em um arquivo do repositório.
- Aplique restrições. Se a chave for chamar apenas o Gemini, mantenha a restrição à Gemini API (Generative Language API). Se ela for usada a partir de servidores fixos, adicione restrições de IP no console do Google Cloud.
- Teste a chave com uma das requisições abaixo.
Etapas baseadas em Como usar chaves da Gemini API, do Google AI for Developers, com última atualização em 27 de outubro de 2026.
Onde posso encontrar minha chave de API do Google depois?
No Google AI Studio, abra Painel → Chaves de API. O AI Studio exibe até 100 chaves e 50 projetos e lista apenas chaves sem restrições ou restritas à Gemini API. Chaves restritas a outras APIs do Google aparecem somente na página de credenciais do console do Google Cloud. Se um projeto não aparecer, importe-o primeiro.
Chaves padrão vs. chaves de autorização: o que mudou em 2026
O Google está migrando a Gemini API das chaves de API padrão para chaves de autorização (auth). Segundo a documentação oficial (27 de outubro de 2026):
| Chave de API padrão | Chave de autorização | |
|---|---|---|
| A que está vinculada | A um projeto do Google Cloud, para faturamento e cota | A uma conta de serviço do Google Cloud |
| Identifica quem faz a chamada | Não | Sim, as requisições são executadas como a conta de serviço vinculada |
| Escopo padrão | Depende das restrições adicionadas | Restrita à Gemini API por padrão |
| Tratamento de chaves vazadas | Manual | Aplicação rápida de medidas que interrompem o uso de chaves vazadas detectadas pelo Google |
| Criada pelo AI Studio | Antes de 28 de maio de 2026 | A partir de 28 de maio de 2026 |
| Ainda funciona? | Somente com restrições explícitas | Sim |
O que isso significa na prática:
- Chaves padrão sem restrições são rejeitadas. Se uma chave antiga não tiver restrições de API, as requisições ao Gemini falharão. Para corrigir no AI Studio, passe o cursor sobre o aviso da chave e escolha Restringir apenas à Gemini API. Você precisa da permissão
apikeys.keys.update. - Chaves sem restrições que ficaram inativas são bloqueadas. Desde 7 de maio de 2026, chaves sem restrições que não são usadas por um período prolongado exibem a etiqueta Bloqueada. Crie uma nova chave e configure seu app para usá-la.
- Novo prefixo de chave. Desenvolvedores relatam que as novas chaves de autorização não começam mais com o conhecido prefixo
AIza(relato de exemplo). Se uma ferramenta de terceiros valida chaves pelo prefixo, ela pode rejeitar uma nova chave válida. Atualize a ferramenta em vez de voltar a usar uma chave padrão. - Permissões para criar chaves. Se o botão Criar indicar que você não tem permissão, o administrador do Cloud precisa atribuir a você um papel com
apikeys.keys.create,serviceusage.services.enable,iam.serviceAccounts.createeiam.serviceAccountApiKeyBindings.create, entre outras permissões. Sem acesso de administrador, você pode criar um novo projeto que não faça parte de uma organização.
Configure a chave como variável de ambiente
As bibliotecas cliente do Google leem GEMINI_API_KEY ou GOOGLE_API_KEY automaticamente. Se ambas estiverem definidas, GOOGLE_API_KEY tem prioridade, uma causa comum de "minha nova chave não está sendo usada".
# macOS / Linux (add to ~/.zshrc or ~/.bashrc, then open a new terminal)
export GEMINI_API_KEY="paste-your-key-here"
# Make sure an old key is not overriding it
unset GOOGLE_API_KEY
No Windows, adicione GEMINI_API_KEY em Propriedades do Sistema → Variáveis de Ambiente e abra um novo terminal.
Teste sua chave da Gemini API
curl (Interactions API)
O guia de início rápido atual do Google usa o endpoint Interactions com a chave no cabeçalho x-goog-api-key:
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
"model": "gemini-3.8-flash",
"input": "Reply with the single word: ok"
}'
Uma resposta JSON com texto de saída indica que a chave, o projeto e o acesso ao modelo estão funcionando. Um 403 geralmente significa que a chave está restrita a outras APIs ou bloqueada; um 429 indica que você atingiu um limite de requisições (veja abaixo).
Python (SDK google-genai)
# pip install google-genai
from google import genai
client = genai.Client() # reads GEMINI_API_KEY from the environment
interaction = client.interactions.create(
model="gemini-3.8-flash",
input="Explain what an API key is in one sentence.",
)
print(interaction.output_text)
Node.js (@google/genai)
// npm install @google/genai
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
const interaction = await ai.interactions.create({
model: "gemini-3.8-flash",
input: "Explain what an API key is in one sentence.",
});
console.log(interaction.output_text);
Use a mesma chave com o SDK da OpenAI
O Gemini também oferece um endpoint compatível com a OpenAI. Isso é útil para ferramentas que só aceitam uma URL base da OpenAI, como muitos agentes de programação e aplicativos de chat:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
resp = client.chat.completions.create(
model="gemini-3.8-flash",
messages=[{"role": "user", "content": "Say ok"}],
)
print(resp.choices[0].message.content)
Para configurar cada ferramenta por meio de um único gateway, consulte Gemini API por meio de um roteador compatível com a OpenAI.
A chave da Gemini API é gratuita?
A chave é gratuita, assim como um nível gratuito com uso limitado. A página de preços do Google (consultada em 27 de outubro de 2026) descreve três planos: Gratuito, Pago e Empresarial. O nível gratuito oferece tokens de entrada e saída sem custo em determinados modelos, mas o conteúdo enviado no nível gratuito é usado para melhorar os produtos do Google. No nível pago, isso não acontece. Não envie dados de clientes usando uma chave do nível gratuito.
| Modelo | Nível gratuito | Entrada / saída pagas por 1M de tokens (Padrão) |
|---|---|---|
| Gemini 4 Argon | Indisponível | $2.00 / $10.00 até 30 de novembro de 2026; $4.00 / $20.00 a partir de 1 de dezembro de 2026 |
| Gemini 3.8 Flash | Sim | $0.75 / $3.75 até 31 de dezembro de 2026; $1.50 / $7.50 a partir de 1 de janeiro de 2027 |
| Gemini 3.5 Flash-Lite | Sim | $0.30 / $2.50 |
| Gemini 3.1 Flash-Lite | Sim | $0.25 / $1.50 (texto, imagem, vídeo) |
Fonte: Preços da Gemini Developer API, 27 de outubro de 2026. Observe os aumentos de preço programados: inclua as tarifas mais altas no orçamento se seu app continuar em operação após essas datas.
Como usar a Gemini API gratuitamente
- Crie uma chave no AI Studio sem vincular uma conta de faturamento. O projeto permanece no nível Gratuito.
- Use um modelo que tenha nível gratuito, como
gemini-3.8-flashougemini-3.5-flash-lite. O Gemini 4 Argon está disponível apenas no nível pago. - Respeite os limites de requisições do nível gratuito exibidos no AI Studio. Os limites se aplicam por projeto, não por chave, então criar mais chaves no mesmo projeto não aumenta a cota.
- Use apenas dados de teste ou públicos, pois o conteúdo do nível gratuito pode ser usado para melhorar os produtos do Google.
Limites de requisições e níveis
Os limites da Gemini API são medidos em requisições por minuto (RPM), tokens de entrada por minuto (TPM) e requisições por dia (RPD). Exceder qualquer um deles gera um erro, e o limite de RPD é reiniciado à meia-noite no horário do Pacífico (limites de requisições, 27 de outubro de 2026). O Google também aplica limites baseados em gastos em uma janela móvel de 10 minutos, que retornam 429 RESOURCE_EXHAUSTED.
| Nível | Requisitos | Teto do nível de faturamento |
|---|---|---|
| Gratuito | Projeto ativo ou teste gratuito | N/A |
| Nível 1 | Vincular uma conta de faturamento ativa | $250 |
| Nível 2 | Ter pago $100 + 3 dias desde o primeiro pagamento bem-sucedido | $2,000 |
| Nível 3 | Ter pago $1,000 + 30 dias desde o primeiro pagamento bem-sucedido | $20,000 a $100,000+ |
Fonte: Limites de requisições da Gemini API, 27 de outubro de 2026. Confira os limites exatos por modelo no AI Studio; o Google informa que os limites listados não são garantidos.
O que alguém pode fazer com sua chave de API?
Qualquer pessoa que tenha sua chave Gemini pode enviar requisições cobradas do seu projeto e consumir sua cota. A documentação do Google alerta que uma chave vazada pode resultar em "cobranças inesperadas" e acesso a dados privados do projeto. Com uma chave de autorização, o invasor atua como a conta de serviço vinculada e pode acessar tudo o que essa conta tiver permissão para acessar (boas práticas para chaves de API do Google Cloud). Por isso, você deve manter as permissões da conta de serviço no mínimo necessário.
Se você suspeita que uma chave vazou:
- Crie uma chave substituta no AI Studio.
- Implante a nova chave no app e confirme que ela funciona.
- Desative a chave antiga no console do Cloud. Não a exclua antes de colocar a nova em uso, ou você causará indisponibilidade.
- Verifique o faturamento e o uso da API no console do Cloud para identificar tráfego desconhecido. A página Uso do AI Studio agrupa o tráfego que não consegue associar a uma chave nomeada como "(chaves desconhecidas)".
Solução de problemas: por que sua chave da Gemini API não funciona
| Sintoma | Causa provável | Solução |
|---|---|---|
403 ou "Chave de API inválida" com uma chave antiga |
Chave padrão sem restrições, agora rejeitada | Restrinja a chave apenas à Gemini API ou crie uma nova chave de autorização |
| A chave aparece como Bloqueada no AI Studio | Chave sem restrições que ficou inativa, bloqueada desde 7 de maio de 2026 | Crie uma nova chave e atualize seu app |
| A nova chave é ignorada pelo código | GOOGLE_API_KEY também está definida e tem prioridade |
Remova essa variável ou configure-a com a nova chave |
| Uma ferramenta de terceiros informa que o formato da chave está incorreto | A ferramenta espera o prefixo antigo | Atualize a ferramenta ou encaminhe as chamadas por um gateway compatível com a OpenAI |
| "Você não tem permissão para criar uma chave" | Faltam permissões de IAM no projeto do Cloud | Peça ajuda a um administrador ou use um projeto fora da organização |
429 RESOURCE_EXHAUSTED |
Limite de RPM, TPM, RPD ou de gastos | Tente novamente com espera progressiva, reduza o tamanho da requisição ou passe para um nível superior |
| Modelo não encontrado ou indisponível | O modelo não faz parte do nível gratuito (por exemplo, Gemini 4 Argon) | Vincule uma conta de faturamento ou escolha um modelo do nível gratuito |
Para padrões de tratamento de erros entre provedores, consulte nossa taxonomia de erros de gateways de LLM.
Checklist de produção para uma chave da Gemini API
Uma chave que funciona em um notebook ainda não está pronta para atender usuários. Antes do lançamento:
- Mantenha a chave no servidor. Nunca a distribua em um app web ou móvel; o Google informa que chaves no código do cliente podem ser extraídas. Coloque um pequeno proxy no backend entre seu cliente e o Gemini.
- Use uma chave por ambiente e por app. Separe as chaves de desenvolvimento, homologação e produção para poder revogar uma sem interromper os outros ambientes. Dê nomes claros a elas.
- Armazene a chave em um gerenciador de segredos. O Google recomenda o Secret Manager para produção. Carregue a chave em tempo de execução.
- Restrinja por API e, quando possível, por IP. Uma chave de autorização é restrita ao Gemini por padrão; adicione restrições de IP para backends fixos.
- Limite as permissões da conta de serviço. Não conceda à conta de serviço vinculada papéis abrangentes de que ela não precisa.
- Ative alertas de faturamento no console do Google Cloud para ficar sabendo de um pico de gastos antes de receber a fatura.
- Fixe os IDs dos modelos. Use IDs exatos, como
gemini-3.8-flash, na configuração e planeje-se para as mudanças de preço em 1 de dezembro de 2026 e 1 de janeiro de 2027. - Use o nível pago para dados de usuários. O conteúdo do nível gratuito pode ser usado para melhorar os produtos do Google.
- Planeje como lidar com os limites de requisições. Adicione espera exponencial entre novas tentativas para erros
429e decida o que acontece quando um limite é atingido: colocar na fila, recorrer a um modelo menor ou usar uma alternativa em caso de falha. - Verifique os repositórios em busca de chaves vazadas. Ative a verificação de segredos do GitHub e a proteção de push.
- Troque as chaves periodicamente. Crie a nova chave, implante, verifique e só então desative a antiga.
Para uma análise mais aprofundada, use nosso checklist de preparação da Gemini API para produção e nosso guia de gerenciamento seguro de chaves de API.
Quando uma única chave Flatkey simplifica mais do que uma chave Gemini
Se seu app também chama Claude, GPT, DeepSeek ou Qwen, gerenciar uma chave, uma conta de faturamento e um nível de limites de requisições separados por provedor dá mais trabalho. A Flatkey oferece uma única chave e uma URL base compatíveis com a OpenAI (https://router.flatkey.ai/v1) para o Gemini e outros modelos, com registros de uso por chave (documentação da Flatkey). Avalie com transparência a diferença de preço, que varia por modelo. Em 27 de outubro de 2026, as páginas de modelos da Flatkey listavam:
| Modelo | Preço de tabela do Google (Padrão) | Flatkey |
|---|---|---|
| Gemini 4 Argon | $2.00 / $10.00 | $1.60 / $8.00 |
| Gemini 3.5 Flash-Lite | $0.30 / $2.50 | $0.24 / $2.00 |
| Gemini 3.8 Flash | $0.75 / $3.75 (promoção até 31 de dezembro de 2026) | $1.20 / $6.00 |
Para o Gemini 3.8 Flash, o preço promocional do Google é menor que o da Flatkey até 31 de dezembro de 2026. Portanto, um app que usa apenas Flash gasta menos chamando o Google diretamente até essa data. A Flatkey faz mais sentido para Argon, Flash-Lite ou apps que combinam provedores.
from openai import OpenAI
import os
client = OpenAI(api_key=os.environ["FLATKEY_API_KEY"], base_url="https://router.flatkey.ai/v1")
resp = client.chat.completions.create(
model="gemini-4-argon",
messages=[{"role": "user", "content": "Summarize this stack trace in one line."}],
)
print(resp.choices[0].message.content)
Perguntas frequentes
Como obtenho uma chave da Google Gemini API?
Entre em aistudio.google.com/apikey, aceite os termos, escolha ou importe um projeto do Google Cloud e clique em Criar chave de API. Novos usuários recebem automaticamente um projeto padrão e uma chave. A chave aparece na página Chaves de API do AI Studio.
A chave da Gemini API é gratuita?
Sim. Criar uma chave não custa nada, e modelos como Gemini 3.8 Flash e Gemini 3.5 Flash-Lite têm um nível gratuito com limites de requisições. O conteúdo do nível gratuito pode ser usado para melhorar os produtos do Google, e o Gemini 4 Argon não está disponível gratuitamente.
Como uso a Gemini API gratuitamente?
Crie uma chave sem vincular uma conta de faturamento, chame um modelo do nível gratuito, como gemini-3.8-flash, e respeite os limites exibidos no AI Studio. Os limites são por projeto, então chaves adicionais no mesmo projeto não aumentam a cota.
Onde encontro minha chave de API do Google?
No Google AI Studio, em Painel → Chaves de API. Chaves restritas a APIs do Google que não sejam a Gemini API aparecem apenas na página de credenciais do console do Google Cloud.
O que alguém pode fazer com minha chave de API?
Essa pessoa pode fazer requisições cobradas do seu projeto, consumir sua cota e, com uma chave de autorização, atuar como a conta de serviço vinculada. Se suspeitar de um vazamento, substitua a chave, implante a nova, desative a antiga e revise o uso.
Por que minha chave antiga da Gemini API parou de funcionar?
Desde 2026, a Gemini API rejeita chaves padrão sem restrições e, desde 7 de maio de 2026, bloqueia chaves sem restrições que ficaram inativas por muito tempo. Restrinja a chave à Gemini API ou crie uma nova chave de autorização.
Posso usar uma chave da Gemini API com o SDK da OpenAI?
Sim. Defina a URL base como https://generativelanguage.googleapis.com/v1beta/openai/ e passe sua chave Gemini como chave de API.
Conclusão
Obter uma chave Gemini leva dois minutos no AI Studio; mantê-la segura exige um pouco mais. Use uma chave de autorização, armazene-a no servidor em um gerenciador de segredos, aplique restrições, configure alertas de faturamento, use o nível pago para dados reais de usuários e acompanhe as mudanças de preço programadas. Se você usa vários provedores, uma única chave de gateway pode substituir um conjunto de chaves individuais. Compare modelos no catálogo de modelos da Flatkey e consulte o guia de roteamento Gemini vs. Claude para saber quando direcionar o tráfego a cada um.
