"API key not valid. Please pass a valid API key." — a frase menos útil do Gemini. A chave geralmente É válida; algo ao redor dela está errado: uma restrição de referenciador, a Generative Language API não habilitada ou uma chave do AI Studio enviada a um endpoint do Vertex. Siga a lista abaixo na ordem.
O erro
{
"error": {
"code": 400,
"message": "API key not valid. Please pass a valid API key.",
"status": "INVALID_ARGUMENT",
"details": [{ "reason": "API_KEY_INVALID" }]
}
}Causas e soluções em resumo
| Causa | Solução |
|---|---|
| Restrições da chave (referenciador HTTP / IP) bloqueando chamadas do servidor | No Google Cloud Console → Credentials, uma chave restrita por referenciador rejeita solicitações do lado do servidor. Use uma chave sem restrições ou restrinja por API. |
| Generative Language API não habilitada no projeto | Habilite a "Generative Language API" para chaves no estilo do AI Studio. |
| Incompatibilidade entre chave do AI Studio e endpoint do Vertex AI | Chaves AIza… chamam generativelanguage.googleapis.com; o Vertex usa OAuth/contas de serviço em outro host. Não as misture. |
| Região não compatível | As chaves do AI Studio não funcionam em todos os países; verifique a disponibilidade ou roteie por um gateway. |
| Configuração da variável de ambiente (aspas/espaços/nome incorreto) | imprima repr(key) dentro do processo que falha; exporte novamente de forma limpa. |
Teste a chave isoladamente
Um curl contra o endpoint REST informa se a própria chave está correta:
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"contents":[{"parts":[{"text":"ping"}]}]}' | head -c 400Verifique as restrições e as APIs habilitadas
Cloud Console → APIs & Services → Credentials: abra a chave. Se Application restrictions disser "HTTP referrers", as chamadas do servidor retornarão 400 — mude para None ou para uma restrição baseada em IP. Em seguida, confirme que a Generative Language API está habilitada no mesmo projeto.
Se você precisar de uma chave para muitos modelos mesmo assim
Se estiver alternando entre chaves do Gemini, Claude e GPT, um gateway compatível com OpenAI as reúne em uma única credencial — o mesmo código, uma base_url e nenhum projeto do Google Cloud necessário.
Se você estiver chamando pela Kunavo
O Kunavo disponibiliza Gemini 2.5 Flash e Pro pelo mesmo endpoint compatível com OpenAI e pela mesma chave sk-kn usada para Claude e GPT — sem projeto do Google Cloud, sem restrições de chave para depurar e funcionando em regiões onde as chaves do AI Studio não são oferecidas. As tarifas ficam bem abaixo do preço de tabela do Google, e a configuração exige três campos em qualquer SDK da OpenAI.
Perguntas frequentes
Minha chave do Gemini funciona localmente, mas falha em produção — por quê?
Geralmente por restrições de referenciador/IP (os IPs de produção não estão autorizados), um arquivo de ambiente diferente em produção ou o projeto de produção não ter a Generative Language API habilitada. Compare a representação da chave e o ID do projeto entre os ambientes.
A API do Gemini é gratuita?
O AI Studio tem um nível gratuito com cotas rigorosas por minuto; o tráfego de produção exige faturamento habilitado (ou um gateway). Se você estiver recebendo erros de cota, e não de chave, consulte nosso guia de RESOURCE_EXHAUSTED.
Guias relacionados
Mais detalhes sobre o significado dos erros estão em referência de erros; obter uma chave leva um minuto por meio de cadastro e da guia de autenticação.