OpenRouter API 완전 가이드:
GPT·Claude·Gemini 단일 키 연동 (2026)

GPT, Claude, Gemini, Grok, 오픈 웨이트 모델을 프로덕션 Agent에서 병행하는 개발팀은 벤더별 API 키, SDK 차이, 청구 주기 분산으로 인한 통합 비용을 겪습니다. OpenRouter는 이를 OpenAI 호환 엔드포인트 하나로 묶어 70개 이상 프로바이더, 400개 이상 모델에 단일 키로 접근하게 합니다. 본문은 OpenRouter 정의, 모델/프로바이더 라우팅, 5가지 도입 이점, 직접 API 대비, curl/Python/OpenAI SDK/Node/스트리밍/fallback 코드, 요금, SEO 전략, FAQ, MACNOX 연결을 비교표와 실행 절차 중심으로 정리합니다.

• 핵심:base_url을 https://openrouter.ai/api/v1로 변경하고 기존 OpenAI SDK 코드를 유지한 채 model 슬러그만 교체합니다. token 마진 없음, 크레딧 구매 5.5% 수수료(최소 $0.80)입니다.
• 무료 tier:25개 이상 무료 모델, 미구매 50회/일, $10 충전 후 1,000회/일, 상한 20 req/min.
• 적합 사례:프로토타입, 멀티모델 Agent, fallback 자동화. 엔터프라이즈 SLA, 커스텀 fine-tune, 단일 벤더 데이터 레지던시가 필요하면 직접 API를 검토하세요.

SECTION 01 멀티벤더 LLM API 도입 시 개발자가 겪는 4가지 제약

2026년 상반기 대부분의 프로덕션 AI 스택이 여러 모델을 병행합니다. OpenRouter 이전에 발생하는 대표적 비용은 다음과 같습니다.

• 키 관리 분산:OpenAI, Anthropic, Google, xAI, Moonshot 등 각사가 별도 콘솔, rate limit, 인증 헤더를 요구해 CI/CD 키 배포가 보안 감사 대상이 됩니다;
• SDK 파편화:Anthropic Messages API와 OpenAI Chat Completions 형식이 달라 신모델 추가마다 Agent 프레임워크에 어댑터가 늘어납니다;
• 장애 시 공백:단일 프로바이더 다운 시 대체 model ID·단가·지연 프로필을 미리 알지 못하면 Agent 파이프라인이 멈춥니다;
• 청구 불투명:Kimi K3와 Claude, GPT token 단가 비교만으로는 부족하고 통합 공수가 실비용의 대부분을 차지하는 경우가 늘고 있습니다.

