Google AI Studio API 키 설정: 만든 뒤 6가지 실행 조건을 확인하세요

Google AI Studio의 API Keys 화면에서 Gemini API 키를 만들 수 있습니다. 하지만 키가 발급되었다는 사실만으로 첫 API 요청이 성공하는 것은 아닙니다. 실제 실행 가능성은 그 키가 연결된 Google Cloud 프로젝트, 사용 지역, billing 또는 Free Tier 상태, 호출할 모델, active limits, 그리고 키가 안전하게 보관되는지에 의해 결정됩니다.

코드를 고치거나 새 키를 여러 개 만들기 전에 아래 6가지를 먼저 확인하세요.

Google AI Studio API 키는 어디서 만들어야 하나

공식 경로는 Google AI Studio API Keys에 로그인해 새 Google Cloud 프로젝트를 만들거나 기존 프로젝트를 선택한 뒤 Gemini API key를 생성하는 방식입니다. Google의 Gemini API key 문서는 Gemini API를 사용하려면 API key가 필요하고, key가 Google Cloud 프로젝트와 연결된다는 점을 명확히 설명합니다.

이 프로젝트 연결을 가볍게 보면 setup이 계속 꼬입니다. API key는 독립된 비밀번호가 아니라 프로젝트의 권한, billing, usage, quota, 복구 경로를 끌고 오는 credential입니다. AI Studio에서 만든 key가 기본 프로젝트에 속할 수도 있고, 팀원이 보내 준 key가 팀원의 프로젝트에 속할 수도 있습니다. 따라서 오류를 보기 전에 먼저 “이 key가 어느 프로젝트의 key인가”를 확인해야 합니다.

처음 생성된 key는 한 번만 복사해 안전한 위치에 보관합니다. Google 문서는 초기 테스트에서 key를 잠깐 hardcode할 수 있다고 설명하지만, client-side code, 공개 저장소, 모바일 앱 패키지, 스크린샷, issue, 채팅 로그에 넣는 것은 setup이 아니라 사고입니다. 개발 환경에서는 GEMINI_API_KEY 또는 GOOGLE_API_KEY 같은 환경 변수를 사용하고, 배포 환경에서는 secret manager나 서버 전용 환경 변수를 사용합니다.

AI Studio에서 특정 제한 key가 보이지 않을 때도 프로젝트를 다시 확인해야 합니다. Google은 AI Studio가 unrestricted key 또는 Generative Language API로 제한된 key를 표시한다고 설명합니다. 더 세밀한 key restriction은 Google Cloud Console에서 관리해야 합니다. 버튼을 못 찾는 것보다 더 흔한 실수는 다른 프로젝트 화면을 보고, 다른 key를 복사하고, browser에 노출되는 환경 변수를 서버 key처럼 사용하는 것입니다.

키 생성 후 확인할 6가지 실행 조건

Gemini API key를 만들었다면 다음 단계는 “코드 실행”이 아니라 “실행 조건 확인”입니다. 첫 요청 실패는 코드 문법보다 프로젝트, 지역, billing, 모델, 제한, 보안 상태에서 나오는 경우가 많습니다.

확인 순서도 중요합니다. 먼저 프로젝트를 맞춰야 billing과 quota 화면이 같은 대상을 가리킵니다. 그다음 지역을 봅니다. 지역이 맞지 않으면 SDK나 prompt를 바꿔도 결과가 달라지지 않습니다. 이후 billing / Free Tier와 모델 상태를 확인합니다. 마지막으로 active limits와 key 보안을 봅니다. 이 두 영역은 “어제는 됐는데 오늘은 안 됨” 같은 증상에서 자주 등장합니다.

Gemini API 무료 범위나 실제 한도만 깊게 확인하려면 Gemini API 무료 티어 한도: 지금도 무료인 범위, 실제 quota 확인 위치, 결제를 켜야 하는 기준을 함께 봐야 합니다. 여기서는 key 생성부터 첫 요청까지의 readiness chain을 다룹니다. 오래된 quota 표를 다시 베끼는 방식은 피합니다.

환경 변수에 넣고 작은 첫 요청을 보내기

