Gemini API 연동 가이드: AI Studio, API 키, 첫 호출 (2026)

Gemini API를 연동하는 가장 짧은 경로는 Google 계정으로 AI Studio를 열고, API 키를 만들고, SDK를 설치한 뒤 첫 generateContent 요청을 보내는 것입니다. 순조롭게 진행되면 전체 과정이 20분을 넘지 않습니다. 실제로 막히는 지점은 "호출이 되는가"가 아니라 진입점을 잘못 선택하는 것, 모델 ID를 잘못 쓰는 것, 무료 등급과 유료 등급을 혼동하는 것, 키를 잘못된 위치에 두는 것입니다.

이 글은 실제 연동 순서를 따릅니다. 먼저 AI Studio와 Vertex AI를 구분하고, 키 생성, SDK 설치, curl과 Python 요청, 모델 이름, 시스템 지시, 스트리밍 출력, 안전 설정을 다룬 뒤 마지막으로 400, 403, 429의 흔한 원인과 키 보안 체크리스트를 정리합니다.

안내: Google과 Gemini는 Google LLC의 상표입니다. 모델 이름, 무료 할당량, 과금 규칙은 조정될 수 있습니다. 이 글은 2026년 10월의 일반적인 절차를 기준으로 하며, 구체적인 내용은 Google 공식 문서와 사이트 내 모델 가격 페이지를 기준으로 합니다.

1. 먼저 AI Studio와 Vertex AI 구분하기

Gemini API에는 두 가지 주요 진입점이 있고 계정 체계와 관리 방식이 다릅니다. 잘못 선택하면 권한이나 정산에서 다시 작업해야 합니다.

비교 항목	Google AI Studio	Vertex AI
진입점	브라우저 콘솔, 개발자 빠른 체험용	Google Cloud 콘솔, 프로젝트 기반 사용
계정 요구 사항	Google 계정만 있으면 시작 가능	Cloud 프로젝트, 결제 계정, IAM 권한
자격 증명	AI Studio에서 생성한 API 키	서비스 계정 또는 통제된 키와 IAM
과금	무료 등급과 유료 등급 병존	Cloud 프로젝트 기준 정산
리전과 데이터	AI Studio 약관 적용	리전 선택 가능, Cloud 약관과 프로젝트 설정에 따름
적합한 상황	프로토타입, 학습, 소규모 검증	운영 시스템, 감사와 권한 요구가 높은 팀

개인 개발자와 소규모 팀은 보통 AI Studio로 절차를 먼저 익힙니다. 계약, 데이터 리전, 통합 감사가 필요해지면 Vertex AI를 검토하세요. 두 진입점의 키, 할당량, 청구서를 섞어 쓰지 말고, AI Studio 키로 Vertex AI 인터페이스를 호출하지도 마세요.

2. 첫 API 키 생성

Google 계정으로 Google AI Studio에 로그인합니다.
API Key 관리 페이지로 이동해 API Key 생성을 선택합니다.
Google Cloud 프로젝트를 선택합니다. 프로젝트가 없으면 페이지 안내에 따라 새로 만듭니다.
생성된 키를 복사해 즉시 서버 환경 변수나 비밀번호 관리자에 저장합니다.
Playground에서 테스트 메시지를 보내 키와 모델이 사용 가능한지 확인합니다.
나중에 교체와 폐기가 쉽도록 키에 용도를 알 수 있는 이름을 붙입니다.

AI Studio는 체험용 무료 등급을 제공하며, 사용 가능한 모델, 요청 속도, 할당량은 계정과 시기에 따라 달라집니다. 연결된 Cloud 프로젝트에서 결제를 활성화하면 유료 등급으로 전환할 수 있습니다. 오래된 글의 할당량 숫자를 현재의 약속으로 받아들이지 말고, 콘솔에 실제로 표시되는 내용과 공식 설명을 기준으로 하세요.

키를 만든 뒤에는 어느 Cloud 프로젝트에 속하는지 먼저 확인하세요. 할당량은 보통 프로젝트 단위로 계산되므로 테스트와 운영을 섞으면 다른 사람의 할당량을 소진할 수 있습니다. 더 높은 할당량이 필요하면 Cloud 프로젝트에서 결제를 활성화하고 예산 알림을 설정한 뒤 일주일간 실제 사용량을 관찰하세요.

3. SDK 설치와 첫 요청

Python 환경은 3.10 이상을 권장하며 가상 환경에 공식 SDK를 설치합니다.

python3 -m venv .venv
source .venv/bin/activate
pip install -U google-genai
export GEMINI_API_KEY="여기에-키"

