Gemini API 시작 가이드: API 키 발급부터 Python 첫 호출까지

요약: 코딩이 익숙하지 않은 1인 사업자와 소규모 팀을 위해 Gemini API 키 발급, google-genai 설치, Python 첫 호출, 비용·한도 확인, 운영 보안까지 순서대로 설명합니다.

확인 기준일: 2026년 7월 19일
적용 대상: /entry/gemini-pro-api-free-ai-agent-setup-guide (CMS ID 62)

Gemini API를 쓰려면 복잡한 AI 시스템부터 만들 필요가 없습니다. Google AI Studio에서 API 키를 만들고, 공식 google-genai SDK로 한 번 호출해 보면 기본 연결은 끝납니다.

다만 "무료 API"를 "아무 제한 없이 계속 무료"라고 이해하면 곤란합니다. Google은 일부 모델과 기능에 무료 계층을 제공하지만, 지원 여부와 실제 한도는 모델, 프로젝트의 사용 등급, 계정, 지역에 따라 달라질 수 있습니다. 무료 계층이 없는 모델도 있습니다. 개발을 시작하기 전과 서비스를 공개하기 전에 공식 가격표와 내 프로젝트의 실제 사용 한도를 확인해야 합니다.

준비물

Google 계정
Python 3와 pip
명령을 입력할 터미널
테스트용 프로젝트 폴더

이 글의 예제는 Google의 공식 Python SDK인 google-genai를 사용합니다. 예전 글에서 볼 수 있는 google-generativeai 패키지와 혼동하지 마세요. 새로 시작하는 프로젝트라면 공식 문서가 안내하는 google-genai를 기준으로 잡는 편이 안전합니다.

1. Google AI Studio에서 API 키 만들기

Google AI Studio의 API 키 페이지를 엽니다.
Google 계정으로 로그인합니다.
사용할 Google Cloud 프로젝트를 선택하거나 새 프로젝트를 만듭니다.
API 키를 생성한 뒤 한 번만 복사해 안전한 곳에 보관합니다.

API 호출량과 한도는 API 키 한 개가 아니라 프로젝트 단위로 적용됩니다. 같은 프로젝트에서 키를 여러 개 만들어도 프로젝트 한도가 늘어나지는 않습니다.

Google의 API 키 공식 문서에 따르면 AI Studio에서 새로 만드는 키는 인증용 키(auth key)로 생성됩니다. 오래전에 만든 구형 키로 인증 오류가 난다면 키를 코드에 억지로 넣기보다 공식 문서의 키 유형과 제한 설정을 확인하고 새 키 발급을 검토하세요.

2. 프로젝트와 가상환경 만들기

터미널에서 다음 명령을 실행합니다.

mkdir gemini-api-start
cd gemini-api-start
python -m venv .venv

가상환경을 활성화합니다.

macOS 또는 Linux:

source .venv/bin/activate

Windows PowerShell:

.\.venv\Scripts\Activate.ps1

이제 공식 SDK를 설치합니다.

python -m pip install -U google-genai

가상환경을 쓰면 다른 업무용 Python 프로그램과 패키지 버전이 섞이는 일을 줄일 수 있습니다.

3. API 키를 환경변수에 넣기

API 키를 Python 파일에 직접 적지 않습니다. 먼저 현재 터미널 세션의 환경변수로 설정하세요.

macOS 또는 Linux:

export GEMINI_API_KEY="여기에_발급받은_키"

Windows PowerShell:

$env:GEMINI_API_KEY="여기에_발급받은_키"

공식 SDK는 GEMINI_API_KEY를 자동으로 읽습니다. GOOGLE_API_KEY도 지원하지만 두 변수가 모두 설정되어 있으면 GOOGLE_API_KEY가 우선합니다. 처음에는 혼선을 피하려고 GEMINI_API_KEY 하나만 쓰는 것이 좋습니다.

위 명령은 현재 터미널 창에서만 유효합니다. 운영 서버에서는 Git 저장소의 파일이 아니라 호스팅 서비스의 Secrets, 환경변수 설정, 클라우드 시크릿 관리 기능에 키를 저장하세요.

4. 최소 Python 예제 실행하기

프로젝트 폴더에 app.py를 만들고 아래 코드를 저장합니다.

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="온라인 쇼핑몰의 배송 지연 안내 문구를 한국어 두 문장으로 써 줘.",
)

print(response.text)

실행합니다.

python app.py

