OpenRouter API 완벽 가이드: GPT·Claude·Gemini 통합 연동 (2026)

OpenRouter는 통합 LLM API 게이트웨이입니다. 개발자는 OpenAI Chat Completions와 동일한 JSON 스키마로 요청하고, model 필드에 공급사/모델 형식(예: openai/gpt-5.6-sol, anthropic/claude-sonnet-4, google/gemini-2.5-pro)을 넣으면 라우팅 계층이 실제 추론 호스트를 선택합니다. 월간 트래픽은 약 100조 토큰 규모이며, 2026년 6월 실트래픽 기준 DeepSeek·Claude·Gemini가 상위권을 차지합니다.

핵심 엔드포인트는 POST https://openrouter.ai/api/v1/chat/completions이며, 모델 목록은 GET https://openrouter.ai/api/v1/models로 조회합니다. 인증은 Authorization: Bearer <OPENROUTER_API_KEY> 한 줄이면 되고, 선택 헤더 HTTP-Referer·X-Title은 앱 순위 집계에 사용됩니다. OpenAI Python SDK에서는 base_url="https://openrouter.ai/api/v1"만 지정하면 기존 코드를 유지할 수 있습니다.

• 인용 가능 데이터 1: 70+ 공급사, 400+ 모델 ID(2026년 7월 공개 카탈로그 기준).
• 인용 가능 데이터 2: 토큰 단가는 공급사 표준가와 동일하며 OpenRouter는 크레딧 충전액의 5.5%만 수수료로 징수합니다.
• 인용 가능 데이터 3: BYOK(Bring Your Own Key) 모드는 월 100만 요청까지 무료이며, 이후에도 공급사 직청구와 동일한 토큰 단가가 적용됩니다.

• SDK·인증 분기: OpenAI·Anthropic·Google 각각 다른 헤더·스트리밍·툴 호출 스키마를 유지하면 Agent 프레임워크마다 어댑터 레이어가 늘어납니다.
• fallback 공백: 한 공급사 장애 시 수동으로 모델 문자열을 바꾸면 CI·Telegram Bot·Cursor Skill이 동시에 멈춥니다. OpenRouter models 배열 fallback은 한 HTTP 요청 안에서 순차 시도합니다.
• 청구 분산: 팀별로 GPT·Claude·DeepSeek 청구서를 합치려면 재무팀이 월말에 CSV를 수작업 병합합니다. OpenRouter 대시보드는 모델·앱·프로젝트 단위로 Token과 USD를 한 화면에 둡니다.
• 로컬 Mac Agent 불안정: OpenRouter만 붙여도 되지만, Hermes·Claude Code 같은 CLI는 macOS Seatbelt·장연결·키체인에 의존합니다. 저가 Linux VPS에서 게이트웨이를 돌리면 대역폭 지터와 NAT 타임아웃이 Agent 세션을 더 자주 끊습니다.

프로덕션에서는 Model Routing + models fallback을 기본으로 두고, 금융·의료처럼 데이터가 특정 공급사만 통과해야 할 때만 Provider Routing을 켭니다. route: "fallback"과 provider: { allow_fallbacks: true } 조합은 공식 문서의 권장 패턴입니다.

쓰지 말아야 할 경우: ① 지연 예산 10ms 미만 실시간 음성·게임 NPC, ② 월 수십억 토큰 이상으로 공급사 Enterprise 직계약이 더 싼 경우, ③ 데이터가 EU·중국 등 특정 관할 외로 나가면 안 되는 규정 준수 워크로드(경로 감사 필요), ④ OpenAI Realtime API·Anthropic Computer Use·Google Vertex 전용 기능이 필수일 때. 이때는 벤더 SDK 직연결과 OpenRouter를 실험 전용으로 분리하는 편이 낫습니다.

openrouter.ai/keys에서 키를 발급하고, 프로덕션에서는 프로젝트별 키·지출 상한·IP allowlist를 분리합니다. 필수 헤더는 Authorization뿐이며, 앱 추적을 원하면 HTTP-Referer: https://your-app.example와 X-Title: Your App을 추가합니다.

요금 검토는 NUKCLOUD 가격 페이지와 별개로 OpenRouter 대시보드의 Usage 탭을 기준으로 삼습니다. Agent 호스트 비용(Mac·VPS·클라우드 Mac)은 API Token과 분리해 TCO 시트에 두 줄로 적어야 합니다.

