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

Google은 핵심을 아주 직설적으로 설명합니다. Gemini models는 OpenAI의 Python 및 TypeScript/JavaScript SDK를 통해 접근할 수 있으며, 핵심은 코드 세 줄만 바꾸는 것입니다. 공식 호환 문서에 나온 엔드포인트는 https://generativelanguage.googleapis.com/v1beta/openai/이고, 예시 모델은 gemini-3.5-flash입니다（Google OpenAI 호환성）. 이는 기존 OpenAI SDK 프로젝트에 매우 유리합니다. 먼저 provider 추상화를 뜯어고칠 필요도 없고, 전체 호출 스택을 바꿀 필요도 없으며, 일단 실행되게 만들면 됩니다.

먼저 호출할 모델을 확인하세요

2026-06-14 기준, Google 모델 페이지는 Gemini 3.5 Flash를 Stable로 표시하며, 모델 코드는 gemini-3.5-flash라고 설명합니다. 이 모델의 입력 한도는 1,048,576 tokens, 출력 한도는 65,536 tokens이며, 텍스트, 이미지, 동영상, 오디오, PDF 입력을 지원하고 출력은 텍스트입니다（Gemini 3.5 Flash）. 모델 페이지는 2026-05-19 UTC에 마지막으로 업데이트되었습니다.

가격도 당일 문서를 확인해야 합니다. Google 가격 페이지는 2026-06-09 UTC에 마지막으로 업데이트되었으며, gemini-3.5-flash Standard paid tier의 가격은 입력 $1.50 / 1M tokens, 출력 $9.00 / 1M tokens로 표시되어 있습니다. 출력 가격에는 thinking tokens가 포함됩니다. Batch는 입력 $0.75, 출력 $4.50입니다（Gemini API 가격）.

모델	상태	입력 한도	Standard 입력	Standard 출력
gemini-3.5-flash	Stable	1,048,576	$1.50 / 1M tokens	$9.00 / 1M tokens
gemini-3-flash-preview	Preview	모델 페이지 참조	$0.50 / 1M tokens	$3.00 / 1M tokens
gemini-3.1-flash-lite	Stable	모델 페이지 참조	$0.25 / 1M tokens	$1.50 / 1M tokens

gemini-3-flash-preview와 gemini-3.1-flash-lite는 Google의 현재 모델 및 가격 페이지에서 가져온 것입니다（모델、가격）. Preview 모델을 곧바로 프로덕션 기본값으로 삼지 마세요. 버전과 한도가 바뀔 수 있습니다.

Python: OpenAI client를 Gemini로 향하게 하기

먼저 SDK를 설치합니다.

pip install openai
export GEMINI_API_KEY="你的 Gemini API Key"

그다음 OpenAI SDK의 호출 방식을 그대로 유지합니다.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["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": "用三句话解释什么是 API 兼容层。"},
    ],
)

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

실제 변경점은 세 곳뿐입니다. api_key를 Gemini key로 바꾸고, base_url을 Google의 OpenAI-compatible endpoint로 바꾸며, model을 Gemini 모델명으로 바꾸는 것입니다. 공식 예시의 URL 끝에는 /가 있다는 점에 주의하세요. 괜히 지웠다가 404를 디버깅하느라 시간을 쓰지 마세요.

TypeScript: 마찬가지로 baseURL입니다

Node 프로젝트에서도 동일합니다.

npm install openai
export GEMINI_API_KEY="你的 Gemini API Key"

import OpenAI from "openai";

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

const response = await openai.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    { role: "user", content: "给我一个 JSON Schema 校验的最小例子。" },
  ],
});

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

프로젝트에서 이미 provider를 환경 변수로 감싸 두었다면 변경은 더 적습니다.

OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
OPENAI_API_KEY="$GEMINI_API_KEY"
OPENAI_MODEL="gemini-3.5-flash"