첫 테스트의 목적은 멋진 demo가 아니라 세 가지를 확인하는 것입니다. 애플리케이션이 key를 읽는지, 프로젝트가 대상 모델을 호출할 수 있는지, 현재 제한이 작은 요청까지 막고 있지는 않은지 확인하면 됩니다.

local shell에서는 다음처럼 최소 환경 변수를 둡니다.

hljs bash复制
export GEMINI_API_KEY="실제 key는 local 또는 server 환경 변수에만 둡니다"
export MODEL_ID="현재 Google model docs에서 고른 모델 ID"

처음 요청은 작고 반복 가능해야 합니다. 아래 형태는 key를 환경 변수에서 읽고, 모델 ID를 코드 안에 오래된 값으로 박아 두지 않으며, request body를 짧게 유지하는 것이 핵심입니다.

hljs bash复制
curl "https://generativelanguage.googleapis.com/v1beta/models/${MODEL_ID}:generateContent?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          { "text": "Reply with one short sentence." }
        ]
      }
    ]
  }'

공식 SDK를 써도 원칙은 같습니다. key는 환경 변수에서 읽고, model ID는 현재 문서에서 확인한 값으로 구성하고, 첫 요청은 짧게 보낸 뒤 context, files, tools, batch, retry, concurrency를 천천히 늘립니다. 새 key 하나에 실제 사용자 traffic, 긴 문서 처리, batch job, frontend 호출, retry queue를 동시에 올리면 실패 원인을 분리하기 어렵습니다.

frontend 프로젝트에서는 반드시 멈춰서 구조를 다시 봐야 합니다. Gemini API key는 비용과 권한이 연결된 credential입니다. NEXT_PUBLIC_ 변수, browser bundle, mobile package, 공개 정적 파일, 사용자에게 다운로드되는 JavaScript에 넣으면 누구나 가져갈 수 있습니다. 안전한 구조는 browser가 backend에 요청하고, backend가 private environment variable에서 key를 읽어 Gemini API를 호출하는 형태입니다.

무료로 key를 만드는 것과 무료 사용은 다르다

API key를 만드는 행위 자체와 API 사용 비용은 같은 문제가 아닙니다. key는 credential이고 quota pool이 아닙니다. Google의 rate limits 문서는 제한을 프로젝트와 모델 상태로 봐야 하며 active limits는 AI Studio에서 확인해야 한다는 방향을 줍니다. 같은 프로젝트 안에서 key를 여러 개 만들어도 일반적으로 같은 프로젝트 제한을 공유합니다.

Google의 billing 문서는 Free Tier와 Paid Tier를 구분합니다. 새 사용자는 Free Tier에서 시작할 수 있지만 사용할 수 있는 모델과 조건이 제한됩니다. Paid Tier는 활성 billing account가 필요하고 prepay가 필요할 수 있습니다. 현재 공식 billing 화면에는 새 setup에서 최소 10 USD prepay가 필요할 수 있다는 설명도 있으므로, 금액과 조건은 배포 직전에 공식 화면에서 다시 확인해야 합니다.

학습, 낮은 빈도의 prototype, 내부 실험에는 Free Tier가 충분할 수 있습니다. 외부 사용자가 있는 기능, 안정적인 처리량, 민감한 data, client demo, 장기 서비스, 반복적인 429가 있는 작업이라면 paid project, budget alert, data boundary, failover 계획을 먼저 세워야 합니다. 무료 범위는 검증에 적합하지만 capacity planning을 대신하지 않습니다.

지역과 403은 경로별로 나누어 봐야 한다

지역 문제는 반드시 제품 경로별로 판단해야 합니다. Gemini 웹 앱, Gemini mobile app, Google AI Studio, Gemini API, Vertex AI는 같은 조건표를 공유하지 않습니다. API key 설정에서는 Google AI Studio / Gemini API available regions를 기준으로 봅니다.

2026년 4월 27일 기준 공식 Gemini API available regions에는 Taiwan이 포함되어 있습니다. Mainland China, Hong Kong, Macao는 AI Studio/Gemini API 지원 목록에서 보이지 않습니다. 이 경계는 Google AI Studio / Gemini API 경로에 대한 판단입니다. Gemini 웹, mobile app, Workspace, Vertex AI의 가능 여부를 여기서 그대로 추론하면 안 됩니다.

