Gemini API 키 사용하기

Gemini API 키 사용하기 (Using Gemini API keys)

Gemini API를 사용하려면 요청을 인증해야 해요. 표준 API 키 또는 권한 부여(authorization) API 키를 사용해 인증할 수 있어요.

Gemini API 키 생성 또는 보기

출처: 원문

본문

API 키 유형: 표준 키와 권한 부여 키

API 키는 Gemini API에 접근을 제공하지만, 보안 특성은 서로 달라요. Gemini API는 보안을 개선하기 위해 표준 API 키에서 권한 부여 키(authorization key)로 전환하고 있어요.

  • 표준 API 키: 요청을 결제 및 할당량(quota) 목적의 Google Cloud 프로젝트와 연결해요. 표준 키는 호출자를 식별하지 않아서 지원할 수 있는 권한 및 접근 제어의 세분성이 제한돼요.
  • 권한 부여(auth) 키: Google Cloud 서비스 계정에 직접 바인딩돼요. 권한 부여 키를 사용하면 요청이 바인딩된 서비스 계정의 신원으로 처리되어 세밀한 접근 제어가 가능해져요. 권한 부여 키는 기본적으로 Generative Language API(Gemini API)로 제한되며, 시스템이 감지한 유출된 키의 사용을 신속히 중지하는 빠른 유출 키 집행(leaked key enforcement)을 제공해요.

안전한 사용을 보장하기 위해 Gemini API는 표준 키에서 auth 키로 전환할 거예요.

  • Auth 키 기본값: 2026년 5월 28일부터 Google AI Studio에서 생성되는 모든 새 API 키는 자동으로 auth 키로 생성돼요.
  • 제한 없는 키 거부: Gemini API는 제한이 없는(unrestricted) 표준 키의 요청을 거부해요. 명시적 제한이 적용된 표준 API 키는 계속 작동해요. 이 제한은 공개적으로 공유되거나 다른 서비스에 연결된 키의 무단 사용을 방지해요.

참고: 권한 부여 키로 인증된 요청은 Google Cloud 서비스 계정 사용량 지표에 기록되지 않아요.

Google AI Studio에서 API 키 관리하기

프로젝트와 키를 Google AI Studio에서 직접 관리할 수 있어요.

Google Cloud 프로젝트

모든 Gemini API 키는 Google Cloud 프로젝트와 연결돼요. Google Cloud 프로젝트는 결제, 협업자, 권한을 관리해요. Google AI Studio는 이러한 프로젝트에 접근할 수 있는 간단한 인터페이스를 제공해요.

  • 기본 프로젝트: 신규 사용자라면 서비스 약관에 동의한 후 Google AI Studio가 기본 Google Cloud 프로젝트와 API 키를 자동으로 생성해요. 대시보드의 Projects 보기로 이동해 프로젝트 이름을 바꿀 수 있어요.
  • 기존 프로젝트: 이미 Google Cloud 계정이 있다면 AI Studio는 기본 프로젝트를 만들지 않아요. 대신 기존 프로젝트를 가져와야 해요.

프로젝트 가져오기 (Importing projects)

기본적으로 Google AI Studio는 모든 Google Cloud 프로젝트를 표시하지 않아요. 사용하려는 프로젝트를 가져와야 해요.

  1. Google AI Studio로 이동해요.
  2. 왼쪽 패널에서 Dashboard를 열고 Projects를 선택해요.
  3. Import projects 버튼을 클릭해요.
  4. 가져올 Google Cloud 프로젝트를 검색하고 선택한 다음 Import를 클릭해요.
  5. 가져온 후 대시보드에서 API Keys 페이지로 이동해 해당 프로젝트에 키를 생성해요.

키 생성 권한 문제 해결

Create API key 버튼을 사용할 수 없고 "You do not have permission to create a key in this project"(이 프로젝트에서 키를 생성할 권한이 없습니다) 메시지가 표시되면 필요한 IAM 권한이 없는 거예요.

