OpenRouter API 완벽 가이드
GPT·Claude·Gemini 하나의 키로 호출하기

다중 벤더 API 파편화: 통합 게이트웨이 도입 전 다섯 가지 과제

OpenRouter는 본질적으로 통합 LLM API 게이트웨이(Unified LLM Gateway)입니다. API Key 하나만 유지하면 OpenAI 호환 프로토콜로 OpenAI, Anthropic, Google, DeepSeek 등 벤더 모델에 접근할 수 있으며, 벤더별 인증과 SDK 어댑터를 따로 작성할 필요가 없습니다. 마이그레이션을 결정하기 전에는 「다중 벤더 직접 연결」이 프로덕션에서 흔히 발생하는 다섯 가지 숨은 비용을 먼저 파악해야 합니다.

1. 01

   다중 Key 순환 비용: GPT, Claude, Gemini마다 별도 계정과 청구서가 필요하며, Key 유출 시 순환, 할당량 모니터링, 알림이 세 개의 콘솔에 분산되어 운영 면적이 기하급수적으로 커집니다.

2. 02

   SDK 방언 비용: 대부분 OpenAI 형식을 지원하지만 base_url, Header(Anthropic 버전 번호 등), 스트리밍 필드, tool call schema에 차이가 있어 Agent 프레임워크에서 모델을 바꿀 때마다 여러 곳을 수정해야 합니다.

3. 03

   Failover 수동 구현 비용: 주 모델이 429 또는 장애 시 재시도 체인, 지수 백오프, 예비 모델 매핑을 직접 작성해야 하며, 통합 라우팅 계층이 없으면 새 모델을 추가할 때마다 비즈니스 코드를 변경해야 합니다.

4. 04

   가격 대조 비용: 벤더마다 과금 단위, 캐시 할인, batch 규칙이 달라 FinOps에서 「동일 prompt를 다른 모델로 바꾸면 얼마나 비싸지는가」를 한 표로 비교하기 어렵습니다.

5. 05

   무료 할당량 분산 비용: 플랫폼마다 무료 tier 규칙이 다릅니다. OpenRouter는 25+ 무료 모델을 집계하고 할당량을 통합합니다(미충전 일 50회, $10 충전 후 일 1000회, 분당 20회). 다만 플랫폼 수수료와 BYOK 경계를 이해해야 합니다.

위 과제를 파악한 뒤 다음 절의 라우팅 메커니즘과 비교표를 대조하여 OpenRouter가 지연, 컴플라이언스, 호출 규모 가정에 맞는지 판단하시기 바랍니다.

6단계 Runbook: 가입부터 fallback 체인 검증까지

아래 6단계는 30분 이내에 첫 호출을 완료할 수 있습니다. 각 단계 산출물은 팀 README에 기록하여 신규 멤버 onboarding에 활용하시기 바랍니다.

1. 01

   계정 가입: openrouter.ai에 접속하여 GitHub 또는 이메일로 계정을 생성합니다.

2. 02

   API Key 생성: Keys 페이지에서 Key를 생성하고 즉시 복사합니다. 프로덕션 환경에서는 Git에 커밋하지 말고 비밀 관리 서비스에 보관하세요.

3. 03

   환경 변수 설정: export OPENROUTER_API_KEY="sk-or-..."로 설정하고 CI/CD와 로컬 .env에서 동일한 이름을 사용하세요.

4. 04

   첫 curl 검증: /v1/chat/completions에 POST를 보내 200 응답과 choices[0].message 구조를 확인합니다.

5. 05

   OpenAI SDK 설정: Python/Node에서 base_url을 OpenRouter로 지정하고, 선택적으로 HTTP-Referer와 X-Title을 추가하여 순위 통계에 참여할 수 있습니다.

6. 06

   fallback 체인 테스트: models 배열을 사용하거나 의도적으로 사용 불가 모델을 지정하여 auto failover가 예비 모델로 전환되는지 검증하고 로그를 기록하세요.

curl 첫 요청

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello from OpenRouter"}]
  }'

Python requests

import os, requests

resp = requests.post(
    "https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "anthropic/claude-sonnet-4",
        "messages": [{"role": "user", "content": "Explain Model Routing vs Provider Routing"}],
    },
)
print(resp.json()["choices"][0]["message"]["content"])