403 PERMISSION_DENIED가 나오면 먼저 owner 상태와 경로 조건을 봅니다. Google의 troubleshooting 문서는 wrong key, insufficient permission, unsupported free-tier region, authentication mismatch 같은 방향을 제시합니다. 확인 순서는 key가 올바른 프로젝트에 속하는지, 지역과 Free Tier 조건이 맞는지, billing이 필요한지, 대상 모델이 프로젝트에서 사용 가능한지, 인증 방식이 해당 API 경로와 맞는지입니다.

더 넓은 Gemini 지역 오류를 겪는다면 Gemini를 이 지역에서 사용할 수 없을 때는 웹, 앱, API를 먼저 나누세요를 참고하세요. 그 주제는 웹, 앱, API, Vertex, gateway를 분리하는 문제입니다. 여기서는 AI Studio API key와 Gemini API 첫 호출 안에서만 판단합니다.

429, 사용할 수 없는 모델, 유출된 key의 복구 순서

429 RESOURCE_EXHAUSTED는 보통 rate limit 또는 quota exhaustion을 뜻합니다. 요청 수만 볼 것이 아니라 token, concurrency, model, project tier, daily limit, retry storm을 함께 봐야 합니다. Google rate limits 문서는 RPM, TPM, RPD 같은 차원을 설명하고, RPD reset은 Pacific Time 기준으로 돌아갈 수 있음을 다룹니다. 실제 capacity는 프로젝트와 모델 상태에 따라 달라질 수 있습니다.

복구는 비용이 낮은 순서로 진행합니다.

1. AI Studio에서 현재 key가 속한 프로젝트를 확인합니다.
2. active limits에서 RPM, TPM, RPD 중 무엇이 닿았는지 봅니다.
3. concurrency를 낮추고 exponential backoff를 넣으며 무의미한 retry를 멈춥니다.
4. prompt를 줄이고, 반복 요청은 cache하고, batch 작업을 나눕니다.
5. 대상 모델이 Paid Tier 또는 더 높은 usage tier를 요구하는지 확인합니다.
6. 정상 traffic에서도 계속 막히면 quota increase 또는 billing이 연결된 프로젝트를 검토합니다.

모델을 사용할 수 없다는 오류가 나오면 예전 tutorial에서 비슷해 보이는 model ID를 가져오지 않습니다. Google의 models 문서는 현재 모델 상태를 확인하는 기준입니다. 예를 들어 Gemini 3 Pro Preview는 2026년 3월 9일 shut down되었고 Google은 Gemini 3.1 Pro Preview로 migration하라고 안내했습니다. 안정적인 설정은 역사적인 ID를 외우는 것이 아니라, model ID를 구성 값으로 두고 현재 docs에서 사용 가능한 모델을 선택하는 것입니다.

key가 유출되면 “조심해서 계속 쓰기”가 아니라 rotation입니다. Google troubleshooting은 유출된 API key가 Google에 의해 차단될 수 있다고 설명합니다. 복구 순서는 새 key 생성, server environment variable 또는 secret manager 교체, 공개 위치의 old key 제거, usage와 billing 이상 여부 확인, old key 비활성화 또는 삭제입니다.

보안은 마지막 정리가 아니라 setup의 일부입니다. 공개 Git repo, frontend bundle, screenshot, issue, log, third-party online tool에 key가 들어갔다면 leaked key로 처리합니다. 제대로 설정된 key는 세 가지 질문에 답해야 합니다. 누가 읽을 수 있는가, 어디에서 사용량을 볼 수 있는가, 유출되면 누가 언제 교체하는가.

AI Studio, Vertex AI, Android Studio, gateway는 다른 경로다

많은 tutorial이 Google AI Studio, Gemini API, Vertex AI, Android Studio, third-party gateway를 한 흐름처럼 보여 줍니다. 실제로는 서로 다른 계약입니다.

현재 작업의 기본값은 공식 AI Studio API key 경로입니다. Google Cloud IAM, regional endpoint, enterprise governance, organization policy가 필요하면 Vertex AI를 별도로 평가합니다. 제3자 gateway가 필요할 수도 있지만, 그것은 공식 Google 경로가 아니라 별도의 provider contract입니다. gateway 존재를 지역 제한이나 billing 조건이 사라졌다는 증거로 쓰면 안 됩니다.