Google Cloud 프로젝트 또는 조직 관리자에게 다음 권한을 포함하는 역할(예: Project Editor)을 부여해 달라고 요청해 주세요.

  • resourcemanager.projects.get: AI Studio가 프로젝트를 확인할 수 있게 해요.
  • apikeys.keys.create: 키 생성을 허용해요.
  • serviceusage.services.enable: Generative Language API가 활성화되도록 보장해요.
  • iam.serviceAccounts.create: 연결된 서비스 계정을 만드는 데 필요해요.
  • iam.serviceAccountApiKeyBindings.create: 서비스 계정을 API 키에 바인딩해요.

관리자 접근 권한을 받을 수 없다면, 조직과 연결되지 않은 새 Google Cloud 프로젝트를 만들어 키를 생성할 수 있어요.

환경 설정하기 (Setting up your environment)

키가 있으면 애플리케이션에서 안전하게 사용하도록 환경을 구성해 주세요.

옵션 1: 환경 변수 사용 (권장)

GEMINI_API_KEY 또는 GOOGLE_API_KEY 환경 변수를 설정해요. Gemini API 클라이언트 라이브러리가 이러한 변수를 자동으로 감지하고 사용해요. 둘 다 설정된 경우 GOOGLE_API_KEY가 우선해요.

운영 체제에 맞춰 변수를 설정하세요.

옵션 2: 코드에서 API 키를 명시적으로 제공

클라이언트를 초기화할 때 API 키를 명시적으로 전달할 수 있어요. 환경 변수를 사용할 수 없는 경우에만 이렇게 하세요.

보안 및 비밀 관리 (Security and secret management)

Gemini API 키를 비밀번호처럼 취급해 주세요. 유출되면 다른 사람이 프로젝트의 할당량을 소비하고, 예상치 못한 청구 비용이 발생하며, 개인 리소스에 접근할 수 있어요.

핵심 보안 규칙

  • 키를 비밀로 유지: Git 같은 소스 제어 시스템에 API 키를 절대 커밋하지 마세요.
  • 프로덕션에서 클라이언트 측에 키를 노출하지 않기: 웹 또는 모바일 앱에 API 키를 직접 하드코딩하지 마세요. 클라이언트 측 코드에 포함된 키는 사용자가 추출할 수 있어요. 클라이언트 측 앱을 보호하려면 백엔드 프록시 서버를 실행해 실제 API 호출을 수행하세요.

비밀 관리 모범 사례

  • 환경 변수: 구성 파일이 아니라 환경 변수에서 키를 읽어요.
  • Secret Manager: 프로덕션에서는 Google Cloud Secret Manager 같은 안전한 비밀 저장소에 키를 저장해요.
  • 청구 알림: Google Cloud Console에서 청구 알림을 설정해 사용량이나 비용이 급증하면 알림을 받아요.

유출 대응 체크리스트

API 키가 유출되었다고 의심된다면:

  1. 새 키 생성: Google AI Studio 또는 Cloud Console에서 교체용 키를 만들어요.
  2. 애플리케이션 업데이트: 새 키를 사용하도록 코드를 배포해요.
  3. 유출된 키 비활성화 또는 삭제: 새 키가 확인되면 Cloud Console에서 유출된 키를 비활성화해요. 애플리케이션 중단을 피하기 위해 새 키가 완전히 활성화될 때까지 이전 키를 삭제하지 마세요.
  4. 사용량 감사: Google Cloud Console에서 청구 로그와 API 사용량을 확인해 무단 활동을 식별해요.

키 제한 및 보안 강화 (Restricting and securing your keys)

API 키에 제한을 추가하면 키가 유출되었을 때 잠재적인 피해를 최소화할 수 있어요.

요청 출처 제한 적용하기

