Claude, GPT, Gemini, Llama, DeepSeek를 각각 쓰려면 API 키 5개, 청구서 5개, 레이트 리밋 각개격파입니다. OpenRouter는 이걸 하나로 통합합니다. 모델만 바꾸면 됩니다. 코드는 그대로입니다.
[핵심 요약]
OpenRouter는 300개 이상의 AI 모델을 단일 API 엔드포인트로 제공하는 LLM 게이트웨이입니다. OpenAI 호환 API라서 base_url만 바꾸면 기존 코드가 그대로 동작합니다. 가격은 프로바이더 직접 가격에 5.5% 플랫폼 크레딧 수수료가 붙는 구조이며, 마크업은 없습니다. 무료 티어로 Gemma, Llama, Mistral 등 25개 이상의 무료 모델을 신용카드 없이 사용할 수 있습니다. BYOK(자체 API 키 연결) 방식은 월 100만 요청까지 무료이고 이후 5% 수수료가 적용됩니다. 프로바이더 장애 시 자동 대체 모델로 전환하는 폴백 라우팅도 지원하며, :free, :nitro, :floor, :thinking, :extended 등의 모델 variant를 선택할 수 있습니다.
OpenRouter가 필요한 이유
여러 AI 모델을 직접 API로 관리하면 번거로운 일이 쌓입니다. Anthropic, OpenAI, Google, Together AI, DeepSeek 각각에 API 키를 만들고, 청구서를 따로 확인하고, 레이트 리밋을 각개격파해야 합니다. 모델을 전환할 때마다 코드 구조가 달라지고, SDK 문서도 따로 읽어야 합니다.
OpenRouter를 쓰면 API 키 하나로 300개 이상의 모델에 접근하고, 청구서는 크레딧 차감 방식으로 하나로 통합됩니다. 모델 전환은 model 파라미터 문자열 하나만 바꾸면 끝이고, OpenAI SDK를 그대로 사용할 수 있습니다. 프로바이더 장애가 생기면 자동 폴백 라우팅이 처리합니다.
실전 1 — 계정 세팅
가입 및 크레딧 충전
계정 세팅 순서는 단순합니다. https://openrouter.ai에 접속해 GitHub 또는 Google 소셜 로그인으로 가입합니다. API 키는 Settings → API Keys → Create Key에서 생성하며, Credit limit을 설정해두면 예산을 초과했을 때 자동으로 차단됩니다. 생성된 키는 즉시 복사해야 합니다. 다시 볼 수 없습니다.
유료 모델을 쓰려면 Settings → Credits → Add Credits에서 크레딧을 충전합니다. 신용카드, 암호화폐, 계좌이체를 지원하며 최소 금액 제한이 없고 크레딧 만료도 없습니다. 크레딧 없이 바로 시작하고 싶다면 무료 모델을 쓰면 됩니다. 하루 50 요청이 기본이고, 크레딧 $10 이상 보유 시 1,000 요청으로 늘어납니다.
환경변수 설정
# .env
OPENROUTER_API_KEY=sk-or-v1-...
# 선택: 요청 메타데이터 (OpenRouter 모니터링 대시보드 식별용)
OPENROUTER_SITE_URL=https://myapp.com
OPENROUTER_APP_NAME=MyApp
실전 2 — 첫 API 호출
OpenRouter의 핵심은 기존 OpenAI SDK 코드에서 base_url만 교체하면 된다는 점입니다. 새로운 SDK를 배울 필요가 없고, 이미 작성한 코드를 그대로 재사용할 수 있습니다.
Python — OpenAI SDK 재사용
# pip install openai python-dotenv
from openai import OpenAI
import os
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ["OPENROUTER_API_KEY"],
)
response = client.chat.completions.create(
model="anthropic/claude-sonnet-4-6", # 모델 문자열만 바꾸면 됨
messages=[
{"role": "user", "content": "OpenRouter를 한 줄로 설명해줘"}
],
extra_headers={
"HTTP-Referer": os.environ.get("OPENROUTER_SITE_URL", ""),
"X-Title": os.environ.get("OPENROUTER_APP_NAME", ""),
}
)
print(response.choices[0].message.content)
print(f"사용 토큰: {response.usage.total_tokens}")
extra_headers의 HTTP-Referer와 X-Title은 선택 항목이지만, OpenRouter 대시보드에서 요청을 앱별로 구분할 때 유용합니다.
TypeScript/JavaScript
// npm install openai
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://openrouter.ai/api/v1",
apiKey: process.env.OPENROUTER_API_KEY,
defaultHeaders: {
"HTTP-Referer": process.env.OPENROUTER_SITE_URL ?? "",
"X-Title": process.env.OPENROUTER_APP_NAME ?? "",
},
});
const response = await client.chat.completions.create({
model: "google/gemini-3-flash",
messages: [
{ role: "user", content: "OpenRouter를 한 줄로 설명해줘" }
],
});
console.log(response.choices[0].message.content);
순수 fetch (SDK 없이)
SDK를 쓰지 않고 httpx로 직접 호출할 수도 있습니다. 이 방식은 응답에서 OpenRouter 고유의 비용 메타데이터를 바로 추출할 수 있다는 장점이 있습니다.
import httpx
import os
response = httpx.post(
"https://openrouter.ai/api/v1/chat/completions",
headers={
"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
"Content-Type": "application/json",
"HTTP-Referer": "https://myapp.com",
"X-Title": "MyApp",
},
json={
"model": "meta-llama/llama-3.3-70b-instruct",
"messages": [
{"role": "user", "content": "안녕하세요"}
]
}
)
data = response.json()
print(data["choices"][0]["message"]["content"])
print(f"비용: ${data.get('usage', {}).get('cost', 0):.6f}")
실전 3 — 모델 식별자 체계
OpenRouter의 모델 ID는 {provider}/{model-name}:{variant} 형식으로 구성됩니다. variant는 선택 항목이며 없으면 기본 라우팅이 적용됩니다. 자주 쓰는 모델 ID를 미리 알아두면 편합니다.
# 주요 모델 ID 예시
"anthropic/claude-sonnet-4-6" # Claude Sonnet 4.6
"anthropic/claude-opus-4-7" # Claude Opus 4.7
"openai/gpt-5.4" # GPT-5.4
"openai/gpt-4o-mini" # GPT-4o Mini
"google/gemini-3-flash" # Gemini 3 Flash
"google/gemini-3.1-flash-lite" # Gemini 3.1 Flash Lite
"meta-llama/llama-3.3-70b-instruct" # Llama 3.3 70B
"deepseek/deepseek-chat" # DeepSeek V3
"mistralai/mistral-large" # Mistral Large
"x-ai/grok-beta" # Grok
모델 variant 종류
variant는 같은 모델을 다른 방식으로 라우팅하거나 기능을 바꿀 때 씁니다. :free는 크레딧 소모 없이 무료로 사용하는 버전, :nitro는 가장 빠른 프로바이더로 라우팅해 처리량을 최적화, :floor는 가장 저렴한 프로바이더로 라우팅해 비용을 최소화합니다. :thinking은 추론 모드를 활성화하고, :extended는 더 긴 컨텍스트 윈도우를 사용합니다.
model = "meta-llama/llama-3.3-70b-instruct:free" # 무료
model = "anthropic/claude-sonnet-4-6:nitro" # 속도 최적화
model = "anthropic/claude-sonnet-4-6:floor" # 비용 최적화
model = "anthropic/claude-opus-4-7:thinking" # 추론 모드
model = "openai/gpt-5.4:extended" # 긴 컨텍스트
전체 모델 목록 API로 가져오기
사용 가능한 모델 목록은 API로 실시간으로 조회할 수 있습니다. 무료 모델만 필터링하거나, 툴 콜링 지원 여부로 필터링하는 것도 가능합니다.
import httpx
import os
response = httpx.get(
"https://openrouter.ai/api/v1/models",
headers={"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"}
)
models = response.json()["data"]
# 무료 모델만 필터링
free_models = [
m for m in models
if m.get("pricing", {}).get("prompt") == "0"
]
print(f"무료 모델 수: {len(free_models)}")
for m in free_models[:5]:
print(f" {m['id']} — 컨텍스트: {m.get('context_length', 'N/A')}K")
# 툴 콜링 지원 모델 필터링
tool_calling_models = [
m for m in models
if "tools" in m.get("supported_parameters", [])
]
실전 4 — 주요 모델 선택 가이드
2026년 5월 기준 주요 모델 가격과 컨텍스트를 정리했습니다.
모델 ID 입력 출력 컨텍스트
| anthropic/claude-opus-4-7 | $5.00 | $25.00 | 1M |
| anthropic/claude-sonnet-4-6 | $3.00 | $15.00 | 1M |
| anthropic/claude-haiku-4-5 | $0.80 | $4.00 | 200K |
| openai/gpt-5.4 | $2.00 | $8.00 | 128K |
| openai/gpt-4o-mini | $0.15 | $0.60 | 128K |
| google/gemini-3-flash | $0.10 | $0.40 | 1M |
| google/gemini-3.1-flash-lite:free | FREE | FREE | 1M |
| meta-llama/llama-3.3-70b:free | FREE | FREE | 128K |
| deepseek/deepseek-chat | $0.27 | $1.10 | 64K |
| mistralai/mistral-small | $0.10 | $0.30 | 128K |
태스크별로 추천 모델이 갈립니다. 코딩이나 에이전트처럼 최고 품질이 필요하다면 claude-opus-4-7, 비용 효율을 봐야 한다면 claude-sonnet-4-6이 적합합니다. 빠른 응답과 실시간 채팅은 gemini-3-flash나 claude-haiku-4-5, 무료 프로토타이핑은 :free variant 모델들로 충분합니다. 긴 문서 처리에는 2M 컨텍스트의 gemini-3.1-pro, 추론·수학에는 claude-opus-4-7:thinking이나 deepseek-r1이 맞습니다.
실전 5 — 비용 구조 정확히 이해하기
OpenRouter 비용은 프로바이더 비용에 플랫폼 수수료가 더해지는 구조입니다. Pay-as-you-go 방식은 크레딧 충전 시 5.5% 수수료가 붙습니다. $100을 충전하면 실제 사용 가능한 금액은 $94.5입니다. BYOK 방식은 월 100만 요청까지 무료이고 이후 표준 비용의 5%가 적용됩니다.
Sonnet 4.6 기준으로 100만 입력 토큰을 처리할 경우, 직접 API를 쓰면 $3.00, OpenRouter Pay-as-go는 $3.165, BYOK는 $3.15입니다. 월 $30 미만이면 수수료를 신경 쓸 필요가 없고, 대규모 트래픽이라면 BYOK가 유리합니다. API 키 관리 비용 절감, 자동 폴백 라우팅, 통합 모니터링 대시보드, 단일 청구서를 감안하면 5.5% 수수료는 합리적인 편입니다.
비용 응답에서 확인하기
매 응답에서 실제 비용을 추출하려면 OpenRouter raw 응답을 직접 파싱해야 합니다. OpenAI SDK의 response.usage로는 토큰 수만 확인되고, 실제 달러 비용은 raw 응답의 usage.cost 필드에 있습니다.
import httpx
raw = httpx.post(
"https://openrouter.ai/api/v1/chat/completions",
headers={"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"},
json={
"model": "anthropic/claude-sonnet-4-6",
"messages": [{"role": "user", "content": "안녕"}]
}
).json()
cost = raw.get("usage", {}).get("cost", 0)
print(f"이번 요청 비용: ${cost:.8f}")
# → $0.00001500 같이 매우 작은 값
실전 6 — 무료 티어로 시작하기
크레딧 없이, 신용카드 없이 바로 시작할 수 있습니다. :free variant 모델들을 쓰면 비용이 전혀 발생하지 않으며, 레이트 리밋만 적용됩니다. 아래는 무료 모델만 사용하는 챗봇 예시입니다.
from openai import OpenAI
import os
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.environ["OPENROUTER_API_KEY"],
)
FREE_MODELS = [
"meta-llama/llama-3.3-70b-instruct:free",
"google/gemini-3.1-flash-lite:free",
"mistralai/mistral-7b-instruct:free",
"microsoft/phi-3-medium-128k-instruct:free",
"openrouter/free",
]
def chat_free(message: str, model: str = FREE_MODELS[0]) -> str:
response = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": message}]
)
return response.choices[0].message.content
print(chat_free("파이썬 리스트 컴프리헨션 설명해줘"))
무료 티어 한도는 신용카드 없는 경우 무료 모델 하루 50 요청, 크레딧 $10 이상 보유 시 하루 1,000 요청입니다. 레이트 리밋은 무료 모델 기준 분당 20 요청(RPM)이며, 유료 모델은 프로바이더 한도를 따릅니다.
마무리
1편에서는 OpenRouter의 핵심 개념부터 실제 API 호출, 모델 ID 체계, 비용 구조, 무료 티어 활용까지 다뤘습니다. 가장 중요한 포인트는 base_url만 바꾸면 기존 OpenAI SDK 코드가 그대로 동작한다는 것입니다. 모델 전환이 문자열 하나로 끝나기 때문에 여러 모델을 비교하거나 폴백 전략을 짜기가 훨씬 편합니다.
2편에서는 프로바이더 장애 대응을 위한 폴백 설정, 여러 프로바이더를 동시에 활용하는 로드밸런싱, 특정 프로바이더 고정 또는 제외, DeepSeek 시간대 할인 자동 활용, 비용 최적화 고급 패턴을 다룹니다.
관련 글
'AI 개발' 카테고리의 다른 글
| LiteLLM 완전 가이드 3편 — Proxy 서버 모드: 팀 공용 LLM 게이트웨이 구축 실전 (0) | 2026.05.19 |
|---|---|
| OpenRouter 완전 가이드 4편 — 모니터링, 레이트 리밋 관리, OAuth PKCE, 팀 운영, ZDR (0) | 2026.05.19 |
| Firebase AI Logic + Gemini 실전 가이드 4편 — App Check, Vertex AI 전환, Remote Config, 모니터링, 비용 최적화 (0) | 2026.05.19 |
| Firebase AI Logic + Gemini 실전 가이드 1편 — 개요, Firebase 세팅, 첫 API 호출까지 (0) | 2026.05.19 |
| EU AI Act 개발자 실전 가이드 — 2026년 8월부터 AI 앱 만들때 주의 (0) | 2026.05.18 |