"Chave de API inválida. Passe uma chave de API válida." — as cinco coisas que o Gemini quer dizer com isso

Esta mensagem é o aviso genérico do Google: a chave enviada não pôde ser usada nesta chamada. Isso não é o mesmo que a chave estar errada, e quatro das cinco causas deixam a própria chave perfeitamente válida — por isso copiá-la novamente geralmente é perda de tempo.

O erro

response (HTTP 400)

{
  "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
A Generative Language API não está habilitada no projeto da chave	Habilite-a nesse projeto e aguarde um minuto — APIs recém-habilitadas rejeitam chamadas durante um curto período.
Uma credencial do Vertex AI enviada ao endpoint do AI Studio	O Vertex usa OAuth com um host regional; generativelanguage.googleapis.com espera uma chave de API do AI Studio. Eles não são intercambiáveis.
A chave contém restrições de referenciador HTTP ou IP	Chamadas do lado do servidor não enviam referenciador. Restrinja por IP ou emita uma chave sem restrições para uso no backend.
Chave enviada no lugar errado	O Gemini lê `x-goog-api-key` ou `?key=`. Um cabeçalho `Authorization: Bearer` é ignorado, então a requisição chega sem chave.
Chave excluída ou de uma conta do Google diferente da que você imagina	A única causa em que emitir outra chave ajuda. Verifique em qual conta o AI Studio está conectado.

Comprove primeiro a chave isoladamente

Antes de mexer na sua aplicação, use a chave em uma requisição simples. Se ela funcionar e seu app não, a chave está correta e o problema está na forma como o app a transmite — eliminando de uma só vez as três causas mais comuns.

check-key.sh

curl -s -H "x-goog-api-key: $GEMINI_API_KEY" \
  "https://generativelanguage.googleapis.com/v1beta/models" \
  | head -20

# 200 + a model list  -> the key is valid; look at your client
# 400 API_KEY_INVALID -> the key really cannot call this API

Leia qual cabeçalho seu cliente realmente envia

A maioria dos SDKs no formato da OpenAI coloca as credenciais em `Authorization: Bearer`. A API nativa do Gemini não lê esse cabeçalho, então apontar um cliente OpenAI diretamente para generativelanguage.googleapis.com produz exatamente este erro com uma chave perfeitamente válida. Use o SDK do Google ou chame um endpoint compatível com OpenAI que espere o formato bearer.

openai_shape.py

from openai import OpenAI

# Bearer auth, OpenAI request shape, Gemini model names.
client = OpenAI(
    api_key=KUNAVO_API_KEY,
    base_url="https://api.kunavo.com/v1",
)

print(client.chat.completions.create(
    model="gemini-2-5-flash",
    messages=[{"role": "user", "content": "ping"}],
).choices[0].message.content)

Separe 400 de 403

Se o motivo mudar para PERMISSION_DENIED quando a chave for transmitida corretamente, a chave está sendo lida e rejeitada por escopo — um problema diferente, com uma correção diferente (permissões do projeto, não formato da chave). Passar de 400 para 403 é progresso, não regressão.

Se você estiver chamando pela Kunavo

No Kunavo, o Gemini fica atrás do mesmo endpoint no formato da OpenAI e usa a mesma chave `sk-kn-` que todo o resto, enviada como um token bearer normal — portanto, as causas de incompatibilidade de cabeçalho e Vertex versus AI Studio acima simplesmente não podem ocorrer dessa forma. Não há um projeto do Google para habilitar nem uma política de referenciador por chave com a qual se deparar. O que continua sendo sua responsabilidade é a chave estar ativa e a carteira ter saldo; uma requisição rejeitada não é cobrada. As tarifas do Gemini por token estão em nosso guia de preços do Gemini.

Perguntas frequentes

Acabei de criar a chave e ela ainda aparece como inválida.

APIs recém-habilitadas e chaves recém-criadas podem ser rejeitadas por até um ou dois minutos. Se persistir depois disso, quase certamente falta a Generative Language API no projeto, e não há um problema com a chave.

Isso significa que fiquei sem cota?

Não. O esgotamento da cota é 429 RESOURCE_EXHAUSTED, e problemas de cobrança aparecem como 403. Um 400 API_KEY_INVALID nunca significa que você ficou sem crédito.

Por que a mesma chave funciona no AI Studio, mas não no meu código?

As chamadas do AI Studio vêm da própria origem do Google. Uma chave restrita por referenciador permite essa origem e recusa seu servidor, que não envia referenciador algum.

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.