Gemini API 첫 호출 — 키 만들기 · 환경 변수 · 무료 한도 확인까지

KAITABASE가 공식 문서와 원문을 직접 읽고 새로 쓴 가이드입니다.

이 가이드로 할 수 있는 것

Gemini API는 Google의 Gemini 모델을 내 프로그램에서 부르는 통로입니다. 공식 빠른 시작 문서는 키 하나와 파이썬 SDK 한 줄 설치로 첫 요청을 보내는 방법을 안내합니다. 이 가이드는 그 순서를 따르되, 직접 설치해 본 결과와 문서에서 놓치기 쉬운 부분(키 종류, 한도가 적용되는 단위, 무료 등급의 데이터 사용)을 함께 적었습니다.

끝까지 따라 하면 다음이 됩니다.

1. AI Studio에서 키를 만들고, 코드가 아니라 환경 변수에 둡니다.
2. 파이썬 가상환경에 google-genai 를 설치하고 첫 요청을 보냅니다.
3. 내 프로젝트의 무료 한도를 어디서 보는지, 한도가 왜 키가 아니라 프로젝트 단위인지 압니다.

빠른 시작

키를 환경 변수 GEMINI_API_KEY 에 넣었다면, Windows PowerShell에서 아래 순서면 됩니다.

python -m venv .venv
.\.venv\Scripts\python -m pip install -U google-genai
.\.venv\Scripts\python first_call.py

first_call.py 는 공식 빠른 시작 문서의 예제 그대로입니다.

12345678from google import genai

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

2026-10-22 기준 PyPI의 최신 버전은 google-genai 2.32.0(2026-10-21 배포)이고, 요구 파이썬 버전은 3.10 이상입니다.

STEP 1. API 키 만들기

목표: 내 Google Cloud 프로젝트에 묶인 키를 하나 만듭니다. · 예상 시간: 5분

공식 문서 기준(직접 실행 안 함): 로그인이 필요해 이 단계는 실행하지 않았습니다.

