Gemini CLI com endpoint personalizado e modelos gratuitos
O Gemini CLI é o agente de programação de código aberto do Google para o terminal. Ele pode enviar as suas requisições para uma URL base personalizada. Este guia aponta o Gemini CLI para o FreeLLMAPI, que serve a API nativa do Gemini em /v1beta. Assim, as suas requisições vão para o seu conjunto de camadas gratuitas, que pode incluir chaves gratuitas da API Gemini.
O código, os nomes dos modelos e os rótulos do catálogo ao vivo são exibidos em inglês.
A mudança de 2026 no plano gratuito do Gemini CLI
Leia isto primeiro. O Google mudou o uso gratuito do Gemini CLI em 2026. A página de cotas do Gemini CLI diz: "Unpaid tier and Google One users: Gemini CLI was replaced by Antigravity CLI on June 18th, 2026."
O anúncio do Google diz que o Gemini CLI continua disponível com chaves pagas da API Gemini e para clientes corporativos.
- Login Google no plano gratuito: não é mais atendido pelo Gemini CLI para contas de consumidor.
- Chave da API Gemini com URL base personalizada: a referência de configuração do Gemini CLI ainda documenta
GOOGLE_GEMINI_BASE_URL. Com esta variável, o Gemini CLI envia as requisições para a URL que você definir, e não para o Google. - Chaves gratuitas da API Gemini: o Google AI Studio ainda lista uma camada gratuita para a API Gemini. O FreeLLMAPI pode usar essas chaves, junto com chaves de outros provedores.
Este guia usa o segundo método. O FreeLLMAPI responde às requisições e envia cada uma para um modelo gratuito do seu conjunto.
Etapa 1: instale o FreeLLMAPI e o Gemini CLI
Instalar os dois
curl -fsSL https://freellmapi.co/install.sh | bash
npm install -g @google/gemini-cliAbra http://localhost:3001. Adicione pelo menos duas chaves gratuitas de provedores na página Keys. Uma chave gratuita do Google AI Studio é uma boa primeira chave. Copie a sua chave unificada na mesma página.
Etapa 2: aponte o Gemini CLI para o gateway
Defina duas variáveis de ambiente e inicie o Gemini CLI. A URL base é a origem do servidor, sem /v1beta. O Gemini CLI adiciona o caminho da API por conta própria.
macOS ou Linux
export GOOGLE_GEMINI_BASE_URL=http://localhost:3001
export GEMINI_API_KEY=<unified-key>
geminiWindows PowerShell
$env:GOOGLE_GEMINI_BASE_URL="http://localhost:3001"
$env:GEMINI_API_KEY="<unified-key>"
geminiQuando o Gemini CLI pedir um método de autenticação, selecione Use Gemini API key. Para salvar a escolha, defina-a em ~/.gemini/settings.json:
~/.gemini/settings.json
{
"security": {
"auth": {
"selectedType": "gemini-api-key"
}
}
}GEMINI_API_KEY. Um issue do Gemini CLI relata que a versão 0.44.x falha com "Invalid auth method selected" quando GOOGLE_API_KEY é usada com GOOGLE_GEMINI_BASE_URL. Se GOOGLE_API_KEY estiver definida, remova-a com unset GOOGLE_API_KEY.Etapa 3: mapeie os nomes de modelos do Gemini para modelos gratuitos
O Gemini CLI pede nomes de modelos do Gemini, por exemplo gemini-2.5-flash. O FreeLLMAPI não envia esses nomes diretamente ao Google. Ele os resolve pelo mapa de famílias do Gemini, na aba Keys, Agents. Mapeie cada família (Pro, Flash e Flash-Lite) para Auto ou para um modelo fixo do catálogo.
- Com Auto, o roteador escolhe um modelo gratuito para cada requisição. Quando um provedor envia um erro 429, ele tenta o próximo.
- IDs do catálogo também funcionam como nomes de modelos. Inicie o Gemini CLI com
gemini -m <catalog-id>, ou definaGEMINI_MODEL. - O Gemini CLI é um agente com ferramentas. Mapeie as famílias para modelos com chamada de ferramentas e uma janela de contexto grande.
A primeira tabela mostra os modelos gratuitos do Gemini no catálogo de hoje. A segunda tabela mostra outros modelos gratuitos que você pode mapear para uma família do Gemini.
| Modelo | Gratuito em | Contexto | Limites gratuitos (melhor oferta) | Ferramentas | Visão |
|---|---|---|---|---|---|
| Gemini 3.8 Flash | Google AI Studio | 1M | Recurring provider quota | Sim | Sim |
| Gemini Flash (latest alias) | Google AI Studio | - | 10 req/min 20 req/dia 250,000 tokens/min ~3M | Sim | Sim |
| Gemini 3.7 Flash | Google AI Studio | 1M | 10 req/min 20 req/dia 250,000 tokens/min ~3M | Sim | Sim |
| Gemini 3.6 Flash | Google AI Studio | 1M | 10 req/min 20 req/dia 250,000 tokens/min ~3M | Sim | Sim |
| Gemini 3.5 Flash | Google AI Studio | 1M | 10 req/min 20 req/dia 250,000 tokens/min ~3M | Sim | Sim |
| Gemini 3.8 Live | Google AI Studio | - | 10 req/min 20 req/dia 250,000 tokens/min ~3M | Sim | Sim |
| Gemini 3.8 Live Extended Thinking | Google AI Studio | - | 10 req/min 20 req/dia 250,000 tokens/min ~3M | Sim | Sim |
| Gemini 3.5 Flash Lite | Google AI Studio | 1M | 15 req/min 20 req/dia 250,000 tokens/min ~3M | Sim | Sim |
Mostrando 8 de 14 modelos gratuitos correspondentes. Ver todos os modelos.
Dados ao vivo do catálogo FreeLLMAPI (versão 2026.11.19, verificado em 2026-11-19). Os limites gratuitos mudam com frequência. O catálogo é verificado todos os dias.
| Modelo | Gratuito em | Contexto | Limites gratuitos (melhor oferta) | Ferramentas | Visão |
|---|---|---|---|---|---|
| GLM 5.3 | UnoRouter | 1M | 1 req/min 1 req/min per model | Sim | Não |
| GLM 5.3 Flash | NVIDIA NIM, UnoRouter | 1M | 40 req/min 40 RPM | Sim | Sim |
| Qwen3.8 Flash Next | AMD Radeon Cloud | 262K | Recurring daily account allowance | Sim | Não |
| Qwen3.8 Flash | ElectronHub | 1M | $0.25/week shared recurring credit | Sim | Sim |
| GPT-5.6 Luna | ElectronHub | 1M | $0.25/week shared recurring credit | Sim | Sim |
| Dots3 Note Preview | Kilo Gateway, OpenRouter | 512K | 20 req/min 50 req/dia 50 req/day account-wide (1,000 after a $10 purchase) | Sim | Sim |
| DeepSeek V4 Flash | AMD Radeon Cloud, BazaarLink, ElectronHub | 1M | 10 req/min 50 req/dia Shared rate limit | Sim | Não |
| Qwen3.8 27B | ElectronHub, Groq, OVH AI Endpoints | 262K | 30 req/min 250 req/dia 70,000 tokens/min ~6M | Sim | Sim |
Mostrando 8 de 104 modelos gratuitos correspondentes. Ver todos os modelos.
Dados ao vivo do catálogo FreeLLMAPI (versão 2026.11.19, verificado em 2026-11-19). Os limites gratuitos mudam com frequência. O catálogo é verificado todos os dias.
Limites do plano gratuito do Gemini
A página de limites de taxa do Google diz que os limites se aplicam por projeto, e não por chave de API. Mais chaves em um mesmo projeto não dão mais cota. O Google também diz que os limites não são garantidos e que você pode ver os seus limites atuais no Google AI Studio. Modelos em preview têm limites menores.
Uma chave gratuita do Gemini Flash permite poucas requisições por dia. Uma tarefa do Gemini CLI pode enviar muitas requisições. Adicione chaves de outros provedores, para que o roteador continue quando a cota do Gemini acabar. A superfície nativa aceita generateContent, streamGenerateContent com ?alt=sse, countTokens e a lista de modelos.
O FreeLLMAPI aceita a chave no cabeçalho x-goog-api-key, como token Bearer ou no parâmetro de consulta ?key= do Gemini. Prefira o cabeçalho, porque uma chave em URL pode vazar para o histórico do shell e para os logs de proxy.
Solução de problemas
| Problema | Causa | Solução |
|---|---|---|
| O Gemini CLI abre um login Google | O tipo de autenticação não está definido como chave da API Gemini | Selecione Use Gemini API key, ou defina security.auth.selectedType |
| "Invalid auth method selected" | GOOGLE_API_KEY é usada com uma URL base personalizada | Use GEMINI_API_KEY e remova GOOGLE_API_KEY com unset |
| As requisições vão para o Google, não para o gateway | GOOGLE_GEMINI_BASE_URL não está definida neste shell | Exporte a variável e inicie gemini de novo |
404 nas chamadas de modelo | A URL base inclui /v1beta | Use somente a origem http://localhost:3001 |
| Chamadas de ferramentas falham | A família do Gemini aponta para um modelo com chamada de ferramentas fraca | Mapeie a família para um modelo das tabelas acima |
| "All models rate-limited after N attempts" (mensagem em inglês) | Todas as chaves estão no limite | Adicione chaves de mais provedores, ou espere os períodos de espera |
Perguntas frequentes
O Gemini CLI ainda é gratuito?
O Google encerrou o uso gratuito do Gemini CLI com login Google para usuários sem plano pago e usuários do Google One, em 18 de junho de 2026. A CLI ainda aceita uma URL base personalizada, então pode rodar em um gateway gratuito como o FreeLLMAPI.
Como uso o Gemini CLI com um endpoint personalizado?
Defina GOOGLE_GEMINI_BASE_URL como a origem do endpoint e GEMINI_API_KEY como a chave dele, depois selecione Use Gemini API key. O endpoint precisa falar a API nativa do Gemini em /v1beta.
O Gemini CLI pode usar modelos que não são do Gemini?
Sim, por meio do FreeLLMAPI. O gateway mapeia os nomes das famílias Gemini Pro, Flash e Flash-Lite para Auto ou para qualquer modelo do catálogo, por exemplo um modelo Qwen ou GLM.
Quais são os limites do plano gratuito da API Gemini?
O Google define os limites por projeto, e não por chave, e mostra os valores atuais no Google AI Studio. A tabela desta página mostra os modelos gratuitos do Gemini de hoje e os limites deles, a partir do catálogo do FreeLLMAPI.
Por que recebo 'Invalid auth method selected'?
Um issue do Gemini CLI relata este erro na versão 0.44.x quando GOOGLE_API_KEY é usada com GOOGLE_GEMINI_BASE_URL. Use GEMINI_API_KEY e remova GOOGLE_API_KEY com unset.
Guias relacionados
- free gemini api
- Cota da API Gemini excedida (429 RESOURCE_EXHAUSTED)
- Como usar o Claude Code gratuitamente
- Use o Codex CLI com modelos gratuitos
- Melhores APIs gratuitas de modelos para código
Fontes
- Gemini CLI docs: configuration reference (verificado em 20 November 2026)
- Gemini CLI docs: authentication (verificado em 20 November 2026)
- Gemini CLI docs: quota and pricing (verificado em 20 November 2026)
- Google Developers Blog: transitioning Gemini CLI to Antigravity CLI (verificado em 20 November 2026)
- Gemini CLI issue 27550: auth with a custom base URL (verificado em 20 November 2026)
- Google AI Studio: rate limits (verificado em 20 November 2026)
- FreeLLMAPI docs: native Gemini API (verificado em 20 November 2026)