최종 준비 체크리스트

설정 완료는 화면에 key 문자열이 나타난 순간이 아닙니다. 아래 질문에 모두 답할 수 있어야 첫 요청을 실제 설정으로 봅니다.

이 표에서 하나라도 답하지 못한다면 key는 “생성됨” 상태에 가깝고 “실행 준비 완료” 상태는 아닙니다. 먼저 8개 질문을 닫은 뒤 application에 연결하면 오류가 줄고, 실패해도 원인을 훨씬 빠르게 좁힐 수 있습니다.

자주 묻는 질문

Google AI Studio API key는 무료인가요?

key 생성 자체는 보통 비용이 들지 않습니다. 하지만 key는 무료 사용권이 아닙니다. 실제 비용과 사용 가능성은 모델, 프로젝트, 지역, Free Tier, billing, active limits에 따라 달라집니다.

GEMINI_API_KEY와 GOOGLE_API_KEY 중 무엇을 써야 하나요?

Google의 API key 문서는 Gemini API libraries가 GEMINI_API_KEY 또는 GOOGLE_API_KEY를 사용할 수 있다고 설명합니다. 팀에서는 하나의 변수명을 정하고, 배포 문서에 key source, scope, rotation 절차를 같이 적는 편이 안전합니다.

같은 프로젝트에 API key를 여러 개 만들면 quota가 늘어나나요?

늘어난다고 보면 안 됩니다. quota와 billing은 key 문자열이 아니라 Google Cloud 프로젝트와 모델, usage tier에 연결됩니다. 여러 key는 environment separation, rotation, permission management에는 쓸 수 있지만 active limits 우회 수단이 아닙니다.

방금 만든 key가 바로 403을 내는 이유는 무엇인가요?

key가 다른 프로젝트에 속했거나, permission이 부족하거나, region 또는 Free Tier 조건이 맞지 않거나, billing이 필요하거나, 인증 방식이 해당 API 경로와 맞지 않을 수 있습니다. 프로젝트, 지역, billing, 모델 순서로 확인하는 것이 빠릅니다.

어제 되던 호출이 오늘 429가 되는 이유는 무엇인가요?

RPM, TPM, RPD 중 하나가 닿았거나 retry가 폭증했거나 model, project tier, daily usage가 바뀌었을 수 있습니다. AI Studio의 active limits를 보고 concurrency, backoff, prompt size, cache를 조정해야 합니다.

Mainland China, Hong Kong, Macao에서 Google AI Studio / Gemini API를 직접 쓸 수 있나요?

2026년 4월 27일 기준 이 세 지역은 공식 Google AI Studio / Gemini API available regions 목록에서 보이지 않습니다. Taiwan은 목록에 있습니다. 지역 지원은 변할 수 있으므로 배포 전 공식 페이지를 다시 확인해야 합니다.

Gemini 웹이 열리면 Gemini API key도 사용할 수 있나요?

그렇지 않습니다. Gemini web app, mobile app, AI Studio, Gemini API, Vertex AI는 지역, account, billing, compliance 경계가 다릅니다. API key 설정은 Google AI Studio / Gemini API 문서를 기준으로 판단해야 합니다.

key가 유출된 뒤 계속 써도 되나요?

권장되지 않습니다. Google은 유출된 key를 차단할 수 있습니다. 새 key를 만들고 server environment variable 또는 secret manager를 교체한 뒤, 공개 위치의 old key를 제거하고 usage와 billing 이상 여부를 확인해야 합니다.

Vertex AI와 AI Studio API key 중 무엇을 선택해야 하나요?

개인 개발, prototype, 빠른 backend 연결은 AI Studio / Gemini API key부터 시작하는 것이 보통 더 간단합니다. GCP IAM, organization policy, regional endpoint, enterprise governance가 필요하면 Vertex AI를 별도 경로로 평가합니다.

code sample에는 어떤 model ID를 고정해야 하나요?

오래된 preview ID를 고정하지 않습니다. 현재 Google model docs에서 사용 가능한 모델을 확인하고, 프로젝트, 지역, billing 상태에 맞는 model ID를 환경 변수나 설정 파일에 둡니다. 모델 상태가 바뀌면 code deploy 없이 설정을 바꿀 수 있어야 합니다.