1. AI Studio의 API Keys 페이지(https://aistudio.google.com/apikey)를 엽니다.
2. Create API key 를 누릅니다. 처음 쓰는 사용자에게는 기본 프로젝트가 만들어집니다.
3. 이미 Google Cloud를 쓰고 있다면 Dashboard > Projects > Import projects 에서 기존 프로젝트를 먼저 가져와야 그 프로젝트에 키를 만들 수 있습니다.

공식 문서에 따르면 키는 모두 하나의 Google Cloud 프로젝트에 속하고, 결제 · 협업자 · 권한은 그 프로젝트가 관리합니다. 2026-05-28부터 AI Studio에서 새로 만드는 키는 기본으로 auth 키입니다.

확인 API Keys 목록에 새 키가 보이고, 어느 프로젝트에 속하는지 함께 나옵니다.

막히면 Create API key 버튼이 눌리지 않으면 권한 문제입니다. 공식 문서는 apikeys.keys.create, iam.serviceAccounts.create 같은 IAM 권한이나 Project Editor 역할이 필요하다고 안내합니다. 회사 계정이라면 Cloud 관리자에게 요청합니다.

주의 공식 문서에 따르면 Gemini API는 제한이 걸리지 않은(unrestricted) standard 키의 요청을 거절합니다. 예전에 만든 키가 갑자기 안 된다면 AI Studio에서 Add restrictions > Restrict to Gemini API only > Restrict key 로 제한을 걸어 줍니다. 오래 쓰지 않은 제한 없는 키는 2026-05-07부터 막혀 있습니다.

STEP 2. 키를 환경 변수에 넣기

목표: 키를 코드에 적지 않고 SDK가 알아서 읽게 합니다. · 예상 시간: 3분

공식 SDK는 GEMINI_API_KEY 또는 GOOGLE_API_KEY 환경 변수를 자동으로 읽습니다. 둘 다 있으면 GOOGLE_API_KEY 가 우선합니다. 공식 문서는 하나만 두라고 권합니다.

macOS · Linux(Bash · Zsh)에서는 ~/.bashrc 또는 ~/.zshrc 에 한 줄을 넣고 다시 읽습니다.

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>
source ~/.bashrc

Windows에서는 환경 변수 창의 사용자 변수에 GEMINI_API_KEY 를 추가하고, 터미널을 새로 엽니다. 지금 연 PowerShell 창에서만 잠깐 쓰려면 다음처럼 넣을 수 있습니다(창을 닫으면 사라집니다).

$env:GEMINI_API_KEY = "여기에_키"

공식 문서 기준(직접 실행 안 함): 이 가이드는 키를 쓰지 않았으므로 환경 변수도 설정하지 않았습니다.

확인 새 터미널에서 echo $env:GEMINI_API_KEY(PowerShell) 또는 echo $GEMINI_API_KEY(Bash)로 값이 나오는지 봅니다. 화면 공유 중이라면 이 확인은 건너뜁니다.

되돌리기 환경 변수 창에서 해당 변수를 지우거나, ~/.bashrc 에 넣은 줄을 지우고 터미널을 새로 엽니다.

STEP 3. 가상환경에 SDK 설치하기

목표: 공식 파이썬 SDK를 다른 패키지와 섞이지 않게 설치합니다. · 예상 시간: 3분

123456python --version
mkdir gemini-work
cd gemini-work
python -m venv .venv
.\.venv\Scripts\python -m pip install -U google-genai
.\.venv\Scripts\python -m pip show google-genai

직접 실행한 결과입니다(Windows 11 · Python 3.14.3).

Name: google-genai
Version: 2.32.0
Summary: GenAI Python SDK

확인 Version: 줄이 보이면 설치된 것입니다. 저장소 README의 설치 명령은 pip install google-genai, uv를 쓰면 uv pip install google-genai 입니다.

막히면 파이썬이 3.9 이하이면 PyPI 표기(>=3.10)를 벗어나 설치가 안 될 수 있습니다. 새 버전을 설치합니다.

되돌리기 gemini-work 폴더를 지우면 시스템 파이썬에는 아무것도 남지 않습니다.

STEP 4. 키 없이 먼저 돌려 보고 오류 모양 익히기

목표: 키 문제일 때 어떤 오류가 나는지 미리 봅니다. · 예상 시간: 3분

키를 넣기 전에 한 번 돌려 보면, 나중에 오류가 났을 때 키 문제인지 아닌지 바로 가를 수 있습니다. 실제로 실행해 본 결과입니다.

환경 변수에 키가 없을 때 genai.Client() 를 만들면 요청을 보내기도 전에 멈춥니다.

ValueError: No API key was provided. Please pass a valid API key. Learn how to create an API key at https://ai.google.dev/gemini-api/docs/api-key.

일부러 틀린 키(not-a-real-key)를 넣고 요청하면 서버가 400으로 거절합니다.

Error code: 400 - API key not valid. Please pass a valid API key.
status: INVALID_ARGUMENT · reason: API_KEY_INVALID

직접 실행하다 알게 된 점: 같은 틀린 키라도 client.interactions.create 는 BadRequestError, client.models.generate_content 는 google.genai.errors.ClientError 로 서로 다른 예외 종류를 냅니다(google-genai 2.32.0). 오류를 잡는 코드를 쓸 때는 쓰는 함수 쪽 예외를 확인합니다.

확인 위 두 오류 중 하나가 나오면 SDK 설치와 네트워크는 정상이고, 남은 것은 키뿐입니다.

STEP 5. 첫 요청 보내기

목표: 모델의 답을 받아 화면에 찍습니다. · 예상 시간: 3분

공식 문서 기준(직접 실행 안 함): 빠른 시작의 예제를 first_call.py 로 저장하고 실행합니다.

12345678from google import genai

with genai.Client() as client:
    interaction = client.interactions.create(
        model="gemini-3.8-flash",
        input="회의록 요약에 쓸 체크리스트를 3줄로 써 주세요."
    )
    print(interaction.output_text)

README는 다 쓴 클라이언트를 client.close() 로 닫거나 with 블록으로 열어 연결을 정리하라고 권합니다. 위 예제는 with 를 썼습니다.

README에는 기존 방식인 generate_content 예제도 함께 있습니다.

1234response = client.models.generate_content(
    model='gemini-flash-latest', contents='Why is the sky blue?'
)
print(response.text)

터미널에서 바로 시험하려면 공식 문서의 REST 예제를 씁니다.

1234567curl -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.8-flash",
    "input": "Explain how AI works in a few words"
  }'