먼저 curl로 SDK 외의 요인을 배제합니다. 모델 ID는 자리표시자로 두고 실제 이름은 모델 목록이나 사이트 가격 페이지에서 가져오세요.

curl "https://generativelanguage.googleapis.com/v1beta/models/<모델ID>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "API 게이트웨이가 무엇인지 한 문장으로 설명해 주세요"}]}
    ],
    "generationConfig": {"maxOutputTokens": 256, "temperature": 0.7}
  }'

curl이 200을 반환하면 Python SDK로 넘어갑니다.

import os
from google import genai

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

resp = client.models.generate_content(
    model="<모델ID>",
    contents="API 게이트웨이가 무엇인지 한 문장으로 설명해 주세요",
)
print(resp.text)

model에는 전체 모델 ID를 적고 계열 이름만 적지 마세요. 모델마다 지원하는 입력 유형과 파라미터가 다르므로 잘못 쓰면 400이나 404로 나타납니다.

4. 모델 이름, 시스템 지시, 생성 파라미터

Gemini의 모델 ID는 보통 계열과 버전으로 구성됩니다. 가장 안전한 방법은 현재 계정에서 사용 가능한 모델 목록을 먼저 조회하는 것입니다.

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

목록에 없는 모델은 추측하지 마세요. 모델을 고를 때는 작업별로 나눕니다. 가벼운 작업에는 지연이 낮은 등급을, 복잡한 추론과 긴 문서에는 높은 등급을 사용합니다. 구체적인 등급과 가격은 모델 가격 페이지를 기준으로 합니다.

모델 ID는 버전이 올라가면 바뀌고 이전 ID는 사용 중단으로 표시되거나 바로 종료될 수 있습니다. 모델 이름을 설정 파일에 두고 코드 곳곳에 흩어 두지 마세요. 업그레이드 시 한 곳만 수정하고 회귀 샘플로 출력이 크게 달라지지 않았는지 확인합니다.

시스템 지시는 역할과 출력 규칙을 고정하며 번역, 추출, 고객지원 같은 시나리오에 적합합니다.

resp = client.models.generate_content(
    model="<모델ID>",
    contents="이 문장을 영어로 번역하세요: 연동 완료",
    config={"system_instruction": "당신은 기술 문서 번역가이며 번역문만 출력합니다."},
)

자주 쓰는 생성 파라미터는 temperature, maxOutputTokens, topP입니다. 구조화된 결과가 필요하면 모델이 JSON을 반환하도록 하고 코드에서 파싱과 검증을 수행하세요. 모델이 형식을 반드시 지킨다고 가정하지 말고 실패 재시도와 폴백 로직을 미리 작성해야 합니다.

5. 스트리밍 출력과 안전 설정

스트리밍 출력은 채팅 인터페이스와 긴 답변에 적합합니다. REST 인터페이스는 메서드 뒤에 :streamGenerateContent를 붙이고 alt=sse를 함께 사용하며, Python SDK는 generate_content_stream을 사용합니다.

for chunk in client.models.generate_content_stream(
    model="<모델ID>",
    contents="속도 제한이 무엇인지 세 가지로 설명해 주세요",
):
    print(chunk.text, end="")

안전 설정은 범주별로 차단 기준을 조정할 수 있으며, 일반적인 범주에는 괴롭힘, 혐오, 성적 콘텐츠, 위험 콘텐츠가 있습니다. 기본 기준은 대부분의 업무에 적합합니다. 차단을 낮추면 허용 범위가 넓어지므로 제품 정책과 현지 규정을 함께 검토해야 합니다. 특히 공개 대상 제품에서 테스트를 통과시키기 위해 안전 설정을 전부 끄지 마세요.

6. 400, 403, 429 점검 방법

상태 코드	흔한 원인	처리 방향
400	JSON 구조 오류, 지원하지 않는 파라미터, 모델 ID와 인터페이스 불일치	요청 본문을 필드별로 확인하고 최소 요청부터 시도
403	키가 유효하지 않거나 제한됨, API 미활성화, 프로젝트 또는 지역 제한	다른 키로 검증하고 프로젝트 권한과 계정 상태 확인
404	모델 ID 오타, 인터페이스 버전이나 경로 오류	모델 목록을 조회하고 `v1beta`와 메서드 이름 확인
429	무료 등급 할당량 소진, 분당 요청 초과, 동시성 과다	지수 백오프 재시도, 동시성 축소, 유료 등급 검토
500/503	서버 일시 장애	제한된 횟수로 재시도, 지속 실패 시 폴백 또는 경로 전환