한 줄 정의: OpenRouter는 통합 LLM API 게이트웨이입니다. 단일 키, 단일 엔드포인트(https://openrouter.ai/api/v1), 70+ 프로바이더 / 400+ 모델(GPT-5.x, Claude 4.x, Gemini 2.x, Grok, DeepSeek, Kimi 등)에 OpenAI 호환으로 접근하며 fallback과 BYOK를 옵션으로 제공합니다.

SECTION 02 OpenRouter란? 라우팅 메커니즘과 요금 모델

OpenRouter는 애플리케이션과 상류 LLM 프로바이더 사이에 위치합니다. 표준 Chat Completions 요청을 보내면 프로바이더 선택, 부하 분산, 청구 집계를 대행합니다.

무료 모델과 rate limit

OpenRouter는 25개 이상 무료 모델(커뮤니티/벤더 제공 tier)을 운영합니다. 2026년 7월 기준 제한은 다음과 같습니다.

• 크레딧 미구매:무료 모델 50회/일(잔액 미차감);
• $10 이상 충전 후:무료 모델 1,000회/일;
• rate 상한:무료 모델 공통 20회/분.

요금 — token 마진 없음

SECTION 03 OpenRouter vs 직접 API: 비교표, 5가지 이점, 쓰지 말아야 할 경우

개발자가 OpenRouter를 선택하는 5가지 이유

1. 단일 통합으로 전 모델:model 슬러그 교체만으로 충분합니다. Grok 4.5와 Claude, GPT 벤치마크 비교에도 동일 클라이언트를 재사용할 수 있습니다.
2. OpenAI SDK 호환:base_url과 api_key 변경만으로 Python/Node/TS 코드를 유지합니다.
3. 자동 fallback:단일 요청으로 Claude → GPT → Gemini를 순차 시도할 수 있습니다.
4. 투명한 요금:모델 카탈로그에 token 단가가 표시되며 숨은 스프레드가 없습니다.
5. 무료 tier 실험:25+ 무료 모델로 계약 전 Agent 프로토타입을 검증합니다.

OpenRouter를 쓰지 말아야 할 경우

• 엔터프라이즈 SLA / BAA:의료·금융에서 특정 벤더 BAA가 필요하면 제3자 게이트웨이 경유는 법무 검토가 필요합니다;
• 커스텀 fine-tune:비공개 GPT-4 fine-tune이나 Vertex AI 커스텀 모델은 공개 카탈로그에 없습니다;
• 엄격한 데이터 레지던시:추론이 특정 리전 전용 용량으로 제한되는 계약에서는 대체가 되지 않습니다;
• 초저지연:실시간 음성·거래 파이프라인에서는 게이트웨이 ms가 영향을 줍니다;
• 대량 협상 할인:월 6자리 USD 규모에서는 직접 계약 15~30% 할인이 유리할 수 있습니다.

SECTION 04 OpenRouter API 코드 예제: curl, Python, OpenAI SDK, Node, 스트리밍, fallback

아래 예제는 OpenRouter base URL과 대시보드 API 키를 전제로 합니다. 상류 업데이트 후 공식 문서에서 헤더와 파라미터를 다시 확인하세요.

curl — 기본 Chat Completion

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "HTTP-Referer: https://your-app.com" \
  -H "X-Title: Your App Name" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "모델 라우팅을 한 문단으로 설명해 주세요"}]
  }'

Python — requests

import os, requests

resp = requests.post(
    "https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
        "HTTP-Referer": "https://your-app.com",
        "X-Title": "Your App Name",
    },
    json={
        "model": "anthropic/claude-sonnet-4",
        "messages": [{"role": "user", "content": "이 API 설계를 요약해 주세요..."}],
    },
)
print(resp.json()["choices"][0]["message"]["content"])

OpenAI SDK — 교체

from openai import OpenAI

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

response = client.chat.completions.create(
    model="google/gemini-2.5-pro",
    messages=[{"role": "user", "content": "GPT와 Claude의 코드 리뷰 적합성을 비교해 주세요."}],
)
print(response.choices[0].message.content)

Node.js — fetch

const resp = await fetch("https://openrouter.ai/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.OPENROUTER_API_KEY}`,
    "Content-Type": "application/json",
    "HTTP-Referer": "https://your-app.com",
    "X-Title": "Your App Name",
  },
  body: JSON.stringify({
    model: "x-ai/grok-4",
    messages: [{ role: "user", content: "TypeScript retry 헬퍼를 작성해 주세요." }],
  }),
});
const data = await resp.json();
console.log(data.choices[0].message.content);

스트리밍

from openai import OpenAI

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

stream = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "스트리밍으로 응답해 주세요."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

fallback — models 배열

{
  "models": [
    "anthropic/claude-sonnet-4",
    "openai/gpt-4o",
    "google/gemini-2.5-flash"
  ],
  "messages": [
    {"role": "user", "content": "Claude가 다운되면 GPT, 그다음 Gemini를 시도해 주세요."}
  ]
}

이 JSON을 /chat/completions에 POST합니다. model을 생략(또는 첫 슬러그 지정)하면 OpenRouter가 순차 시도합니다.

SECTION 05 OpenRouter 도입 6단계: 가입부터 프로덕션 fallback까지

1. 계정 생성 및 API 키 발급:openrouter.ai에서 가입 후 Settings → Keys에서 키를 만듭니다. 시크릿 매니저에 저장하고 git에 커밋하지 마세요.
2. 크레딧 추가(무료 모델만이면 선택):1,000회/일 무료 tier가 필요하면 $10 이상 충전합니다. 유료 모델은 리스트 가격으로 잔액에서 차감됩니다.
3. 클라이언트를 OpenRouter 엔드포인트로 지정:OpenAI SDK에서는 base_url=https://openrouter.ai/api/v1, curl/requests/fetch에서는 동일 URL을 사용합니다.
4. 카탈로그에서 model 슬러그 선택:models API 또는 대시보드에서 openai/gpt-4o, anthropic/claude-sonnet-4, google/gemini-2.5-pro, moonshotai/kimi-k3 등을 확인합니다.
5. 프로덕션 Agent에 fallback 설정:models 배열에 2~3개 대안을 추가하고 실제 응답 모델을 로그에 기록해 비용과 지연을 조정합니다.
6. 귀속 헤더와 사용량 모니터링:HTTP-Referer와 X-Title을 포함합니다(일부 무료 모델 필수). 대시보드에서 예산 알림을 설정한 뒤 CI/CD나 고객용 Agent에 연결합니다.