확인 공식 문서 기준 짧은 설명 문장이 출력됩니다.

막히면 README에 따르면 SDK는 기본으로 미리 보기 기능을 위한 beta 엔드포인트를 씁니다. 안정 버전만 쓰려면 types.HttpOptions(api_version='v1') 로 바꿀 수 있지만, 새 기능은 v1에 없을 수 있습니다.

STEP 6. 무료 한도 확인하기

목표: 내 프로젝트가 1분 · 하루에 얼마나 보낼 수 있는지 압니다. · 예상 시간: 3분

공식 rate-limits 문서가 밝히는 내용은 다음과 같습니다.

• 한도는 분당 요청 수(RPM), 분당 입력 토큰 수(TPM), 하루 요청 수(RPD) 세 가지로 잽니다. 일부 모델은 분당 이미지 수(IPM) · 하루 토큰 수(TPD)가 더 있습니다.
• 한도는 키가 아니라 프로젝트 단위로 걸립니다. 같은 프로젝트에 키를 여러 개 만들어도 한도는 늘지 않습니다.
• 하루 한도(RPD)는 태평양 시간 자정에 초기화됩니다. 한국 시간으로는 오후 4시(서머타임 기간) 또는 오후 5시입니다.
• 무료(Free) 등급의 구체적 숫자는 이 문서에 적혀 있지 않습니다. 문서는 AI Studio에서 내 활성 한도를 보라고 안내합니다. 그래서 이 가이드도 숫자를 옮겨 적지 않았습니다.
• 등급은 Free(활성 프로젝트 또는 무료 체험) → Tier 1(결제 계정 연결) → Tier 2(누적 100달러 결제 + 첫 결제 후 3일) → Tier 3(누적 1,000달러 결제 + 30일)입니다.
• 문서는 "명시된 한도는 보장되지 않으며 실제 처리량은 달라질 수 있다"고 적습니다.

확인 AI Studio에서 내 프로젝트의 모델별 한도 표를 열어, 쓰려는 모델의 RPM · RPD를 적어 둡니다.

막히면 한도를 넘으면 요청이 거절됩니다. 반복 작업이라면 요청 사이에 쉬는 시간을 두거나, 결제 계정을 연결해 Tier 1로 올리는 방법이 있습니다. 결제를 연결하면 요금이 나갈 수 있으니 STEP 7과 주의할 점을 먼저 읽습니다.

STEP 7. 키를 안전하게 두기

목표: 키가 새어 나가 요금이 나가는 일을 막습니다. · 예상 시간: 3분

공식 문서는 "API 키를 비밀번호처럼 다루라"고 하며 다음을 권합니다.

1. 키를 Git 같은 소스 관리에 올리지 않습니다. .env 파일을 쓴다면 .gitignore 에 넣습니다.
2. 실제 서비스하는 웹 · 모바일 앱에 키를 넣지 않습니다. 사용자 기기에서 키가 보이므로, 키는 내 백엔드 서버에 두고 앱은 그 서버를 부르게 합니다.
3. 운영용 키는 Google Cloud Secret Manager 같은 비밀 관리 도구에 두고, 프로젝트에 결제 알림을 겁니다.
4. 키를 다른 Google API와 같이 쓰면 Cloud 콘솔의 API restrictions 에서 제한합니다.

