Gemini API 키 사용

Gemini API를 사용하려면 요청을 인증해야 합니다. 표준 또는 승인 API 키를 사용하여 인증할 수 있습니다.

Gemini API 키 만들기 또는 보기

API 키 유형: 표준과 승인

API 키는 Gemini API에 대한 액세스를 제공하지만 보안 특성은 다릅니다. Gemini API는 보안을 강화하기 위해 표준 API 키에서 승인 키로 전환하고 있습니다.

• 표준 API 키: 청구 및 할당량 목적으로 요청을 Google Cloud 프로젝트와 연결합니다. 표준 키는 호출자를 식별하지 않으므로 지원할 수 있는 권한 및 액세스 제어의 세부사항이 제한됩니다.
• 승인 (auth) 키: Google Cloud 서비스 계정에 직접 바인딩됩니다. 승인 키를 사용하면 바인딩된 서비스 계정의 ID로 요청이 처리되므로 세부적인 액세스 제어가 가능합니다. 승인 키는 기본적으로 Generative Language API(Gemini API)로 제한되며, Google 시스템에서 감지한 유출된 키의 사용을 신속하게 중지하는 신속한 유출 키 시행을 제공합니다.

안전한 사용을 위해 Gemini API가 표준 키에서 인증 키로 이동합니다.

• 인증 키 기본값: Google AI Studio에서 생성된 모든 새 API 키는 인증 키로 자동 생성됩니다.
• 제한되지 않은 키 거부됨: Gemini API가 제한되지 않은 표준 키의 요청을 거부합니다. 명시적 제한사항이 적용된 표준 API 키는 계속 작동합니다. 이 제한은 공개적으로 공유되거나 다른 서비스에 연결될 수 있는 키의 무단 사용을 방지합니다.
• 2026년 9월: Gemini API가 표준 키의 요청을 거부합니다. 서비스 중단을 방지하려면 이 날짜 전에 인증 키로 마이그레이션해야 합니다. 2026년 9월 전에 인증 키로 이전해야 합니다.

Google AI Studio에서 API 키 관리

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

Google Cloud 프로젝트

모든 Gemini API 키는 Google Cloud 프로젝트와 연결됩니다. Google Cloud 프로젝트는 결제, 공동작업자, 권한을 관리합니다. Google AI Studio는 이러한 프로젝트에 액세스할 수 있는 경량 인터페이스를 제공합니다.

• 기본 프로젝트: 신규 사용자의 경우 서비스 약관에 동의하면 Google AI Studio에서 기본 Google Cloud 프로젝트와 API 키를 자동으로 생성합니다. 대시보드의 프로젝트 뷰로 이동하여 이 프로젝트의 이름을 바꿀 수 있습니다.
• 기존 프로젝트: Google Cloud 계정이 이미 있는 경우 AI Studio에서 기본 프로젝트를 만들지 않습니다. 대신 기존 프로젝트를 가져와야 합니다.

프로젝트 가져오기

기본적으로 Google AI Studio에는 모든 Google Cloud 프로젝트가 표시되지 않습니다. 사용할 프로젝트를 가져와야 합니다.

1. Google AI Studio로 이동합니다.
2. 왼쪽 패널에서 대시보드를 열고 프로젝트를 선택합니다.
3. 프로젝트 가져오기 버튼을 클릭합니다.
4. 가져올 Google Cloud 프로젝트를 검색하여 선택한 다음 가져오기를 클릭합니다.
5. 가져온 후 대시보드의 API 키 페이지로 이동하여 해당 프로젝트에서 키를 만듭니다.

키 생성 권한 문제 해결

API 키 만들기 버튼을 사용할 수 없고 '이 프로젝트에서 키를 만들 권한이 없습니다'라는 메시지가 표시되면 필요한 IAM 권한이 없는 것입니다.

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

• resourcemanager.projects.get: AI Studio에서 프로젝트를 확인할 수 있습니다.
• apikeys.keys.create: 키 생성을 허용합니다.
• serviceusage.services.enable: Generative Language API가 사용 설정되어 있는지 확인합니다.
• iam.serviceAccounts.create: 연결된 서비스 계정을 만드는 데 필요합니다.
• iam.serviceAccountApiKeyBindings.create: 서비스 계정을 API 키에 바인딩합니다.

관리 액세스 권한을 얻을 수 없는 경우 조직과 연결되지 않은 새 Google Cloud 프로젝트를 만들어 키를 생성할 수 있습니다.

환경 설정 중

키가 있으면 애플리케이션에서 안전하게 사용할 수 있도록 환경을 구성합니다.

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

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

운영체제를 선택하여 변수를 설정합니다.

~/.bashrc

touch ~/.bashrc && open ~/.bashrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.bashrc

~/.zshrc

touch ~/.zshrc && open ~/.zshrc

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

source ~/.zshrc

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

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

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

interaction = client.interactions.create(
    model="gemini-3.6-flash",
    input="Explain how AI works in a few words"
)
print(interaction.output_text)

import { GoogleGenAI } from "@google/genai"