출처 제한은 키를 사용할 수 있는 IP 주소, 웹사이트 또는 애플리케이션을 제한해요.

  1. Google Cloud Console 자격 증명 페이지로 이동해요.
  2. 프로젝트를 선택하고 제한하려는 API 키의 이름을 클릭해요.
  3. Application restrictions에서 IP addresses(또는 환경에 적합한 제한 유형)를 선택해요.
  4. 허용할 IP 주소 또는 범위를 지정한 다음 Save를 클릭해요.

제한 없는 표준 API 키 보안 강화

Gemini API를 계속 사용하려면 제한 없는 키를 반드시 보호해야 해요.

방법 A: 키를 Gemini API로만 제한 (AI Studio)

키를 Gemini API에만 사용한다면 AI Studio에서 직접 보호할 수 있어요.

  1. Google AI Studio의 API Keys 페이지에서 Unrestricted 라벨이 표시된 키를 찾아요.
  2. 라벨 위에 마우스를 올리고 대화상자에서 Add restrictions를 클릭해요.
  3. Restrict to Gemini API only를 선택해요.
  4. Restrict key를 클릭해 확정해요.

참고: API 키를 제한하려면 연결된 Google Cloud 프로젝트에 apikeys.keys.update 권한이 있어야 해요. 이 권한은 API Keys Admin 또는 Editor 같은 역할에 포함되어 있어요.

방법 B: 다른 서비스용 키 제한 (Google Cloud Console)

키를 다른 Google API와 공유하는 경우(권장하지 않음) Cloud Console에서 제한해 주세요. 참고: 이러한 제한이 적용된 후에는 이 키를 사용한 Gemini API 요청이 실패해요.

  1. Google Cloud Console 자격 증명 페이지를 방문해요.
  2. 프로젝트와 API 키를 선택해요.
  3. API restrictions에서 Select API restrictions 드롭다운을 사용해 이 키가 접근할 API를 선택해요. Generative Language API는 선택하지 마세요.
  4. Save를 클릭해요. Gemini API를 계속 사용하려면 AI Studio에서 별도의 제한된 키를 만들어 주세요.

차단된 휴면 키 (Blocked dormant keys)

2026년 5월 7일부터 Gemini API는 오랫동안 휴면 상태였던 제한 없는 API 키를 차단해요. 이러한 키는 AI Studio에서 Blocked 태그로 표시돼요. 계속 사용하려면 새 키를 생성하거나 기존 제한 키를 사용해야 해요.

auth 키로 마이그레이션하기

새 auth API 키를 만들고 애플리케이션을 업데이트하려면 다음 단계를 따르세요.

  1. AI Studio API Keys 페이지로 이동해요.
  2. Key Type 열을 확인해 Standard로 표시된 키를 식별해요.
  3. Create API key를 클릭해 새 키를 생성해요. AI Studio에서 생성된 모든 새 키는 자동으로 auth 키로 생성돼요.
  4. 새 auth API 키를 복사해요.
  5. 애플리케이션 코드, 환경 변수 및 모든 배포 구성을 새 auth API 키를 사용하도록 업데이트해요.
  6. 애플리케이션을 테스트해 새 키로 올바르게 작동하는지 확인해요.
  7. 확인되면 오용을 방지하기 위해 이전 트래픽 키를 삭제하거나 취소해요.

참고: 키가 보이지 않으면 Cloud 프로젝트를 AI Studio로 가져와야 할 수 있어요. 지침은 프로젝트 가져오기 섹션을 참고하세요.

제한 사항 (Limitations)

Google AI Studio는 다음과 같은 프로젝트 및 키 관리 제한을 적용해요.

  • Google AI Studio Projects 페이지에서 한 번에 최대 10개의 프로젝트를 만들 수 있어요.
  • API keys 및 Projects 페이지는 최대 100개의 키와 50개의 프로젝트를 표시해요.
  • 제한이 없거나 Generative Language API(Gemini API)로만 특별히 제한된 API 키만 표시돼요.

고급 프로젝트 관리 또는 다른 제한이 있는 키를 수정하려면 Google Cloud Console 자격 증명 페이지를 사용해 주세요.

더 알아보기 (Learn more)