OpenAI SDK로 Gemini API 호출하기: base_url, API Key, 모델명만 바꾸는 마이그레이션 튜토리얼

2026-06-14 기준, Google의 Gemini OpenAI compatibility 문서는 매우 직설적으로 설명합니다. 이미 Python 또는 TypeScript용 OpenAI 라이브러리 코드를 쓰고 있다면 API Key, base_url, 모델명만 바꿔 Gemini에 연결할 수 있습니다. 문서 예시 모델은 gemini-3.5-flash이며, 호환성 페이지의 마지막 업데이트일은 2026-05-18입니다(Google AI for Developers). 이것은 “어댑터 레이어의 마법”이 아니라, OpenAI SDK의 요청을 Google이 제공하는 호환 엔드포인트로 보내는 것뿐입니다.

먼저 SDK를 설치하고, 호출 방식은 바꾸지 마세요

프로젝트에서 이미 공식 OpenAI Python SDK를 사용 중이라면 chat.completions.create()를 그대로 두면 됩니다. OpenAI의 Python SDK 저장소는 여전히 공식 클라이언트의 출처이며(openai-python), Google 호환 인터페이스도 이 호출 형태를 받아들입니다.

from openai import OpenAI

client = OpenAI(
    api_key="GEMINI_API_KEY",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

resp = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[
        {"role": "system", "content": "You are a concise code reviewer."},
        {"role": "user", "content": "Review this Python function for edge cases."},
    ],
)

print(resp.choices[0].message.content)

API Key는 Google AI Studio에서 생성합니다(AI Studio API key). 끝의 슬래시에 주의하세요. /v1beta/openai/이며, 일반 Gemini 네이티브 인터페이스의 /v1beta/models/...가 아닙니다.

REST도 OpenAI 형태로 호출할 수 있습니다

서버, curl 디버깅, 게이트웨이 헬스 체크에 반드시 SDK가 필요한 것은 아닙니다. Google 호환 문서에서 제시하는 REST 경로는 /openai/chat/completions입니다.

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [
      {"role": "user", "content": "Give me a 5-point migration checklist."}
    ]
  }'

마이그레이션할 때는 먼저 이 명령을 실행해 보세요. Key, 모델명, 네트워크 출구, 결제 권한이라는 네 가지 문제를 분리해 확인할 수 있어, 비즈니스 서비스 안에서 바로 debug하는 것보다 시간을 절약할 수 있습니다.

reasoning_effort는 어떻게 매핑되나

Gemini의 thinking 제어와 OpenAI의 reasoning_effort는 겹치는 부분이 있으며, Google은 둘을 동시에 전달하지 말라고 명확히 말합니다. 호환 레이어는 OpenAI 스타일 파라미터를 Gemini thinking 파라미터로 매핑합니다(Google OpenAI compatibility).

OpenAI reasoning_effort	Gemini 3 thinking_level	Gemini 2.5 thinking_budget
minimal	minimal 또는 low	1024
low	low	1024
medium	medium	8192
high	high	24576

보수적으로 마이그레이션하려면 먼저 reasoning_effort를 전달하지 말고, 모델이 기본값을 사용하게 하세요. 비용을 제어하고 싶다면 긴 컨텍스트 작업에 low를 추가한 뒤 출력 품질과 token 청구액을 관찰하세요.

가격은 모델명만 보지 마세요

Google 공식 가격 페이지는 Gemini 2.5 Pro와 Flash의 표준 가격을 명확히 제시하며, 단위는 100만 token당 가격이고 출력 가격에는 thinking tokens가 포함됩니다(Gemini API pricing).

모델	입력 가격	출력 가격
gemini-2.5-pro, prompt ≤ 200k	$1.25	$10.00
gemini-2.5-pro, prompt > 200k	$2.50	$15.00
gemini-2.5-flash, 텍스트/이미지/동영상 입력	$0.30	$2.50
gemini-2.5-flash, 오디오 입력	$1.00	$2.50

제 추천은 이렇습니다. 채팅, 분류, 가벼운 코드 작업은 먼저 Flash를 사용하세요. 복잡한 추론, 긴 문서 종합, 코드 리팩터링은 그다음 Pro로 전환하세요. Pro의 200k prompt 임계값은 입력과 출력 단가에 직접 영향을 주므로, 로그, 검색 조각, 반복되는 system prompt를 한꺼번에 밀어 넣지 마세요.

마이그레이션 체크리스트

1. OPENAI_API_KEY를 GEMINI_API_KEY로 바꾸고, AI Studio에서 생성합니다.
2. base_url을 https://generativelanguage.googleapis.com/v1beta/openai/로 변경합니다.
3. 모델명을 호환 Gemini 모델, 예를 들어 gemini-3.5-flash로 바꿉니다.
4. 먼저 REST curl로 연결을 확인한 뒤 SDK에 다시 연결합니다.
5. 사용자 지정 reasoning_effort는 잠시 중단하고, 품질을 확인한 뒤 다시 추가합니다.
6. 입력, 출력, thinking token 비용을 기록합니다. 특히 Pro의 200k 임계값에 주의하세요.

Claude/GPT도 함께 연결해야 한다면

Gemini만 연결한다면 Google 공식 호환 엔드포인트를 쓰는 것이 가장 깔끔합니다. 하지만 프로젝트에서 Claude, GPT, Gemini를 동시에 써야 하는 순간, 여러 Key, 여러 청구, 여러 SDK가 상당히 번거로워집니다. 간편한 경로는 onehop입니다. OpenAI/Anthropic과 호환되며, base_url을 https://api.onehop.ai/v1로 바꾸면 같은 OpenAI SDK로 Claude/GPT/Gemini를 호출할 수 있습니다. 공식보다 낮은 가격, 신규 계정 $10 제공, 카드 등록 불필요를 내세웁니다.

from openai import OpenAI

client = OpenAI(
    api_key="ONEHOP_API_KEY",
    base_url="https://api.onehop.ai/v1",
)

resp = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.5",
    messages=[{"role": "user", "content": "Refactor this API handler."}],
)
print(resp.choices[0].message.content)

지금 당장 여러 모델 연결을 실행해 보고 싶다면 바로 시도해 볼 수 있습니다. onehop에서 Claude 등 모델 호출하기, 또는 먼저 크레딧을 받으세요. 가입 즉시 $10 체험 크레딧 제공. 마이그레이션의 핵심은 추상화 레이어를 잔뜩 바꾸는 것이 아니라, 변수를 세 가지로 수렴시키는 것입니다. endpoint, key, model.