터미널에 한국어 답변이 나오면 API 키, SDK, 네트워크 연결이 정상입니다. 이 예제의 호출 방식과 모델명은 Gemini API 공식 quickstart의 Python 최소 예제를 기준으로 했습니다.

모델은 새로 추가되거나 지원 상태가 바뀔 수 있습니다. 예제의 모델을 운영에 그대로 고정하기 전에 공식 모델 목록에서 현재 지원 여부, 안정 버전인지 preview인지, 입출력 형식과 가격을 확인하세요. 운영 서비스에는 가능하면 특정 안정 모델명을 명시하고, 모델 교체 전에는 결과 품질을 다시 테스트하는 편이 낫습니다.

5. 첫 호출이 실패할 때 확인할 것

`API key not valid` 또는 인증 오류

API 키 앞뒤에 공백이 들어가지 않았는지 확인합니다.
환경변수를 설정한 터미널과 python app.py를 실행한 터미널이 같은지 확인합니다.
GEMINI_API_KEY와 GOOGLE_API_KEY를 동시에 설정하지 않았는지 확인합니다.
오래된 키라면 API 키 문서에서 현재 키 유형과 제한 조건을 확인합니다.

`ModuleNotFoundError: No module named 'google'`

가상환경이 활성화된 상태에서 다시 설치합니다.

python -m pip install -U google-genai

`429` 또는 할당량 초과 오류

짧은 시간에 요청을 많이 보냈거나 분당 토큰, 일일 요청, 지출 기준 한도 가운데 하나를 넘었을 수 있습니다. 숫자를 추측하지 말고 AI Studio 사용량 화면에서 해당 프로젝트의 활성 한도를 확인하세요.

운영 코드에서는 429가 발생했을 때 즉시 같은 요청을 반복하지 말고 지수 백오프와 재시도 횟수 제한을 둡니다. 주문 처리처럼 중복 실행이 문제가 되는 업무라면 요청 ID를 저장해 같은 작업이 두 번 처리되지 않게 해야 합니다.

6. 무료 사용과 비용을 정확히 이해하기

Gemini API 가격표는 모델별로 무료 계층과 유료 계층을 구분합니다. 여기서 확인할 항목은 다음과 같습니다.

선택한 모델에 무료 계층이 있는가
입력 토큰과 출력 토큰의 유료 단가가 얼마인가
이미지, 오디오, 캐싱, 검색 연동 등 별도 과금 항목이 있는가
무료 계층과 유료 계층의 데이터 처리 조건이 어떻게 다른가
내 프로젝트에 결제가 연결되어 있는가

무료 계층 표시에 Free of charge가 있더라도 무제한이라는 뜻은 아닙니다. 실제 사용 가능 여부와 한도는 계정, 모델, 지역, 프로젝트 상태에 따라 달라질 수 있고 Google이 정책을 변경할 수도 있습니다. 또한 preview·experimental 모델은 일반적으로 한도가 더 제한적일 수 있습니다.

따라서 이 글에는 고정된 "하루 몇 회 무료" 숫자를 적지 않습니다. 게시 시점에 맞았던 숫자가 독자의 프로젝트에는 적용되지 않을 수 있기 때문입니다. 아래 두 페이지를 기준으로 판단하세요.

유료 계층이 필요하면 공식 결제 안내를 읽고 프로젝트에 결제를 설정합니다. 결제를 켜기 전에는 월 예산과 알림 기준을 먼저 정하세요. 결제 연결 자체를 비용 상한으로 오해해서는 안 됩니다. 요청 수, 입력 길이, 출력 길이를 애플리케이션에서도 제한해야 합니다.

7. rate limit은 세 숫자만 외우는 문제가 아니다

Google은 모델과 사용 등급에 따라 여러 제한을 적용합니다. 대표적으로 다음 지표가 있습니다.

RPM: 분당 요청 수
TPM: 분당 토큰 수
RPD: 일일 요청 수

이 가운데 하나만 넘어도 요청이 제한될 수 있습니다. 예를 들어 RPM 여유가 있어도 긴 문서를 한꺼번에 보내 TPM을 넘으면 실패할 수 있습니다. 제한은 프로젝트 단위이며, 문서에 표시된 값이 항상 보장되는 용량은 아닙니다. 정확한 현재 값은 rate limits 공식 문서와 AI Studio의 프로젝트 화면에서 확인하세요.

소규모 팀은 처음부터 복잡한 인프라를 만들 필요는 없지만 아래 장치는 넣는 편이 좋습니다.

