OpenAI SDK로 Gemini API 호출하기: base_url, key, 모델명만 바꾸는 연동 튜토리얼

Google은 이미 매우 분명하게 말했습니다. Gemini API는 OpenAI compatibility를 지원하며, OpenAI Python SDK, JavaScript SDK 및 REST로 호출할 수 있습니다. 공식 예시의 base_url은 https://generativelanguage.googleapis.com/v1beta/openai/이고, 모델명은 gemini-3.5-flash입니다（Google AI for Developers）。
이는 기존에 OpenAI SDK 코드를 보유한 팀에 매우 실용적입니다. 새로운 client를 다시 작성할 필요도 없고, 메시지 구조를 바꿀 필요도 없습니다. 먼저 세 가지 설정만 바꿔서 실행되게 한 뒤, Gemini의 네이티브 기능을 사용할지 결정하면 됩니다.

먼저 어디 세 군데를 바꿔야 하는지 보자

Google 문서는 예시 뒤에 매우 명확히 적고 있습니다. 바뀌는 것은 api_key, base_url, model 세 항목입니다. OpenAI Python SDK 자체도 base_url 또는 OPENAI_BASE_URL 설정을 지원하며（openai-python）, Node SDK의 대응 필드는 baseURL입니다（openai-node）。

최소 Python 예시:

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": "你是一个简洁的技术助手。"},
        {"role": "user", "content": "用一句话解释什么是向量数据库。"},
    ],
)

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

기존 코드가 이미 client.chat.completions.create()를 사용하고 있다면, 대부분은 client를 초기화하는 부분만 설정 항목으로 빼면 됩니다. 비즈니스 함수 안에 모델명을 하드코딩하지 마세요. 나중에 Batch, Flex로 전환하거나 모델을 바꿀 때 더 고통스러워집니다.

Node.js도 같은 방식이다

JavaScript 버전은 필드명만 base_url에서 baseURL로 바뀝니다:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.GEMINI_API_KEY,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

const resp = await client.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [{ role: "user", content: "给我一个 Redis 限流方案。" }],
});

console.log(resp.choices[0].message.content);

REST도 직접 호출할 수 있습니다. POST https://generativelanguage.googleapis.com/v1beta/openai/chat/completions를 사용하고, 요청 헤더에는 Authorization: Bearer $GEMINI_API_KEY를 넣으면 됩니다. 이 방법은 먼저 curl로 SDK, 프록시, 환경 변수 문제를 배제할 때 적합합니다.

가격은 감으로 보지 말고 출력 기준으로 계산하라

2026-06-14 기준, Gemini 공식 pricing 페이지에 기재된 gemini-3.5-flash 표준 가격은 입력 $1.50 / 1M tokens, 출력 $9.00 / 1M tokens이며, Batch와 Flex는 모두 입력 $0.75 / 1M tokens, 출력 $4.50 / 1M tokens입니다（Gemini API pricing）。공식 문서에는 출력 가격에 thinking tokens가 포함된다고도 명시되어 있으므로, 추론형 작업에서는 입력 가격만 보지 마세요.

모드	입력 / 1M tokens	출력 / 1M tokens	적합한 시나리오
Standard	$1.50	$9.00	온라인 요청, 낮은 지연 시간
Batch	$0.75	$4.50	오프라인 배치 처리
Flex	$0.75	$4.50	탄력적 스케줄링을 허용할 수 있는 경우

제안은 간단합니다. 채팅, Agent, 에디터 플러그인은 먼저 Standard로 가고, 로그 요약, 데이터 정제, 오프라인 평가는 가능하면 Batch/Flex를 사용하세요. 출력이 긴 작업에서는 비용 차이가 더 크게 벌어집니다.

마이그레이션할 때 가장 쉽게 밟는 함정

첫째, base_url 끝의 /openai/를 빠뜨리지 마세요. 많은 404나 모델 없음 문제는 본질적으로 Gemini 네이티브 경로로 요청을 보낸 것이지, 호환 경로가 아닙니다.
둘째, 환경 변수를 명확히 구분하세요. OPENAI_API_KEY는 계속 OpenAI용으로 쓰고, Gemini는 별도로 GEMINI_API_KEY에 넣는 것을 권장합니다. CI에서 두 provider가 같은 변수를 두고 충돌하게 만들지 마세요.
셋째, 먼저 models.list()를 실행하세요. Google 문서에는 모델 목록 조회와 모델 가져오기 예시가 있습니다. 운영 전에 이를 사용해 계정 리전, 권한, 모델 ID가 모두 문제없는지 확인하세요.
넷째, 스트리밍, 함수 호출, 이미지 입력 같은 기능은 호환 계층에 예시가 있지만, 모든 OpenAI 파라미터가 1:1로 지원된다고 기본 가정하지 마세요. 먼저 실제 비즈니스 요청 하나로 회귀 테스트를 하세요.

key 한 세트를 덜 관리하고 싶다면

팀에서 Claude, GPT, Gemini를 동시에 사용한다면, 각각 신청하고, 카드를 연결하고, 한도를 설정하는 일은 꽤 번거롭습니다. 더 간단한 경로는 onehop을 사용하는 것입니다. OpenAI SDK의 base_url을 https://api.onehop.ai/v1로 바꾸고 onehop의 key를 사용하면, OpenAI/Anthropic 호환 인터페이스로 Claude, GPT, Gemini를 호출할 수 있습니다. onehop의 포지셔닝은 연동 작업을 덜 번거롭게 해주는 것입니다. 가격은 공식보다 낮고, 신규 계정에는 $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="gemini-3.5-flash",
    messages=[{"role": "user", "content": "把这段报错日志总结成三条原因。"}],
)

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

Claude나 멀티 모델 라우팅을 테스트해보고 싶다면 바로 여기에서 확인할 수 있습니다: onehop에서 Claude 등 모델 호출하기. 먼저 작은 예시를 실행해보고 싶고 카드 연결은 원하지 않는다면 이入口를 이용하세요: 가입 즉시 $10 체험 크레딧 받기.

결론: 먼저 설정으로 만들고, 공급사를 하드코딩하지 말라

이번 Gemini의 OpenAI compatibility에서 가장 가치 있는 점은 “모델이 하나 더 생겼다”가 아니라 마이그레이션 비용이 충분히 낮다는 것입니다. base_url, api_key, model을 설정에 넣고, 비즈니스 코드는 계속 OpenAI SDK의 chat completions를 사용하세요.
실행이 확인된 뒤에는 세 가지를 보완하세요. 입력/출력 tokens를 기록하고, 작업에 따라 Standard 또는 Batch/Flex를 선택하며, 모델 ID를 점진 배포 스위치로 만드세요. 이렇게 하면 오늘 Gemini를 붙이고, 내일 Claude나 다른 호환 서비스를 붙이더라도 핵심 비즈니스 코드는 다시 건드리지 않아도 됩니다.