OpenRouter API 완전 가이드: 하나의 Key로 GPT·Claude·Gemini 전 모델을 통합 호출하는 실전 절차

OpenRouter란 무엇인가 — 통합 LLM API 게이트웨이 구조

OpenRouter는 여러 LLM 벤더를 하나의 OpenAI 호환 인터페이스로 묶는 통합 API 게이트웨이입니다. https://openrouter.ai/api/v1/chat/completions 단일 엔드포인트와 하나의 API Key로 GPT, Claude, Gemini, Llama, DeepSeek, Qwen, Mistral 등 70개 이상 공급사의 400개 이상 모델에 접근할 수 있습니다. 벤더별 개별 가입, SDK 분기, 분산된 청구 대시보드 관리가 필요 없습니다.

• 인증: Authorization: Bearer $OPENROUTER_API_KEY
• 프로토콜: OpenAI Chat Completions 형식 — 기존 OpenAI SDK 코드는 base_url과 api_key만 바꾸면 동작합니다
• 모델 지정: 벤더/모델명 형식 (예: openai/gpt-4o, anthropic/claude-3.5-sonnet, google/gemini-2.5-pro)

OpenRouter 내부에서는 다음 두 계층이 독립적으로 라우팅을 결정합니다.

주력 공급사가 레이트 리밋이나 오류를 반환하면 OpenRouter는 다음 가용 공급사 또는 models 배열에 지정한 대체 모델로 자동 전환합니다. 비즈니스 코드에서 circuit breaker를 직접 구현하지 않아도 게이트웨이 계층에서 페일오버가 완료됩니다.

다중 벤더 관리의 핵심 마찰 — OpenRouter가 풀어주는 문제

다중 모델 개발을 진행할수록 다음과 같은 숨은 비용이 누적됩니다.

• 계정 분산: 벤더마다 KYC, 청구 정보, API Key 로테이션을 개별 관리해야 합니다
• SDK/프로토콜 차이: 모델을 바꿀 때마다 클라이언트 구현을 다시 작성하는 공수가 발생합니다
• 가용성 자체 설계: 직접 API는 레이트 리밋·장애 시 재시도와 폴백을 앱 측에서 구현해야 합니다
• 청구 대조: 여러 대시보드를 넘나들며 비용을 파악하는 것은 A/B 테스트나 프로토타입 단계에서도 부담입니다

OpenRouter vs 직접 API — 선택 기준 비교표

OpenRouter는 공식 SDK를 대체하는 것이 아니라, 「다중 모델 활용」과 「단일 벤더 직접 연결」 사이의 절충안입니다. 주요 차이를 표로 정리합니다.

OpenRouter 5가지 핵심 장점과 쓰지 말아야 할 경우

장점 1: 하나의 Key로 전 모델 접근, 마이그레이션 비용 거의 제로. 모델 전환은 model 문자열 변경만으로 충분하며, 벤더별 어댑터 계층을 작성할 필요가 없습니다.

장점 2: 공급사 간 자동 페일오버. models 배열과 route: "fallback"으로 명시적 폴백 체인을 설정하면 주력이 다운되어도 다음 후보로 자동 이동합니다.

장점 3: 통합 청구와 사용량 분석. 하나의 Dashboard에서 전 모델의 소비, 비용, TTFT, 처리량을 확인할 수 있습니다.

장점 4: token markup 없는 요금 설계. 공식 FAQ에 따르면 token 단가에 가산하지 않으며, Credits 충전 시에만 5.5% 수수료가 부과됩니다. BYOK(Bring Your Own Key) 모드에서는 월 100만 요청까지 무료, 초과분은 동등 금액의 5% 서비스료입니다.

장점 5: 프로토타입과 다중 모델 A/B 테스트에 최적. 동일한 Prompt/Agent 프레임워크로 시장 주요 모델을 가로질러 검증할 수 있으며, 월 수천 달러 규모의 중간 워크로드에서도 운영 부담을 줄입니다.

실전 절차 — OpenRouter API 6단계 도입

가입부터 첫 요청까지의 흐름입니다. Python 버전 충돌이나 오래된 SDK 잔여물을 피하려면 깨끗한 macOS 개발 환경에서 작업하는 것을 권장합니다.