한 사용자가 보낼 수 있는 요청 횟수 제한
입력 글자 수와 최대 출력 토큰 제한
429·5xx 오류에 대한 제한된 재시도
실패한 작업을 확인할 로그
일별 사용량 점검과 비용 알림

8. 운영에 넣기 전 보안 체크

API 키는 비밀번호처럼 다뤄야 합니다. Google의 공식 안내도 Git에 커밋하지 말고, 운영 웹·모바일 앱의 클라이언트 코드에 키를 넣지 말라고 명시합니다. 브라우저나 앱에 포함된 키는 사용자가 추출할 수 있습니다.

운영 구조는 다음처럼 잡습니다.

사용자 브라우저 또는 모바일 앱
        ↓
내 서버의 API 엔드포인트
        ↓  (서버가 비밀 환경변수에서 키를 읽음)
Gemini API

최소 보안 수칙은 다음과 같습니다.

키를 Git, 메신저, 공개 문서에 올리지 않습니다.
브라우저 JavaScript나 배포한 모바일 앱에 키를 넣지 않습니다.
개발·테스트·운영 프로젝트와 키를 분리합니다.
유출이 의심되면 즉시 키를 폐기하고 새로 발급합니다.
서버 로그에 API 키와 고객의 민감정보를 남기지 않습니다.
주민등록번호, 결제정보, 계약서 원문 같은 민감정보를 보내기 전 데이터 처리 약관과 내부 정책을 확인합니다.
사용자별 요청 제한, 입력 검증, 최대 출력 길이를 설정합니다.

무료 계층과 유료 계층은 데이터 처리 조건이 다를 수 있습니다. 고객 데이터를 다루는 서비스라면 가격표의 Used to improve our products 항목과 Gemini API 추가 약관을 함께 검토하세요. "API를 썼으니 입력 데이터가 자동으로 비공개"라고 가정하면 안 됩니다.

9. 작은 업무 하나로 시작하기

첫 프로젝트는 범위를 좁히는 것이 좋습니다. 예를 들면 고객 문의를 자동 발송하는 시스템보다, 사람이 검토할 답변 초안을 만드는 도구가 안전합니다.

다음 순서로 시험해 보세요.

반복되는 업무 하나를 고릅니다. 예: 배송 지연 답변 초안.
실제 개인정보를 제거한 샘플 20개로 결과를 확인합니다.
틀리면 피해가 큰 항목은 사람이 반드시 검토하게 합니다.
요청 수, 입력·출력 토큰, 실패율을 기록합니다.
일주일 뒤 실제 비용과 수정 시간을 보고 계속 쓸지 판단합니다.

API 연결에 성공한 것과 업무 자동화가 안전하게 완성된 것은 다른 문제입니다. 처음에는 결과를 바로 고객에게 보내지 말고 초안 생성 용도로 운영하세요.

마무리

Gemini API의 첫 연결은 API 키 발급, google-genai 설치, 환경변수 설정, 최소 Python 코드 실행으로 확인할 수 있습니다. 그다음부터는 모델 선택보다 운영 기준이 더 중요합니다. 내 프로젝트의 가격과 한도를 직접 확인하고, 키를 서버에만 보관하며, 사용량 제한과 사람의 검토 절차를 둬야 합니다.

무료 사용 가능 여부를 홍보 문구로 단정하지 마세요. 모델, 계정, 지역, 프로젝트 등급에 따라 조건이 달라질 수 있으므로 실제 AI Studio 화면과 공식 문서를 기준으로 판단해야 합니다.

출처

함께 읽을 가이드

공식 문서 확인 기준일: 2026년 7월 19일. 가격·모델·할당량은 변경될 수 있으므로 실행 전 연결된 공식 문서를 다시 확인하세요.

'🤖 1인 에이전트 구축기' 카테고리의 다른 글

n8n 워크플로우 무중단 운영을 위한 예외 처리 및 대체 모델 필수 체크리스트 (0)	2026.06.12
Gemini·Claude 교차검증 가이드: LLM 합의보다 근거를 비교하는 방법 (0)	2026.05.27
Claude API 재시도 설계: Node.js에서 중복과 장애를 함께 다루는 방법 (0)	2026.05.23
API Rate Limit 대응: 429 재시도·백오프·동시성 제한 설계 (0)	2026.05.23
Claude API 키 발급과 안전한 환경변수 설정: .gitignore·유출 대응·Secret Manager 가이드 (2026) (0)	2026.05.12