SECTION 06 인용 가능 데이터, 한국어 SEO 전략, 프로덕션 연결

• 카탈로그 규모:70+ 프로바이더, 400+ 모델, 엔드포인트 https://openrouter.ai/api/v1.
• 무료 tier:25+ 무료 모델, 미구매 50 req/일, $10 충전 후 1,000 req/일, 20 req/min 상한.
• 수익 모델:token 마진 없음, 크레딧 5.5%(최소 $0.80), 암호화폐 5%, BYOK 월 100만 req 무료.
• 라우팅:모델 라우팅은 슬러그 최적화, 프로바이더 라우팅은 벤더 고정, models 배열로 fallback.
• SDK:OpenAI SDK base_url / api_key 변경만으로 동작.
• 귀속 헤더:HTTP-Referer와 X-Title은 무료 모델 leaderboard 표시에 필요합니다.

배포 후 아래 공식 출처에서 요금·제한·API 동작을 다시 확인하세요.

OpenRouter 공식 문서

OpenRouter FAQ — 요금, 무료 모델, BYOK

OpenRouter models API — 라이브 카탈로그와 token 단가

한국어 SEO: 키워드 매트릭스와 제목 신호

영어 페이지 유입이 없을 때 — 진단 체크리스트

• CDN / WAF:US·EU 엣지에서 HTTP 200 반환 여부;
• hreflang 오설정:EN을 기계번역 stub에 연결하면 양쪽 모두 평가 하락;
• robots / noindex:/en/blog/가 실수로 차단되지 않았는지;
• sitemap:영어 URL이 lastmod와 함께 등록되었는지;
• CSR 빈 껍데기:MACNOX 블로그는 정적 HTML — 본문을 JS만으로 렌더링하지 마세요;
• 기계번역 감지:영어는 단락 구조와 예시를 독립적으로 재작성;
• 키워드 불일치:영어 검색은 "OpenRouter API tutorial"형 — 직역 제목을 피하세요.

canonical / sitemap / 배포 채널

• canonical:각 언어판은 자체 URL만(예 https://macnox.com/ko/blog/2026-openrouter-api-guide-gpt-claude-gemini.html);
• 한국어 배포:Velog, Brunch, 티스토리, X 스레드;
• 영어 배포:dev.to, Hacker News, Reddit r/LocalLLaMA;
• Schema:BlogPosting + FAQPage를 head에 통합(본 페이지 참조).

OpenRouter는 모델 접근을 통합하지만 멀티모델 API Agent, macOS CI/CD, 7×24 자동 테스트를 구축하는 팀에게는 세 가지 프로덕션 공백이 남습니다. ① 게이트웨이 장애는 로컬 Mac 슬립·재부팅을 해결하지 않습니다; ② VM macOS CI에서는 Metal / Core ML 호환성과 성능 오버헤드가 발생합니다; ③ 책상 위 MacBook은 24/7 Agent 호스트가 아닙니다. 가상화 성능 손실, 장기 안정성 부족, Root 제한——이들이 겹치는 환경에서 제로 오버헤드 네이티브 Apple 연산, 안정적 iOS CI/CD, AI Agent 7×24 자동화가 필요한 프로덕션에는 MACNOX 클라우드 물리 Mac 노드가 보통 더 나은 선택입니다. 100% Apple 정품 물리 머신, 전체 Root, Hypervisor 오버헤드 없음, 일/주/월 계약. Kimi K3 멀티벤더 API 연동, Grok 4.5 Agent 비용 분석, Mac Mini M4 렌탈 vs 구매 TCO도 참고하세요.

SECTION 07 자주 묻는 질문 FAQ