「API key not valid. Please pass a valid API key.」 — Gemini가 이 메시지로 의미하는 다섯 가지

이 메시지는 Google의 포괄적인 오류 메시지입니다. 전송한 키를 이 호출에 사용할 수 없다는 뜻입니다. 키 자체가 잘못되었다는 뜻은 아니며, 다섯 가지 원인 중 네 가지에서는 키 자체가 완전히 유효합니다. 따라서 키를 다시 복사하는 것은 대개 시간 낭비입니다.

오류

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" }]
  }
}

원인과 해결 방법 한눈에 보기

원인	해결 방법
키가 속한 프로젝트에서 Generative Language API가 활성화되지 않음	해당 프로젝트에서 API를 활성화한 다음 1분 정도 기다리세요 — 방금 활성화된 API는 짧은 시간 동안 요청을 거부합니다.
AI Studio 엔드포인트에 Vertex AI 자격 증명을 전송함	Vertex는 지역 호스트에 대해 OAuth를 사용하고, generativelanguage.googleapis.com은 AI Studio API 키를 요구합니다. 둘은 서로 바꿔 사용할 수 없습니다.
키에 HTTP 리퍼러 또는 IP 제한이 설정되어 있습니다	서버 측 호출은 리퍼러를 전송하지 않습니다. IP로 제한하거나, 백엔드에서 사용할 제한 없는 키를 발급하세요.
키가 잘못된 위치로 전송되었습니다	Gemini는 `x-goog-api-key` 또는 `?key=`를 읽습니다. `Authorization: Bearer` 헤더는 무시되므로 키 없이 요청이 도착합니다.
키가 삭제되었거나, 생각한 것과 다른 Google 계정에서 발급되었습니다	키를 재발급하면 해결되는 유일한 원인입니다. AI Studio에 로그인된 계정을 확인하세요.

먼저 키 자체를 단독으로 검증하세요

애플리케이션을 수정하기 전에 키를 단순한 요청에 넣어 보세요. 이 요청은 성공하지만 앱은 실패한다면 키는 정상이고, 문제는 앱이 키를 전송하는 방식에 있습니다. 이렇게 하면 가장 흔한 세 가지 원인을 한 번에 배제할 수 있습니다.

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

클라이언트가 실제로 전송하는 헤더를 확인하세요

대부분의 OpenAI 형태 SDK는 자격 증명을 `Authorization: Bearer`에 넣습니다. Gemini 네이티브 API는 이 헤더를 읽지 않으므로, OpenAI 클라이언트를 generativelanguage.googleapis.com에 직접 연결하면 완전히 정상인 키로도 정확히 이 오류가 발생합니다. Google SDK를 사용하거나, bearer 형식을 요구하는 OpenAI 호환 엔드포인트를 호출하세요.

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)

400과 403을 구분하세요

키가 올바르게 전송된 후 이유가 PERMISSION_DENIED로 바뀐다면, 키를 읽기는 했지만 범위가 거부된 것입니다. 이는 다른 해결책이 필요한 별개의 문제입니다(키 형식이 아니라 프로젝트 권한 문제). 400에서 403으로 바뀐 것은 회귀가 아니라 진전입니다.

Kunavo를 통해 호출하는 경우

Kunavo에서 Gemini 제품군은 다른 모든 기능과 동일한 OpenAI 형태의 엔드포인트와 `sk-kn-` 키를 통해 일반 bearer 토큰으로 전송됩니다. 따라서 위의 헤더 불일치 및 Vertex와 AI Studio 간 차이 원인은 여기에서 발생할 형태 자체가 없습니다. 활성화해야 할 Google 프로젝트도 없고, 문제를 일으킬 키별 리퍼러 정책도 없습니다. 사용자가 책임져야 할 것은 키가 활성 상태이고 잔액이 충전되어 있는지뿐입니다. 거부된 요청에는 요금이 청구되지 않습니다. 토큰별 Gemini 요금은 다음에서 확인할 수 있습니다 Gemini 요금 안내.

자주 묻는 질문

방금 키를 만들었는데도 여전히 유효하지 않다고 표시됩니다.

새로 활성화한 API나 새로 만든 키를 사용하면 최대 1~2분 정도 요청이 거부될 수 있습니다. 그 이후에도 지속된다면 키가 잘못된 것이 아니라 프로젝트에 Generative Language API가 없을 가능성이 매우 높습니다.

할당량이 소진되었다는 뜻인가요?

아니요. 할당량 소진은 429 RESOURCE_EXHAUSTED로 표시되고, 결제 문제는 403으로 나타납니다. 400 API_KEY_INVALID는 크레딧 부족을 의미하지 않습니다.

같은 키가 AI Studio에서는 작동하는데 코드에서는 작동하지 않는 이유는 무엇인가요?

AI Studio는 Google 자체 오리진에서 호출합니다. 리퍼러 제한 키는 이를 허용하지만, 리퍼러를 전혀 전송하지 않는 서버는 거부합니다.