Gemini API 키 사용하기
Gemini API 키 사용하기
Gemini API를 사용하려면 요청을 인증해야 해요. 표준(standard) 또는 인가(authorization) API 키로 인증할 수 있어요.
출처: 원문
본문
API 키 유형: 표준 vs 인가
API 키는 Gemini API에 대한 접근을 제공하지만, 보안 특성은 서로 달라요. Gemini API는 보안을 강화하기 위해 표준 API 키에서 **인가 키(authorization key)**로 전환하고 있어요:
- 표준 API 키(Standard API keys): 청구와 할당량 목적으로 요청을 Google Cloud 프로젝트와 연결해요. 표준 키는 호출자를 식별하지 않아서, 지원할 수 있는 권한과 접근 제어의 세분화 정도가 제한돼요.
- 인가 키(Authorization/auth keys): Google Cloud 서비스 계정에 직접 바인딩돼요. 인가 키를 사용하면 요청이 바인딩된 서비스 계정의 신원으로 처리되어 세분화된 접근 제어가 가능해요. 인가 키는 기본적으로 Generative Language API(Gemini API)로 제한되며, 우리 시스템이 감지한 유출 키의 사용을 빠르게 중지하는 **빠른 유출 키 강제(leaked key enforcement)**를 제공해요.
안전한 사용을 보장하기 위해 Gemini API는 표준 키에서 인가 키로 이동할 거예요:
- 인가 키 기본값(Auth keys default): 2026년 5월 28일부터 Google AI Studio에서 만든 모든 새 API 키는 자동으로 인가 키로 생성돼요.
- 제한 없는 키 거부(Unrestricted keys rejected): Gemini API는 제한 없는(unrestricted) 표준 키의 요청을 거부해요. 명시적 제한이 적용된 표준 API 키는 계속 작동해요. 이 제한은 공개적으로 공유되거나 다른 서비스에 연결된 키의 무단 사용을 방지해요.
참고: 인가 키로 인증된 요청은 Google Cloud 서비스 계정 사용량 메트릭에 기록되지 않아요.
Google AI Studio에서 API 키 관리하기
프로젝트와 키는 Google AI Studio에서 직접 관리할 수 있어요.
Google Cloud 프로젝트
모든 Gemini API 키는 Google Cloud 프로젝트와 연결돼요. Google Cloud 프로젝트는 청구, 협업자, 권한을 관리해요. Google AI Studio는 이 프로젝트에 접근할 수 있는 가벼운 인터페이스를 제공하죠.
- 기본 프로젝트(Default project): 새 사용자라면 이용약관에 동의한 후 Google AI Studio가 자동으로 기본 Google Cloud 프로젝트와 API 키를 만들어 줘요. 대시보드의 Projects 보기로 이동해 이 프로젝트 이름을 바꿀 수 있어요.
- 기존 프로젝트(Existing projects): 이미 Google Cloud 계정이 있다면 AI Studio는 기본 프로젝트를 만들지 않아요. 대신 기존 프로젝트를 가져와야 해요.
프로젝트 가져오기 (Importing projects)
기본적으로 Google AI Studio는 모든 Google Cloud 프로젝트를 표시하지 않아요. 사용하려는 프로젝트를 가져와야 합니다:
- Google AI Studio로 이동합니다.
- 왼쪽 패널에서 Dashboard를 열고 Projects를 선택합니다.
- Import projects 버튼을 클릭합니다.
- 가져오려는 Google Cloud 프로젝트를 검색해 선택한 다음 Import를 클릭합니다.
- 가져온 후 대시보드의 API Keys 페이지로 이동해 해당 프로젝트에서 키를 만듭니다.
키 생성 권한 문제 해결 (Troubleshooting key creation permissions)
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)
키를 얻은 후에는 애플리케이션에서 안전하게 사용하도록 환경을 구성하세요.
환경 변수 사용 (권장)
GEMINI_API_KEY 또는 GOOGLE_API_KEY 환경 변수를 설정하세요. Gemini API 클라이언트 라이브러리는 이 변수들을 자동으로 감지해 사용해요. 둘 다 설정된 경우 GOOGLE_API_KEY가 우선해요.
운영 체제에 따라 변수를 설정하세요:
Linux/macOS - Bash
bash 구성 파일이 있는지 확인합니다: ~/.bashrc → 없으면 만들고 열기: touch ~/.bashrc && open ~/.bashrc → 파일 끝에 export 명령 추가: export GEMINI_API_KEY=<YOUR_API_KEY_HERE> → 저장 후 변경 적용: source ~/.bashrc
macOS - Zsh
zsh 구성 파일 확인: ~/.zshrc → 없으면 만들고 열기: touch ~/.zshrc && open ~/.zshrc → export 명령 추가: export GEMINI_API_KEY=<YOUR_API_KEY_HERE> → 저장 후 적용: source ~/.zshrc
Windows
Windows 검색창에서 "환경 변수(Environment Variables)"를 검색합니다. 시스템 속성 대화 상자에서 환경 변수를 클릭합니다. 사용자 변수 또는 시스템 변수에서 **새로 만들기...**를 클릭합니다. 변수 이름을 GEMINI_API_KEY로, 값을 API 키로 설정합니다. 확인을 클릭해 저장합니다. 변수를 로드하려면 새 터미널 세션을 엽니다.
코드에서 API 키를 명시적으로 제공하기
클라이언트 초기화 시 API 키를 명시적으로 전달할 수 있어요. 환경 변수를 사용할 수 없을 때만 이렇게 하세요.
from google import genai
client = genai.Client(api_key="YOUR_API_KEY")
response = client.models.generate_content(
model="gemini-3.8-flash",
contents="Explain how AI works in a few words"
)
print(response.text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey: *** });
async function main() {
const response = await ai.models.generateContent({
model: "gemini-3.8-flash",
contents: "Explain how AI works in a few words",
});
console.log(response.text);
}
main();
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: ***
Backend: genai.BackendGeminiAPI,
})
if err != nil {
log.Fatal(err)
}
result, err := client.Models.GenerateContent(
ctx,
"gemini-3.8-flash",
genai.Text("Explain how AI works in a few words"),
nil,
)
if err != nil {
log.Fatal(err)
}
fmt.Println(result.Text())
}
package com.example;
import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;
public class GenerateTextFromTextInput {
public static void main(String[] args) {
Client client = Client.builder().apiKey("YOUR_API_KEY").build();
GenerateContentResponse response =
client.models.generateContent(
"gemini-3.8-flash",
"Explain how AI works in a few words",
null);
System.out.println(response.text());
}
}
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" -H 'Content-Type: application/json' -H "x-goog-api-key: *** -X POST -d '{
"contents": [
{
"parts": [
{
"text": "Explain how AI works in a few words"
}
]
}
]
}'
보안과 비밀 관리 (Security and secret management)
Gemini API 키는 비밀번호처럼 취급하세요. 유출되면 다른 사람이 프로젝트의 할당량을 소비하고, 예상치 못한 청구가 발생하며, 비공개 리소스에 접근할 수 있어요.
중요 보안 규칙 (Critical security rules)
- 키를 기밀로 유지하세요: Git 같은 소스 제어 시스템에 API 키를 절대 커밋하지 마세요.
- 프로덕션에서 클라이언트 측에 키를 노출하지 마세요: 웹·모바일 앱에 API 키를 하드코딩하지 마세요. 클라이언트 측 코드에 컴파일된 키는 사용자가 추출할 수 있어요. 클라이언트 측 앱을 안전하게 하려면 백엔드 프록시 서버를 실행해 실제 API 호출을 하세요.
비밀 관리 모범 사례 (Secret management best practices)
- 환경 변수: 설정 파일보다 환경 변수에서 키를 읽으세요.
- Secret Manager: 프로덕션에서는 Google Cloud Secret Manager 같은 안전한 비밀 저장소에 키를 저장하세요.
- 청구 알림: 사용량이나 비용이 급증하면 알려 주도록 Google Cloud 콘솔에 청구 알림을 설정하세요.
유출 대응 체크리스트 (Leak response checklist)
API 키가 유출됐다고 의심된다면:
- 새 키 생성: Google AI Studio 또는 Cloud 콘솔에서 교체용 키를 만듭니다.
- 애플리케이션 업데이트: 새 키를 사용해 코드를 배포합니다.
- 유출된 키 비활성화 또는 삭제: 새 키가 검증되면 Cloud 콘솔에서 유출된 키를 비활성화합니다. 애플리케이션 중단을 피하려면 새 키가 완전히 활성화될 때까지 이전 키를 삭제하지 마세요.
- 사용량 감사: Cloud 콘솔의 청구 로그와 API 사용량을 확인해 무단 활동을 식별합니다.
키 제한과 보안 강화 (Restricting and securing your keys)
API 키에 제한을 추가하면 키가 유출됐을 때의 잠재적 피해를 최소화할 수 있어요.
요청 출처 제한 적용 (Apply request origin restrictions)
출처(origin) 제한은 어떤 IP 주소, 웹사이트, 애플리케이션이 키를 사용할 수 있는지 제한해요.
- Google Cloud Console Credentials 페이지로 이동합니다.
- 프로젝트를 선택하고 제한하려는 API 키의 이름을 클릭합니다.
- Application restrictions에서 IP addresses(또는 환경에 맞는 적절한 제한 유형)를 선택합니다.
- 허용할 IP 주소 또는 범위를 지정하고 Save를 클릭합니다.
제한 없는 표준 API 키 보안 처리 (Securing unrestricted standard API keys)
Gemini API를 계속 사용하려면 제한 없는 키를 반드시 보호해야 해요.
AI Studio에서 키를 Gemini API 전용으로 제한하기
키를 Gemini API에만 사용한다면 AI Studio에서 직접 보호할 수 있어요:
- Google AI Studio의 API Keys 페이지에서 Unrestricted 라벨이 붙은 키를 찾습니다.
- 라벨 위에 마우스를 올리고 대화 상자에서 Add restrictions를 클릭합니다.
- Restrict to Gemini API only를 선택합니다.
- Restrict key를 클릭해 확인합니다.
참고: API 키를 제한하려면 연결된 Google Cloud 프로젝트에 대해 apikeys.keys.update 권한이 있어야 해요. 이 권한은 API Keys Admin 또는 Editor 같은 역할에 포함돼요.
Google Cloud 콘솔에서 다른 서비스용 키 제한하기
키가 다른 Google API와 공유된다면(권장하지 않음) Cloud 콘솔에서 제한하세요. 참고: 이 제한이 적용되면 이 키를 사용하는 Gemini API 요청은 실패해요.
- Google Cloud Console Credentials 페이지를 방문합니다.
- 프로젝트와 API 키를 선택합니다.
- API restrictions에서 Restrict key를 선택합니다.
- 드롭다운에서 이 키가 접근할 API를 선택합니다. Generative Language API는 선택하지 마세요.
- Save를 클릭합니다. Gemini API를 계속 사용하려면 AI Studio에서 별도의 제한된 키를 만드세요.
차단된 휴면 키 (Blocked dormant keys)
2026년 5월 7일부터 Gemini API는 오랜 기간 휴면 상태였던 제한 없는 API 키를 차단해요. 이 키들은 AI Studio에서 Blocked 태그로 표시돼요. 계속하려면 새 키를 생성하거나 기존의 제한된 키를 사용해야 해요.
인가 키로 마이그레이션하기 (Migrate to an auth key)
새 인가 API 키를 만들고 애플리케이션을 업데이트하려면 다음 단계를 따르세요:
- AI Studio API Keys 페이지로 이동합니다.
- Key Type 열을 확인해 Standard로 표시된 키를 식별합니다.
- Create API key를 클릭해 새 키를 생성합니다. AI Studio에서 만든 모든 새 키는 자동으로 인가 키로 생성돼요.
- 새 인가 API 키를 복사합니다.
- 애플리케이션 코드, 환경 변수, 배포 설정을 새 인가 API 키를 사용하도록 업데이트합니다.
- 새 키로 올바르게 작동하는지 애플리케이션을 테스트합니다.
- 검증되면 남용을 방지하기 위해 이전 트래픽 키를 삭제하거나 폐기합니다.
참고: 키가 보이지 않는다면 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 credentials 페이지를 사용하세요.
더 알아보기 (Learn more)
- Gemini API 키 만들기 — AI Studio에서 바로 키 생성.
- Google Cloud Secret Manager — 프로덕션 비밀 저장.