아래 예제는 모두 동일한 Chat Completions 스키마를 사용합니다. 키는 환경 변수 OPENROUTER_API_KEY에 두세요.

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "HTTP-Referer: https://nukcloud.com" \
  -H "X-Title: NUKCLOUD Agent" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "messages": [{"role": "user", "content": "Swift 6 Sendable 체크리스트 3줄"}]
  }'

import os, requests
r = requests.post(
    "https://openrouter.ai/api/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"},
    json={
        "model": "google/gemini-2.5-pro",
        "messages": [{"role": "user", "content": "Gemini로 요약해줘"}],
    },
    timeout=60,
)
print(r.json()["choices"][0]["message"]["content"])

from openai import OpenAI
client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)
resp = client.chat.completions.create(
    model="openai/gpt-5.6-sol",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";
const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});
const completion = await client.chat.completions.create({
  model: "deepseek/deepseek-v4-flash",
  messages: [{ role: "user", content: "한국어로 답변" }],
});
console.log(completion.choices[0].message.content);

const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "anthropic/claude-sonnet-4",
    stream: true,
    messages: [{ role: "user", content: "스트리밍 테스트" }],
  }),
});
const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}

{
  "models": [
    "anthropic/claude-sonnet-4",
    "openai/gpt-5.6-sol",
    "google/gemini-2.5-flash"
  ],
  "route": "fallback",
  "messages": [{"role": "user", "content": "primary 장애 시 자동 전환"}]
}

curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" | jq '.data[:3]'

Provider Routing은 요청 본문에 "provider": { "order": ["Anthropic", "Amazon Bedrock"] }를 넣어 우선 공급사를 고정합니다. BYOK는 대시보드 Settings → Keys에서 OpenAI·Anthropic 키를 등록한 뒤, 동일 엔드포인트로 라우팅하면 OpenRouter는 월 100만 req까지 무료이고 Token은 공급사에 직접 청구됩니다.

무료 모델(예: meta-llama/llama-3.3-70b-instruct:free)은 프로토타입·CI 스모크 테스트에 적합하지만 rate limit과 품질 편차가 큽니다. 프로덕션 Agent는 유료 모델 + fallback + 지출 알림을 기본으로 두세요.

한국어·영어 페이지 모두 검색 유입이 낮을 때 아래를 순서대로 확인합니다.

• Search Console: 색인·클릭·CTR; openrouter api·openrouter 연동 쿼리 노출 대비 순위.
• CDN/WAF: 봇·해외 IP 차단이 Googlebot·Bingbot을 막지 않는지.
• hreflang: 목록页만 hreflang 행렬 유지; 상세页은 canonical 단일(generate-blog.md 규칙).
• 기계번역 흔적: ko/en 문장 구조가 동일하면 EEAT 신호 약화; 합니다体·현지 검색어로 재작성.
• 백링크: Dev.to·Qiita·국내 개발 커뮤니티·GitHub README에 실코드 링크.

다국어 사이트는 번역이 아니라 로컬 재작성이 필수입니다. 동일 slug·id·date만 맞추고 본문·intro·tags는 각 언어 팀이 독립 작성합니다.

• URL: https://nukcloud.com/{lang}/blog/{slug}.html; 상세页 hreflang 없음, canonical 자기 참조.
• Sitemap: node .cursor/scripts/generate-sitemap.js 실행 후 새 slug 포함 여부 확인.
• Schema: BlogPosting + mainEntity.FAQPage를 head JSON-LD에 병합(본 페이지 적용).
• og:*: og:type=article, og:url=canonical, title에 | NUKCLOUD.

추적 지표: GSC 클릭·평균 순위, Matomo 페이지 체류, OpenRouter 대시보드 Token/USD, Agent 호스트 uptime. 주간 리뷰에서 P0 미완 항목을 먼저 닫습니다.

1. 01
   계정·결제: openrouter.ai 가입, 프로덕션용 $10+ 크레딧 충전(무료 모델 1000/일 한도).
2. 02
   키 분리: dev/staging/prod 프로젝트별 API 키, 지출 상한·알림 설정.
3. 03
   환경 변수: Mac·CI·클라우드 Mac에 OPENROUTER_API_KEY 주입, 키체인·Secret Manager 사용.
4. 04
   스모크 테스트: curl + models 목록 + 유료·무료 모델 각 1회 호출로 200 확인.
5. 05
   fallback 정의: primary·secondary·tertiary 모델 ID를 Git에 버전 관리, route: "fallback" 적용.
6. 06
   호스트 고정: Agent·MCP·Runner를 NUKCLOUD 주문으로 프로비저닝한 전용 Mac에 배치, SSH·로그·지출 대시보드 연동.