Gemini API 첫 요청 만들기, API 키를 안전하게 보관하는 초보자 순서
AI를 활용하여 생성한 이미지입니다.
Gemini API는 Google의 생성형 AI 모델을 프로그램에서 호출할 수 있게 해 주는 인터페이스예요. 처음에는 모델 이름보다 API 키를 어디에 만들고 어떻게 숨길지가 더 중요합니다. 키를 코드에 그대로 적으면 파일을 공유하거나 저장소에 올리는 순간 다른 사람이 사용할 수 있어요.
Google의 현재 시작 문서는 AI Studio에서 키를 만들고, 환경 변수에 저장한 뒤 Python SDK로 첫 요청을 보내는 흐름을 안내합니다.[1][2] 아래 순서는 개인 PC에서 작은 테스트를 시작하려는 초보자를 위한 기준이에요.
시작 전에 준비할 것
- Google 계정으로 AI Studio에 로그인하세요.
- 새 API 키를 만들 프로젝트를 선택하거나 생성하세요.
- Python을 실행할 터미널과 가상 환경을 준비하세요.
- 키를 코드 파일, 화면 캡처, 공개 저장소에 넣지 마세요.
Google 문서에 따르면 새 키는 AI Studio의 API keys 화면에서 만들 수 있고, 키를 프로젝트에 연결하는 절차가 표시됩니다.[1][2] 사용량이 늘어 유료 등급으로 올릴 때는 Cloud Billing 설정이 필요하므로, 테스트 단계에서 결제 조건까지 확인해 두는 편이 좋아요.[1]
API 키 만들기
- Google AI Studio의 API keys 화면을 여세요.
- Create API key를 누르세요.
- 새 프로젝트를 만들거나 기존 프로젝트를 선택하세요.
- 표시된 키를 한 번만 안전한 곳에 복사하세요.
- 브라우저 기록이나 메신저에 붙여넣은 키는 남기지 마세요.
키가 만들어졌다고 해서 바로 프로그램에 공개해도 되는 것은 아니에요. 프로그램은 키를 환경 변수에서 읽도록 만들고, 실제 코드에는 키 자체를 적지 않는 방식이 기본입니다.[2]
환경 변수에 키 넣기
macOS나 Linux 터미널에서는 다음처럼 현재 셸에 키를 설정할 수 있어요. 아래의 YOUR_API_KEY 부분에 실제 키를 넣되, 이 명령을 문서나 공개 게시물에 남기지 마세요.
export GEMINI_API_KEY="YOUR_API_KEY"Google의 API 키 문서는 GEMINI_API_KEY 또는 GOOGLE_API_KEY 환경 변수를 사용할 수 있다고 안내하며, 두 변수가 모두 있으면 GOOGLE_API_KEY가 우선됩니다.[2] 초보자는 이름을 하나로 통일하는 편이 헷갈리지 않아요.
Windows PowerShell에서는 현재 창에서만 쓸 키를 다음처럼 지정할 수 있습니다.
$env:GEMINI_API_KEY="YOUR_API_KEY"터미널을 새로 열었을 때 키가 사라지는 것은 이상한 일이 아니에요. 영구 설정을 할 때는 운영체제의 사용자 환경 변수 기능을 사용하되, 여러 사람이 쓰는 PC에서는 접근 권한과 키 교체 방법도 함께 정하세요.
Python SDK 설치
Google의 시작 문서는 Python용 google-genai 패키지를 설치하는 방법을 사용합니다.[1] 프로젝트 폴더에서 다음 명령을 실행하세요.
python -m pip install -U google-genai설치가 끝나면 아래 코드로 첫 텍스트 요청을 보낼 수 있어요. 클라이언트는 환경 변수에 있는 키를 자동으로 읽습니다.[1][2]
from google import genai
client = genai.Client()
response = client.models.generate_content(
model="gemini-3.8-flash",
contents="컴퓨터 백업을 처음 시작하는 사람에게 한 문장으로 설명해 줘"
)
print(response.text)모델 이름은 계정과 문서의 제공 범위에 따라 달라질 수 있어요. Google의 현재 빠른 시작 예시는 gemini-3.8-flash를 사용하고 있으니, 실행 시점의 모델 목록과 문서에 표시된 이름을 그대로 확인하세요.[1] 예시가 실패하면 키가 비어 있지 않은지, Python이 같은 터미널 환경을 보고 있는지, 모델 이름에 오타가 없는지부터 점검하면 됩니다.
오류가 날 때 나누어 볼 것
| 증상 | 먼저 볼 항목 | 다음 행동 |
|---|---|---|
| 인증 오류 | 환경 변수 이름과 키 값 | 새 터미널에서 다시 설정하고 키를 교체 |
| 모델을 찾을 수 없음 | 모델 이름과 제공 범위 | 공식 모델 목록의 이름으로 수정 |
| 요청 한도 초과 | 현재 프로젝트의 사용량 | AI Studio 사용량을 확인하고 요청 빈도 줄이기 |
| 결제 관련 오류 | 프로젝트의 Billing 상태 | 유료 전환 조건을 확인한 뒤 결정 |
오류 메시지 전체를 그대로 온라인에 올리는 것도 조심하세요. 키가 포함되거나 프로젝트 식별자가 노출될 수 있으니 필요한 부분만 남기고 나머지는 가리세요.
키를 잘못 공개했다면
키를 Git 저장소, 블로그, 공개 채팅에 올렸다면 파일에서 지우는 것만으로 충분하지 않아요. AI Studio에서 해당 키를 삭제하거나 교체하고, 사용량 화면에서 예상하지 못한 요청이 있었는지 확인하세요. 새 키를 만든 뒤에는 코드가 옛 키를 계속 읽지 않는지도 살펴야 합니다.
어디까지 만들면 충분할까?
처음부터 챗봇 전체를 만들 필요는 없어요. 키 생성, 짧은 질문 하나, 응답 출력까지 성공하면 첫 단계는 끝입니다. 그 다음에 입력 길이, 응답 형식, 오류 처리, 사용량 제한을 하나씩 추가하세요. 사용자 입력을 그대로 외부 모델에 보낼 프로그램이라면 개인정보와 비밀정보를 먼저 걸러내는 규칙도 필요합니다.
API 키를 안전하게 보관하고 작은 요청부터 확인하면 모델 선택보다 더 자주 생기는 설정 실수를 줄일 수 있어요. 공식 문서와 계정 화면의 제공 조건이 바뀔 수 있으므로 새 프로젝트를 시작할 때마다 현재 모델 이름과 사용량 제한을 다시 확인하세요.[1][2]