많은 오래된 프로젝트의 함정은 여기에 있습니다. 변수명이 여전히 OPENAI_API_KEY여도 괜찮습니다. 값은 Gemini key일 수 있습니다. 요청이 실제로 어디로 가는지를 결정하는 것은 base_url/baseURL입니다.

스트리밍, 도구 호출, thinking은 어떻게 할까요

Google 호환 문서는 streaming, function calling, structured outputs, image understanding 등의 예시를 제공합니다（OpenAI 호환성）. 기존 OpenAI SDK 프로젝트는 보통 먼저 세 가지를 검증합니다. 일반 chat, stream=True, tools/function calling입니다. 모두 통과한 뒤 모델 고유 기능을 처리하면 됩니다.

thinking 파라미터는 신중해야 합니다. 호환 문서에는 OpenAI의 reasoning_effort가 Gemini의 thinking 설정으로 매핑된다고 되어 있습니다. 하지만 Gemini 3 및 일부 2.5 모델에서는 thinking을 완전히 끌 수 없습니다. 제안은 간단합니다. 첫 버전에서는 thinking을 조정하지 말고, 기본값으로 품질과 비용 기준선을 먼저 세운 뒤, 긴 작업, 코드 에이전트, 복잡한 추론 경로에서 별도로 부하 테스트를 하세요.

관리해야 할 Key를 줄이고 싶다면

공식 직접 연결은 진지한 프로덕션에 적합합니다. 청구, 한도, 데이터 정책이 모두 명확하기 때문입니다. 문제는 팀이 보통 Gemini만 쓰지 않는다는 점입니다. Claude, GPT도 써야 하고, 심지어 서로 다른 도구에 서로 다른 key를 넣어야 할 수도 있습니다. 간편한 경로는 onehop을 사용하는 것입니다. OpenAI SDK의 base URL을 https://api.onehop.ai/v1로 바꾸면, 동일한 OpenAI/Anthropic 호환 진입점으로 Claude/GPT/Gemini를 호출할 수 있습니다. 신규 계정은 $10를 제공하며, 카드 등록이 필요 없어 데모와 내부 도구를 먼저 돌려보기에 적합합니다.

import os
from openai import OpenAI

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

resp = client.chat.completions.create(
    model=os.environ["ONEHOP_MODEL"],
    messages=[{"role": "user", "content": "把这段日志总结成 5 条排障线索。"}],
)

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

여기서는 의도적으로 model을 환경 변수에 넣었습니다. 게이트웨이의 모델명은 콘솔 기준으로 삼아야 하며, 코드에 하드코딩하지 마세요. 여러 공급사의 청구와 호환 레이어를 덜 신경 쓰고 싶다면 바로 시도해 볼 수 있습니다. onehop에서 Claude 등 모델 호출하기, 또는 먼저 크레딧을 받을 수도 있습니다. 가입 즉시 $10 체험 크레딧 받기.

연동 전 마지막 점검

출시 전에는 텍스트가 반환되는지만 확인하지 마세요. 최소 네 가지를 점검해야 합니다. 첫째, 해당 모델이 Google 현재 모델 페이지에서 여전히 사용 가능한지 확인합니다. 둘째, 가격 페이지에서 입력, 출력, Batch, Search grounding 비용을 대조합니다. 셋째, 401, 429, 5xx 오류 로그를 완전하게 남깁니다. 넷째, base_url, api_key, model을 런타임 설정으로 만들어, 모델을 바꾸기 위해 배포가 필요하지 않게 합니다.

이번 연동의 핵심은 “모델 공급사를 바꾸는 것”이 아니라 SDK 레이어와 모델 공급사를 분리하는 것입니다. 먼저 Google 공식 OpenAI compatibility로 gemini-3.5-flash를 실행되게 만든 뒤, 직접 연결, 게이트웨이, 또는 둘의 병행 중 무엇을 선택할지 결정하세요. 이렇게 하면 변경이 작고 롤백도 빠릅니다.