Python OpenAI SDK (HTTP-Referer / X-Title 포함)

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
    default_headers={
        "HTTP-Referer": "https://your-app.example.com",
        "X-Title": "My Agent App",
    },
)

completion = client.chat.completions.create(
    model="google/gemini-2.5-pro-preview",
    messages=[{"role": "user", "content": "Summarize OpenRouter pricing"}],
)
print(completion.choices[0].message.content)

Node.js OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
  defaultHeaders: {
    "HTTP-Referer": "https://your-app.example.com",
    "X-Title": "My Agent App",
  },
});

const res = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(res.choices[0].message.content);

JavaScript 스트리밍 출력

const stream = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4",
  messages: [{ role: "user", content: "Stream this response" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

Fallback 모델 체인 (JSON)

{
  "model": "openai/gpt-4o",
  "models": [
    "openai/gpt-4o",
    "anthropic/claude-sonnet-4",
    "google/gemini-2.5-flash-preview"
  ],
  "messages": [{"role": "user", "content": "If primary fails, try fallbacks"}]
}

curl 모델 목록 조회

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

인용 가능한 핵심 데이터, 개발자 SEO, 프로덕션 배포 정리

아래 수치는 기술 방안 또는 README에 직접 인용할 수 있으며, 출처는 OpenRouter 공식 문서 및 플랫폼 공개 데이터(2026년 7월)입니다.

• 제공자 규모: 70+ inference 제공자가 동일 게이트웨이에 집계됩니다.
• 모델 수: 400+ 모델, 명명 규칙 vendor/model입니다.
• 무료 모델: 25+ 모델, 미충전 일 50회, $10 충전 후 일 1000회, 분당 20회입니다.
• 플랫폼 수수료: 충전 5.5%(최소 $0.80), BYOK 월 100만 req 무료, 초과 5%입니다.
• 지연 overhead: 직접 연결 대비 보통 10–80ms 추가(리전 및 provider에 따라 다름)입니다.

개발자 대상 다국어 SEO / 영문 트래픽 진단

Agent 제품 또는 기술 블로그가 중영 개발자를 동시에 대상으로 한다면 OpenRouter류 API 문서 SEO는 단순 기계 번역이 아닌 아래 엔지니어링 관행을 적용해야 합니다.

• hreflang 매트릭스: 중영 페이지는 canonical과 hreflang을 상호 참조해야 합니다. 동일 URL에 두 언어를 혼합하면 Google이 duplicate로 판단할 수 있습니다.
• CDN / WAF와 Googlebot: 일부 CDN 기본 규칙이 해외 크롤러를 오차단할 수 있습니다. Search Console 「URL 검사」로 영문 페이지가 Googlebot에 크롤 가능한지 확인하세요. 사람에게만 200이면 부족합니다.
• 기계 번역 영문 금지: 영문 페이지는 모국어 기술 글로 재작성해야 합니다(용어, 코드 스타일, 검색어). 중문 본문 일괄 번역은 EEAT와 이탈률 모두에 악영향을 줍니다.
• 키워드 매트릭스: 중문은 「OpenRouter 튜토리얼 / 연동 / 무료 모델」, 영문은 「OpenRouter API guide」, 「unified LLM gateway」, 「OpenAI compatible multi-model」에 치중합니다. 코드 예제의 model ID는 전 세계 동일하게 유지합니다.

OpenRouter는 「다중 모델 API 통합 연동」 문제를 해결하지만, 로컬 개발기가 슬립, 시스템 업데이트, 프로세스 종료로 7×24 Agent, cron, webhook 콜백을 중단시키면 API Key가 아무리 안정적이어도 호스트 불안정으로 failover 체인이 공회전합니다. 노트북 뚜껑을 닫으면 OpenClaw, LangGraph 또는 자체 daemon의 SLA를 보장할 수 없으며, 순수 Linux VPS에는 Apple Silicon과 macOS 툴체인이 없습니다. 장기 상주 AI Agent 및 자동화 파이프라인이 필요하다면 VpsMesh Mac Mini 클라우드 렌탈이 일반적으로 더 나은 선택입니다. 전용 노드, 탄력적 임대 기간, 감사 가능한 환경으로 OpenRouter 라우팅 전략을 뚜껑을 닫지 않아도 7×24 온라인인 호스트에서 실행할 수 있습니다. 요금은 Mac Mini M4 대여 가격, 배포 문의는 고객 센터를 참고하세요.