Para chamar o Gemini por código você precisa de uma chave API Gemini: uma credencial que o Google gera e que identifica a sua conta em cada requisição. O caminho mais curto para conseguir essa chave é o Google AI Studio: você entra com a conta Google, cria a chave e copia. O que costuma confundir vem depois — existe uma camada gratuita com limites, existe um caminho pago cobrado em dólar, e existe um segundo produto do Google, o Vertex AI, que atende os mesmos modelos por outra porta.
Este guia cobre os dois caminhos, o passo a passo da chave no AI Studio, como testar em um comando só, o que a camada gratuita resolve e o que muda quando o projeto sai do teste. No fim há uma seção sobre usar o Gemini pela Roteia, pagando em Real. O guia funciona inteiro sem essa parte.
O que é a API do Gemini e onde ela vive
Gemini é a família de modelos de IA do Google. A API é a porta para usar esses modelos fora do chat: o seu código envia um texto e recebe a resposta em JSON, dentro do seu produto.
O Google oferece dois caminhos para a mesma família de modelos. O Google AI Studio é a porta simples: conta Google, chave em poucos passos, camada gratuita para testar e nenhuma infraestrutura para configurar. O Vertex AI é a porta corporativa, dentro do Google Cloud, com projeto, permissões de IAM, escolha de região e faturamento do Cloud — mais controle e mais configuração antes da primeira chamada.
Escolha pelo destino. Protótipo, script pessoal ou primeiro teste: AI Studio. Aplicação que já roda dentro do Google Cloud, com política de acesso e exigência de região: Vertex AI. As chaves e os endpoints são diferentes entre os dois, então código escrito para um não sobe direto no outro.
- AI Studio: chave simples, camada gratuita, endereço aistudio.google.com.
- Vertex AI: projeto e permissões do Google Cloud, endereço console.cloud.google.com.
- Você reconhece em qual dos dois está apenas olhando o endereço no navegador.
Como gerar a chave no Google AI Studio, passo a passo
O fluxo tem cinco passos. Os nomes dos botões mudam de tempos em tempos e a interface aparece em inglês para muita gente, então leia pelo sentido e não pelo texto exato.
O Google associa a chave a um projeto do Google Cloud. Se você nunca criou um, a própria tela oferece criar na hora — aceite, é o caminho normal.
A chave completa aparece uma vez, no momento da criação. Copie antes de fechar a janela. As chaves de API do Google costumam começar com AIza, o que ajuda a reconhecê-las depois em um arquivo de configuração.
- Abra aistudio.google.com e entre com a sua conta Google.
- Aceite os termos de uso da API quando a tela pedir.
- Procure a opção de chave de API no menu (aparece como Get API key ou Chave de API).
- Crie a chave escolhendo um projeto existente ou deixando o Google criar um novo.
- Copie a chave e guarde-a fora do navegador antes de fechar a tela.
Teste a chave com uma chamada real
Antes de escrever qualquer código de aplicação, confirme que a chave funciona. Um comando no terminal resolve. Exporte a chave na sessão atual com export GEMINI_API_KEY="sua-chave" e rode o comando abaixo.
Troque MODELO pelo identificador exato do modelo que você viu na documentação do Google. Não invente o nome: cada versão tem um ID próprio e um ID errado devolve erro mesmo com a chave certa. O endereço e a versão do endpoint também saem da documentação do Google — confirme lá antes de colar.
Resposta com status 200 e um JSON contendo candidates significa chave válida e modelo acessível. Erro 400 costuma ser corpo malformado ou campo obrigatório ausente. Erro 403 costuma ser chave errada, chave restrita ou API não habilitada no projeto. Erro 404 aponta para um modelo que não existe com aquele nome. Erro 429 é limite de requisições, e esse assunto é a próxima seção.
curl "https://generativelanguage.googleapis.com/v1beta/models/MODELO:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"parts": [{"text": "Responda apenas: chave funcionando"}]}]
}'A camada gratuita do Gemini e seus limites
O Google AI Studio tem uma camada gratuita, e ela é suficiente para desenvolver. Ela não é ilimitada. O acesso é controlado por limite de requisições por minuto, por limite diário e por volume de tokens, e cada modelo tem o seu próprio teto.
Não colocamos os números aqui de propósito. Eles mudam com frequência, variam por modelo e variam conforme o seu projeto está ou não vinculado a faturamento. Um número copiado para um artigo envelhece; a página de limites de requisição da documentação do Google, não.
Um ponto que costuma passar batido: o Google documenta condições diferentes de tratamento de dados entre a camada gratuita e a paga. Se o seu prompt carrega dado de cliente, leia os termos antes de mandar, não depois.
Na prática, a camada gratuita cobre protótipo, prova de conceito, teste de prompt e script interno de baixo volume. Ela não cobre produção com pico de tráfego, porque o estouro chega no meio do fluxo e a sua aplicação precisa saber tratar isso. Confira o teto que vale para a sua chave na página de limites da documentação do Google, e confirme na prática: quando o teto estoura, a API responde 429.
Como guardar a chave API Gemini com segurança
Uma chave de API é uma senha. Quem tem a sua chave gasta na sua conta, e no modelo pago isso vira fatura. Trate como credencial de produção desde o primeiro dia.
Um erro comum e caro é colocar a chave no front-end. Qualquer pessoa abre o inspecionar do navegador e lê. Se o seu produto é acessado por usuários finais, a chamada ao Gemini sai do seu backend, sempre.
Outro erro comum é o commit. A chave entra no repositório dentro de um arquivo de teste, o repositório vira público meses depois, e o vazamento já era antigo quando alguém percebeu.
- Guarde a chave em variável de ambiente, nunca escrita direto no código.
- Coloque o arquivo .env no .gitignore antes de criar o .env.
- Use uma chave por projeto e outra por ambiente, com nomes que deixem produção óbvia.
- Aplique restrições à chave no Google Cloud, limitando quais APIs ela pode chamar.
- Se a chave vazou, apague e crie outra. Trocar a chave é barato; investigar consumo estranho não é.
- Antes do próximo commit, rode um git grep AIza no repositório e confirme que não volta nada.
O que muda quando o Gemini sai do teste e vai para produção
Sair da camada gratuita significa vincular uma conta de faturamento do Google Cloud ao projeto da sua chave. A partir daí o consumo passa a ser cobrado por token, com preço em dólar, na tabela publicada pelo Google.
Para quem opera no Brasil, isso tem três consequências práticas. A cobrança chega convertida na fatura do cartão internacional, com o câmbio do dia e os tributos que incidem sobre compra em moeda estrangeira, ou seja, o valor final é maior que o preço de tabela. O documento fiscal é emitido por uma empresa de fora, o que complica conciliação e crédito para quem tem contabilidade brasileira. E o custo do mês só fica conhecido depois de fechado, porque depende do câmbio de cada dia.
Tem também o operacional: alguém precisa manter um cartão com limite internacional válido, e a fila de chamadas para no dia em que o pagamento falha. Isso não é defeito do Gemini, é como funciona qualquer API paga contratada fora do país.
Faça a conta antes de subir volume. Pegue o consumo de tokens de um dia representativo de teste, multiplique pelo preço por token da tabela do Google e converta pelo câmbio de hoje. Esse número, e não a impressão de que a camada gratuita dá conta, é o que decide a arquitetura.
Gemini pela Roteia: mesma chamada, saldo em Real
A Roteia é um gateway brasileiro de APIs de IA. Uma chave, uma URL base, e o modelo escolhido no corpo da requisição — no formato compatível com a API da OpenAI. O saldo é pré-pago em Real, a recarga é por Pix, boleto ou cartão conforme a disponibilidade no painel, a NFS-e é emitida mediante solicitação e o suporte é em português, em suporte@roteia.ai.
Vale ser exato sobre o que muda. O formato da chamada deixa de ser o do Google e passa a ser o compatível com OpenAI, o que costuma economizar código em quem já integra vários modelos. O custo aparece em Real no painel, requisição a requisição. O que não muda: o modelo é do Google e continua sendo do Google. Quais modelos Gemini estão liberados hoje é pergunta para o catálogo, em /modelos/ — não afirmamos aqui que um modelo específico está disponível, porque a lista se move.
A Roteia é independente e não pertence nem representa OpenAI, Anthropic, Google, DeepSeek ou OpenRouter. Se o Google AI Studio resolve o seu caso e o cartão internacional não é um problema na sua operação, fique nele. A Roteia faz sentido para quem quer uma chave só para vários modelos, cobrança em Real e nota fiscal brasileira.
Para conferir por conta própria: preços em /precos/, catálogo em /modelos/, o passo a passo completo em /docs/primeira-chamada/ e a documentação geral em /docs/. Quem vem do OpenRouter tem um checklist em /docs/migrar-openrouter/. A chave se cria em https://app.roteia.ai.
curl https://api.roteia.ai/v1/chat/completions \
-H "Authorization: Bearer $ROTEIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "cole-aqui-o-id-do-catalogo",
"messages": [{"role":"user","content":"Responda apenas: integração concluída"}]
}'Dúvidas frequentes
Como conseguir a chave da API do Gemini?
Entre em aistudio.google.com com uma conta Google, aceite os termos da API e abra a opção de chave de API no menu. Crie a chave escolhendo um projeto do Google Cloud existente ou deixando o Google criar um novo. A chave completa aparece só no momento da criação, então copie e guarde antes de fechar a tela.
A API do Gemini é gratuita?
Existe uma camada gratuita no Google AI Studio, com limite de requisições por minuto, limite diário e teto de tokens, e esses limites variam por modelo. Ela dá conta de protótipo e teste, mas não de produção com pico de tráfego. Os números atuais ficam na página de limites de requisição da documentação do Google, porque mudam com frequência.
Qual a diferença entre Google AI Studio e Vertex AI?
O Google AI Studio é o caminho simples: conta Google, chave em poucos passos e camada gratuita para testar. O Vertex AI é o caminho corporativo dentro do Google Cloud, com projeto, permissões de IAM, escolha de região e faturamento do Cloud. Os dois atendem a mesma família de modelos, mas usam chaves e endpoints diferentes, então o código de um não sobe direto no outro.
Preciso de cartão internacional para usar a API do Gemini?
Para a camada gratuita, não. Para o uso pago, sim: é preciso vincular uma conta de faturamento do Google Cloud ao projeto da chave, e a cobrança é feita em dólar. O valor chega convertido na fatura do cartão internacional, com o câmbio do dia e os tributos de compra no exterior, e o documento fiscal vem de uma empresa de fora do Brasil.
Onde encontro minha chave API Gemini depois de criada?
A chave completa é exibida uma única vez, quando é criada. Depois disso, a lista de chaves no Google AI Studio mostra o registro e o projeto associado, mas não o valor inteiro. Se você perdeu a chave, o caminho é apagar aquela e gerar uma nova, o que também é o procedimento correto quando há suspeita de vazamento.
Dá para usar o Gemini pagando em Real?
Sim, por um gateway com operação brasileira. A Roteia é um gateway de APIs de IA com saldo pré-pago em Real, recarga por Pix, boleto ou cartão conforme a disponibilidade no painel, NFS-e mediante solicitação e chamada no formato compatível com a API da OpenAI. Quais modelos Gemini estão liberados deve ser conferido no catálogo em roteia.ai/modelos/, porque a lista muda.
O que fazer quando a API do Gemini retorna erro 429?
O erro 429 indica que o limite de requisições da sua chave foi atingido, seja o limite por minuto, seja o diário. A correção não é repetir a chamada imediatamente: é espaçar as tentativas com intervalo crescente, reduzir o paralelismo ou revisar qual modelo está sendo usado, já que os tetos variam por modelo. Se o volume for constante, o caminho é sair da camada gratuita.
Onde confirmar
Plataforma de terceiro muda de tela e de limite sem avisar. Confira na fonte oficial antes de tomar decisão baseada nesta página.