Google AI Studio에서 API 키를 만드는 데는 몇 분이면 충분합니다. 하지만 복사한 문자열만 있으면 끝난 것은 아닙니다. 키가 내가 관리하는 Google Cloud 프로젝트에 속하고, client code 밖에 보관되며, 한 번의 최소 Gemini Developer API 요청에서 성공 또는 진단 가능한 오류를 얻어야 실제로 운영할 수 있습니다.
API 키는 Gemini 소비자 구독이 아니며, 키마다 별도 무료 쿼터가 생기는 상품도 아닙니다. 프로젝트에 연결된 인증 수단입니다.
먼저 계정과 프로젝트를 맞춘다
Google의 현재 AI Studio와 Gemini API 지원 지역에서 실제 사용 지역을 확인합니다. 대한민국은 2026년 8월 29일 확인한 목록에 포함되어 있습니다. 다만 국가가 보인다는 사실이 개별 계정의 18세 이상, 연령 확인, 조직 정책, 결제 적격성까지 보장하지는 않습니다. AI Studio가 계정에 표시하는 안내도 충족해야 합니다.
그다음 Google AI Studio API Keys를 해당 프로젝트를 소유하거나 정당하게 관리할 계정으로 엽니다. 회사 서비스라면 개인 Gmail이 아니라 조직이 billing, IAM, rotation, revoke를 계속 관리할 수 있는 계정을 선택합니다.
현재 Gemini API 키 문서에 따르면 신규 사용자는 약관 동의 후 기본 Cloud 프로젝트와 API 키를 자동으로 받을 수 있습니다. 이미 Google Cloud를 사용하는 계정은 기본 프로젝트가 생성되지 않을 수 있으며, Dashboard → Projects → Import projects에서 대상 프로젝트를 가져온 뒤 API Keys 화면에서 키를 생성합니다.
표시 이름보다 project ID를 기록하세요. 이후 배포 환경, usage, billing, quota를 대조할 때 같은 이름의 프로젝트를 혼동하지 않게 해 줍니다.
Create API key 버튼에 권한 부족 메시지가 표시되면 반복 클릭하지 않습니다. 프로젝트 조회, 키 생성, 서비스 활성화, service account 생성, key binding 권한을 프로젝트 관리자와 확인합니다. 다른 사람의 키를 받는 것은 IAM 문제를 해결하지 못합니다.
새 키는 auth key인지 확인한다
AI Studio에서 새로 만드는 키는 현재 authorization key(auth key)입니다. service account에 연결되고 기본적으로 Gemini API에 제한됩니다. Google은 standard key에서 auth key로 전환하고 있으며, 현재 문서는 2026년 9월부터 standard key 요청을 거부한다고 설명합니다.
이 날짜와 UI는 변동될 수 있습니다. 생성 후 Key Type 열을 확인하고, 실제 migration 시점에는 공식 문서를 다시 읽습니다. 예전 튜토리얼의 unrestricted standard key를 새 production 설계에 그대로 넣지 마세요.
키를 코드가 아니라 secret으로 저장한다
키가 유출되면 다른 사람이 프로젝트 쿼터를 소비하고 유료 프로젝트에 비용을 만들 수 있습니다. 다음 위치에는 넣지 않습니다.
- Git 저장소와 commit history
- production 브라우저 JavaScript, 모바일 앱, 공개 확장 프로그램
- issue, 채팅, 화면 캡처, 전체 환경 변수 dump
- 분석과 proxy log에 남는 query string
로컬 개발에서는 GEMINI_API_KEY 또는 GOOGLE_API_KEY를 사용할 수 있습니다. 둘 다 설정되면 GOOGLE_API_KEY가 우선합니다. 예전 값이 남아 있으면 새 키를 설정해도 요청이 바뀌지 않은 것처럼 보일 수 있습니다.
bashexport GEMINI_API_KEY="YOUR_API_KEY"
실제 서비스에서는 server-side secret manager에 저장하고 browser/mobile은 자체 backend를 호출하게 합니다. 값 없이 설정 여부만 확인할 수 있습니다.
bashif [ -n "${GEMINI_API_KEY:-}" ]; then echo "GEMINI_API_KEY is set" else echo "GEMINI_API_KEY is missing" fi
현재 예제로 첫 요청을 보낸다
Google의 현재 get-started 문서는 Interactions endpoint와 gemini-3.7-flash를 사용합니다. 키는 URL이 아닌 header로 보냅니다.
bashcurl -sS -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3.7-flash", "input": "API 연결이 동작했음을 한 문장으로 확인해 주세요." }'
성공 기준은 모델이 정확히 같은 문장을 출력하는 것이 아닙니다. 예상 hostname에 요청이 도착하고, 의도한 프로젝트 키로 인증되며, 완료 상태와 model output이 있는 구조화 response가 돌아오는 것입니다.
모델 ID와 API surface는 바뀝니다. 현재 quickstart가 다른 모델을 사용한다면 그 예제로 canary를 갱신하세요. 오래된 모델 이름을 여러 번 추측하지 않습니다.
오류를 정보로 바꾸는 순서
첫 실패에서 HTTP status, 키를 제거한 error body, project ID, endpoint, model, UTC 시각, request ID를 기록합니다. 키 전체나 전체 환경은 기록하지 않습니다. 한 번에 하나만 바꾸고 같은 canary를 반복합니다.
| 보이는 결과 | 먼저 확인할 범위 | 최소 다음 행동 |
|---|---|---|
| 키 관리 화면 전에 차단 | 지역, 연령 확인, 계정/조직 정책 | 공식 조건을 다시 확인하고 부적격 direct route 중단 |
| Create 버튼 비활성 | project import, IAM | project ID를 고정하고 필요한 권한 요청 |
403 PERMISSION_DENIED | 실제 사용 키, 프로젝트, restriction, action | 403 진단 절차 실행 |
429 RESOURCE_EXHAUSTED | 프로젝트/모델/tier의 live limit | AI Studio 값과 rate limit 가이드 확인 |
| model/route not found | 현재 model ID와 API version | 공식 get-started 예제로 한 번 재시도 |
| 일시적 server error | 서비스 상태, retry 정책 | 제한된 exponential backoff, 새 키 생성 금지 |
이 분리는 중요합니다. 키가 유효해도 quota는 부족할 수 있고, 프로젝트가 유료여도 다른 환경 변수가 오래된 키를 가리킬 수 있습니다.
무료와 유료 결정은 연결 확인 다음이다
키 발급 자체에는 별도 “키 가격”이 없습니다. Free는 일부 모델과 serving mode에만 적용되고, 현재 RPM·TPM·RPD는 선택한 프로젝트와 모델에 대해 AI Studio에 보이는 active limit가 기준입니다. 같은 프로젝트에서 키를 추가로 만들어도 독립 쿼터가 생기지 않습니다.
canary가 성공한 뒤 실제 입력/출력량과 필요한 처리량을 측정하고 billing 연결 여부를 결정합니다. 비용 판단은 Gemini API 가격 가이드와 현재 공식 pricing을 사용합니다.
production 전에는 project ID, credential owner, Key Type, secret 위치, rotation 담당자, 허용 backend, 모델, AI Studio live limit, billing 상태를 한 줄씩 남기세요. 누가 어떤 키를 언제 revoke해야 하는지 알 수 있어야 발급이 완료된 것입니다.