429가 나오면 즉시 재전송하지 마세요. 올바른 방법은 백오프에 무작위 지터를 더하고 최대 재시도 횟수를 설정하며 실패 요청을 로그에 기록하는 것입니다. 무료 등급은 속도 제한이 더 엄격한 경우가 많으므로 부하 테스트와 배치 작업은 따로 일정을 잡으세요.

7. 키 보안 체크리스트

키는 서버 환경 변수나 시크릿 관리 서비스에만 두고 프런트엔드, 저장소, 채팅 기록에 남기지 않습니다.
운영, 테스트, 개발에 각각 다른 키를 쓰고 환경별로 할당량과 권한을 격리합니다.
정기적으로 교체하고 퇴사나 프로젝트 종료 시 즉시 폐기합니다.
클라우드 콘솔에서 키가 호출할 수 있는 API를 제한해 유출 시 영향을 줄입니다.
사용량 알림을 켜고 비정상 호출이 보이면 먼저 키를 중지한 뒤 조사합니다.
스크린샷, 화면 녹화, 티켓에 전체 키를 노출하지 않습니다.

8. OpenAI 호환 진입점으로 Gemini 사용하기

팀에 이미 OpenAI SDK와 호출 코드가 있다면 ZSQH AI Gateway의 OpenAI 호환 진입점을 사용할 수 있습니다. Base URL은 https://ai.zhongshangqihang.com/v1이며 base_url, api_key, model 세 곳만 바꾸면 됩니다.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model="<가격 페이지의 Gemini 모델 이름>",
    messages=[{"role": "user", "content": "OK만 답하세요"}],
)
print(resp.choices[0].message.content)

이 방식은 멀티 모델 청구 통합, 위안화 정산, 중국 내 네트워크 환경이 필요한 팀에 적합합니다. Gemini 원본의 파라미터와 멀티모달 필드가 완전히 호환된다고 가정할 수 없으므로 마이그레이션 전에 실제 요청으로 항목별 검증하세요. 가입 진입점은 가입 페이지이며, 모델과 가격은 모델 가격 페이지를 기준으로 합니다.

자주 묻는 질문

Gemini API에 무료 할당량이 있나요?

AI Studio는 무료 등급을 제공하지만 사용 가능한 모델, 속도, 할당량은 변하며 데이터 약관이 유료 등급과 다를 수 있습니다. 프로토타입 검증에는 무료 등급을 쓸 수 있지만 정식 업무에는 유료 등급 기준으로 할당량과 비용을 다시 평가하는 것이 좋습니다.

API 키가 유출되면 어떻게 해야 하나요?

먼저 콘솔에서 키를 폐기하거나 교체한 뒤 사용량 로그로 비정상 호출 범위를 확인하고, 마지막으로 유출 경로를 조사하세요. 코드에서 키만 삭제하는 것으로는 부족하며, 이미 유출된 자격 증명은 무효로 처리해야 합니다.

중국 내 네트워크에서 Gemini API를 직접 호출할 수 있나요?

회선 품질은 지역과 통신사에 따라 다르며 시간 초과나 연결 실패가 발생할 수 있습니다. 흔한 방법은 안정적으로 접속 가능한 서버에서 요청을 보내거나 OpenAI 호환 인터페이스를 지원하는 게이트웨이를 사용하는 것입니다. 구체적인 제한은 실제 회선과 공식 설명을 기준으로 하세요.

curl은 되는데 Python SDK에서 오류가 나는 이유는 무엇인가요?

먼저 SDK 버전과 의존성이 최신인지 확인하고, model 표기, 프록시 설정, 환경 변수가 일치하는지 점검하세요. SDK에서 404가 나면 모델 ID와 인터페이스 경로를 중점적으로 확인하고 여러 변수를 동시에 바꾸지 마세요.

Gemini API를 OpenAI SDK로 직접 호출할 수 있나요?

Google은 OpenAI 호환 진입점을 제공하며 중국 내 게이트웨이도 호환 계층을 일반적으로 제공하지만, 지원하는 파라미터 범위는 다릅니다. 멀티모달, 도구 호출, 구조화 출력은 실제 요청으로 검증해야 하며 완전히 동등하다고 가정할 수 없습니다.

다음 단계

먼저 이 글의 절차로 최소 요청을 성공시킨 뒤 업무 로그, 재시도, 사용량 모니터링을 연결하세요. 하나의 백오피스에서 Gemini와 다른 모델의 호출량, 위안화 청구서, 키 권한을 관리하려면 ZSQH AI Gateway에 가입하는 것부터 시작할 수 있습니다. 가격은 모델 가격을 참고하세요.