1. OpenRouter 계정 등록: openrouter.ai에 접속해 GitHub 또는 이메일로 가입합니다.
2. API Key 발급: Dashboard → Keys에서 키를 생성하고 OPENROUTER_API_KEY 환경 변수에 저장합니다. 저장소에 하드코딩하지 마세요.
3. (선택) Credits 충전: 유료 모델 호출에는 잔액이 필요합니다. 충전 시 5.5%(최소 $0.80) 수수료가 부과됩니다. 미충전 상태에서도 25개 이상 무료 모델을 사용할 수 있으나 레이트 리밋이 있습니다.
4. 가용 모델 확인: GET /api/v1/models로 대상 모델 ID와 현행 단가를 확인합니다.
5. 첫 요청 전송: curl 또는 SDK로 /v1/chat/completions를 호출하고 model을 지정합니다.
6. 스트리밍과 Fallback 검증: 프로덕션 투입 전 stream: true와 models 배열의 장애 대응 체인을 각각 테스트하고, 클라이언트가 올바르게 처리하는지 확인합니다.

curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

코드 예제 — curl / Python / Node.js / OpenAI SDK / 스트리밍 / Fallback

아래는 대표적인 4가지 패턴에 스트리밍과 Fallback 예제를 더한 것입니다. OpenRouter는 HTTP-Referer와 X-Title 헤더 전송을 권장합니다(랭킹 통계용).

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-3.5-sonnet",
    "messages": [
      { "role": "user", "content": "양자 컴퓨팅을 한 문장으로 설명해 주세요" }
    ]
  }'

import requests
import os

response = requests.post(
    url="https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "google/gemini-2.5-pro",
        "messages": [
            {"role": "user", "content": "퀵소트 Python 구현을 작성해 주세요"}
        ],
    },
)
print(response.json()["choices"][0]["message"]["content"])

from openai import OpenAI
import os

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

completion = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_headers={
        "HTTP-Referer": "https://your-app-domain.com",
        "X-Title": "My App",
    },
)
print(completion.choices[0].message.content)

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});

const completion = await openai.chat.completions.create({
  model: "deepseek/deepseek-chat",
  messages: [{ role: "user", content: "Explain OpenRouter in one sentence" }],
});

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

const stream = await openai.chat.completions.create({
  model: "anthropic/claude-3.5-sonnet",
  messages: [{ role: "user", content: "가을에 대한 짧은 시를 써 주세요" }],
  stream: true,
});

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

{
  "model": "anthropic/claude-3.5-sonnet",
  "models": [
    "anthropic/claude-3.5-sonnet",
    "openai/gpt-4o",
    "google/gemini-2.5-pro"
  ],
  "route": "fallback",
  "messages": [{ "role": "user", "content": "Hello" }]
}

주 모델이 레이트 리밋이나 오류를 반환하면 OpenRouter는 목록 순서대로 다음 모델을 자동 시도합니다. 앱 측에서 추가 재시도 로직을 작성할 필요가 없습니다.

무료 한도·BYOK·요금 — 인용할 핵심 기술 정보

• 무료 모델: 25개 이상 무료 모델(Llama, Gemma, DeepSeek 무료 티어 등) 이용 가능. 미충전 계정 약 50회/일; $10 이상 충전 후 1000회/일·20회/분으로 상향.
• BYOK(Bring Your Own Key): 각 벤더 API Key를 가져오면 월 100만 요청까지 OpenRouter 서비스료 무료. 초과분은 동등 금액의 5%.
• 요금 메커니즘: Token은 벤더 원가 그대로 전달, markup 없음. Credits 구매 시에만 5.5%(최소 $0.80). 암호화폐 결제 별도 5%.
• 모델 수: 70개 이상 공급사, 400개 이상 모델. 전체 목록은 GET /api/v1/models로 실시간 조회.

요금 체계, 무료 모델 목록, 레이트 리밋은 변경될 수 있습니다. 이 글의 요약이 아니라 아래 공식 링크를 기준으로 삼으세요.

OpenRouter 공식 문서

OpenRouter 공식 FAQ (요금 및 BYOK)

OpenRouter 공식 — Provider Routing 메커니즘

자주 묻는 질문 FAQ

OpenRouter는 「다중 모델 API 통합」 문제를 해결하지만, 로컬 개발 환경의 마찰까지는 다루지 않습니다. Python 가상 환경 충돌, Node.js 버전 불일치, Agent 프레임워크 시행착오로 메인 머신이 지저분해지는 일 — 다중 모델 실험 단계에서 특히 흔합니다. 언제든 초기화하고 하루 단위로 다시 빌릴 수 있는 실제 Apple Silicon Mac mini라면 OpenRouter 연결 스크립트, Next.js 프로토타입, 상시 실행 Agent 프로세스를 부담 없이 돌릴 수 있습니다. Kimi K3 모델 테스트 가이드와 Xcode CI 러너 구축 가이드에서 소개한 「깨끗한 머신」 접근법은 OpenRouter 다중 모델 연동에도 그대로 적용됩니다.