되돌리기 키가 새었다면 공식 문서의 순서대로 합니다. 새 키를 만들어 배포하고, 새 키가 동작하는 것을 확인한 뒤 옛 키를 끄고, Cloud 콘솔에서 사용 기록을 점검합니다.

잘못 쓰는 예 · 바르게 쓰는 예

바로 쓰는 프롬프트 · 템플릿

.env 와 .gitignore 를 함께 두는 기본 틀입니다.

123456## .env (Git에 올리지 않음)
GEMINI_API_KEY=여기에_키

## .gitignore
.env
.venv/

오류 종류를 나눠 보는 첫 호출 스크립트입니다.

12345678910from google import genai

try:
    with genai.Client() as client:
        r = client.interactions.create(model="gemini-3.8-flash", input="한 줄로 자기소개를 해 주세요.")
        print(r.output_text)
except ValueError as e:
    print("키가 설정되지 않았습니다:", e)
except Exception as e:
    print("요청 실패(키 · 한도 · 모델 이름 확인):", type(e).__name__, e)

AI 코딩 도구에 연결 코드를 맡길 때 붙이는 요청입니다.

12345google-genai 파이썬 SDK로 Gemini API를 부르는 함수를 만들어 주세요.
- 키는 환경 변수 GEMINI_API_KEY에서만 읽고, 코드에 적지 마세요.
- with genai.Client() as client 형태로 클라이언트를 닫아 주세요.
- 한도 초과로 거절되면 30초 쉬고 한 번만 다시 시도하세요.
- 모델 이름은 상수 하나로 빼 두세요.

주의할 점

• 요금: 가격은 공식 가격 페이지(https://ai.google.dev/gemini-api/docs/pricing)에서 확인합니다. 바뀔 수 있어 이 가이드는 옮겨 적지 않았습니다. 2026-10-22 기준 가격 페이지에서 gemini-3.8-flash 는 Standard 등급에만 무료 등급이 있고, Batch · Flex · Priority에는 무료 등급이 없습니다.
• 데이터 사용: 같은 가격 페이지의 "Used to improve our products" 행이 무료 등급은 Yes, 유료 등급은 No입니다. 회사 자료는 유료 등급에서 쓰거나 회사 규정을 먼저 확인합니다.
• 권한: 키는 프로젝트에 속하고, 프로젝트의 협업자는 그 키의 사용량과 결제에 영향을 줍니다. 회사 프로젝트에서 개인 시험을 하지 않습니다.
• 보안: 키가 새면 남이 내 한도와 요금을 씁니다. 결제 알림을 꼭 겁니다.
• 한도: 한도는 보장값이 아니며 바뀔 수 있습니다. 숫자는 늘 AI Studio에서 직접 확인합니다.
• 라이선스: google-genai SDK는 Apache-2.0입니다. API 사용에는 Google의 Gemini API 이용 약관이 적용됩니다.

공식 자료

• Using Gemini API keys — https://ai.google.dev/gemini-api/docs/api-key
• Gemini API quickstart — https://ai.google.dev/gemini-api/docs/quickstart
• Rate limits — https://ai.google.dev/gemini-api/docs/rate-limits
• Gemini API pricing — https://ai.google.dev/gemini-api/docs/pricing
• googleapis/python-genai 저장소 README — https://github.com/googleapis/python-genai
• PyPI google-genai — https://pypi.org/project/google-genai/
• AI Studio API Keys — https://aistudio.google.com/apikey

더 보기

이 가이드는 KAITABASE가 공식 문서와 원문을 직접 읽고 실행해 본 뒤 새로 쓴 자료입니다. 같은 주제의 다른 글은 KAITABASE에서 이어서 볼 수 있습니다.

• 도구 연결 자료 모음 — https://kaitabase.vercel.app/?area=connect
• KAITABASE 전체 자료 — https://kaitabase.vercel.app