Gemini API 키가 작동하지 않음 — API_KEY_INVALID와 다섯 가지 원인

"API key not valid. Please pass a valid API key."는 Gemini의 가장 도움이 되지 않는 문장입니다. 키 자체는 보통 유효합니다. 리퍼러 제한, Generative Language API 미활성화, Vertex 엔드포인트에 AI Studio 키를 전송하는 문제 등 주변 설정이 잘못된 것입니다. 아래 목록을 순서대로 확인하세요.

오류

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

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

원인	해결 방법
서버 호출을 차단하는 키 제한(HTTP referrer / IP)	Google Cloud Console → Credentials에서 리퍼러 제한 키는 서버 측 요청을 거부합니다. 제한 없는 키를 사용하거나 API별로 제한하세요.
프로젝트에서 Generative Language API가 활성화되지 않음	AI Studio 방식 키에 대해 "Generative Language API"를 활성화하세요.
AI Studio 키와 Vertex AI 엔드포인트 불일치	AIza… 키는 generativelanguage.googleapis.com을 호출하고 Vertex는 다른 호스트에서 OAuth/서비스 계정을 사용합니다. 서로 바꿔 사용하지 마세요.
지원되지 않는 지역	AI Studio 키는 모든 국가에서 작동하지 않습니다. 제공 지역을 확인하거나 게이트웨이를 통해 라우팅하세요.
환경 변수 연결 문제(따옴표/공백/잘못된 변수 이름)	실패하는 프로세스 내부에서 print(repr(key))를 실행하고 깨끗하게 다시 내보내세요.

키를 단독으로 테스트하세요

REST 엔드포인트에 curl 한 번을 보내면 키 자체가 정상인지 알 수 있습니다.

test-gemini-key.sh

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 400

제한 및 활성화된 API 확인

Cloud Console → APIs & Services → Credentials에서 키를 여세요. Application restrictions가 "HTTP referrers"라면 서버 호출은 400을 반환합니다. None 또는 IP 기반으로 변경하세요. 그런 다음 동일한 프로젝트에서 Generative Language API가 활성화되어 있는지 확인하세요.

어쨌든 여러 모델에 하나의 키가 필요하다면

Gemini + Claude + GPT 키를 함께 관리한다면 OpenAI 호환 게이트웨이로 하나의 자격 증명으로 통합할 수 있습니다. 동일한 코드, 하나의 base_url, Google Cloud 프로젝트 불필요라는 장점이 있습니다.

Kunavo를 통해 호출하는 경우

Kunavo는 Claude 및 GPT와 동일한 OpenAI 호환 엔드포인트와 sk-kn 키 뒤에서 Gemini 2.5 Flash와 Pro를 제공합니다. Google Cloud 프로젝트나 디버깅해야 할 키 제한이 필요 없으며 AI Studio 키가 제공되지 않는 지역에서도 작동합니다. 요금은 Google 목록 가격보다 훨씬 낮고, 모든 OpenAI SDK에서 설정은 세 필드뿐입니다.

자주 묻는 질문

Gemini 키가 로컬에서는 작동하지만 프로덕션에서 실패하는 이유는 무엇인가요?

대개 리퍼러/IP 제한(프로덕션 IP가 허용되지 않음), 프로덕션에서 다른 환경 파일을 사용하는 경우, 또는 프로덕션 프로젝트에서 Generative Language API가 활성화되지 않은 경우입니다. 환경 간 키의 repr과 프로젝트 ID를 비교하세요.

Gemini API는 무료인가요?

AI Studio에는 분당 할당량이 엄격한 무료 등급이 있습니다. 프로덕션 트래픽에는 결제 활성화가 필요하거나 게이트웨이를 사용해야 합니다. 키 오류가 아니라 할당량 오류가 발생한다면 RESOURCE_EXHAUSTED 가이드를 확인하세요.