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

OpenAI, Anthropic, Google API 키를 각각 관리하면서 Agent나 배치 파이프라인을 구축하면, 모델을 바꿀 때마다 클라이언트 통합 비용이 중복됩니다. 본문은 OpenRouter API 하나로 GPT-4o, Claude 3.5 Sonnet, Gemini 2.5 Pro, DeepSeek, Llama 등 400개 이상 모델을 호출하려는 개발자를 위해 핵심 정의, 직접 API 비교표, 5가지 도입 이유, 부적합 케이스, 7단계 키 발급, cURL·Python·Node.js·OpenAI SDK 코드, 스트리밍과 폴백, 구체적 요금 수치, 한국어 SEO 체크리스트, FAQ, 추적 지표를 정리합니다. 요금은 NOVAKVM 대여 가격 페이지, 주문은 주문 페이지를 참고하시기 바랍니다. 모델 시장 맥락은 OpenRouter 주간 토큰 랭킹 해설과 함께 읽으면 이해가 깊어집니다.

[ SECTION_01 ] // TLDR OpenRouter란 무엇인가: 개발자용 30초 정의

OpenRouter는 LLM용 통합 API 게이트웨이입니다. API 키 1개, OpenAI 호환 엔드포인트(https://openrouter.ai/api/v1/chat/completions), 70개 이상 공급자를 아우르는 단일 청구 대시보드로 프론티어 모델에 접근합니다. model 문자열을 openai/gpt-4o에서 anthropic/claude-3.5-sonnet이나 google/gemini-2.5-pro로 바꾸면 요청 본문, 스트리밍, SDK 래퍼를 그대로 유지할 수 있습니다.

• 인증: Authorization: Bearer $OPENROUTER_API_KEY
• 모델 ID 형식: provider/model-name(예: deepseek/deepseek-chat, meta-llama/llama-3.1-405b)
• 마이그레이션: OpenAI SDK의 base_url="https://openrouter.ai/api/v1"로 지정하고 키만 교체
• 이중 라우팅: 각 요청에서 OpenRouter는 독립적으로 두 가지를 결정합니다. 모델(model 또는 openrouter/auto)과 동일 모델을 제공하는 공급자 호스트(provider 객체, 기본값은 비용 가중 안정 경로)

OpenRouter는 각사 공식 SDK의 모든 기능을 대체하지 않습니다. 통합 표면을 하나로 맞추고, 투명한 패스스루 요금과 게이트웨이 수준 페일오버를 자체 서킷 브레이커 없이 얻고 싶은 프로덕션 멀티 모델 구성을 위한 최단 경로입니다.

[ SECTION_02 ] // COMPARE OpenRouter vs 직접 API(OpenAI·Anthropic·Google) 비교표

OpenRouter vs OpenAI API를 검색하는 개발자는 청구와 SDK를 하나로 묶고 싶지만, 지연 시간, 마크업, 벤더 락인을 우려합니다. 아래는 실무 의사결정 매트릭스입니다.

공급자 라우팅은 OpenRouter 이야기의 절반입니다. 동일 모델 ID를 제공하는 호스트가 여럿이어도 OpenRouter는 가격·가동률·처리량으로 점수를 매기고, 속도 제한이나 오류 시 자동 페일오버합니다. 이는 모델 라우팅(어떤 모델이 응답하는지)과 별개 레이어입니다.

[ SECTION_03 ] // WHY_SWITCH OpenRouter로 전환하는 5가지 이유

• 키 하나로 모든 프론티어 모델: 5개사 가입을 생략할 수 있습니다. Agent 프레임워크에서 런타임에 GPT·Claude·Gemini를 고르게 할 때 문자열 하나만 바꾸면 됩니다.
• 게이트웨이 수준 페일오버: 속도 제한과 지역 장애는 일상입니다. OpenRouter는 공급자 간 재시도와 명시적 models 폴백 배열을 지원해 자체 서킷 브레이커 없이 가용성을 높입니다.
• 통합 대시보드: 전 모델의 토큰 지출·TTFT·처리량을 한 화면에서 보는 것은 OpenAI·Anthropic·Google Cloud 콘솔을 오가며 청구를 대조하는 것보다 실무적입니다.
• 토큰 마크업 없음: 많은 집약 서비스와 달리 OpenRouter FAQ는 패스스루 요금을 명시합니다. 공급자 단가를 그대로 지불하고, 수수료는 크레딧 충전 시(5.5%, 최소 $0.80)에만 발생합니다.
• 무료 티어로 실험: 25개 이상 무료 모델로 스모크 테스트가 가능합니다. 미인증은 하루 약 50회, $10 이상 크레딧 충전 후 하루 1,000회·분당 20회까지 확장됩니다.

[ SECTION_04 ] // ANTI_PATTERNS OpenRouter를 쓰지 않는 편이 나은 경우

일방적 추천보다, 아래 조건에 해당하면 직접 API나 셀프호스팅이 합리적입니다.

• 단일 벤더 초대규모 지출: 월 한 모델에 수만 달러를 쓰면 5.5% 크레딧 수수료와 게이트웨이 지연이 직접 엔터프라이즈 계약보다 비쌀 수 있습니다.
• 공급자 독점 API: OpenAI Batch API, Anthropic 공식 Prompt Caching 청구 최적화, Google Vertex 전용 도구, OpenRouter가 완전 미러하지 않는 Assistants 엔드포인트가 필요한 경우.
• 초저지연: 음성·게임·100ms 미만 대화 루프에서는 10~80ms 추가 홉이 허용되지 않을 수 있습니다.
• 엄격한 데이터 거주지: 미국 제3자 게이트웨이 경유가 규제상 불가한 워크로드는 직접 API 또는 오픈 웨이트 셀프호스팅이 적합합니다.
• 심층 컴플라이언스 감사: 조달이 OpenAI나 Anthropic과의 직접 DPA를 요구하면 중간 집약층이 검토 마찰을 키웁니다.

[ SECTION_05 ] // SETUP OpenRouter API 키 발급: 7단계 절차

1. 계정 생성: openrouter.ai에서 이메일 또는 OAuth로 가입합니다. 무료 모델 시험용 키 생성에 신용카드는 필요 없습니다.
2. Keys 페이지 열기: Settings → API Keys(또는 openrouter.ai/keys)로 이동합니다. 키는 계정 단위이며 독립 로테이션이 가능합니다.
3. 프로덕션 키 발급: Create Key를 누르고 환경명(prod-agent, staging-ci 등)으로 라벨을 붙입니다. 시크릿은 한 번만 표시되므로 시크릿 매니저에 저장하고 Git에는 두지 않습니다.
4. 환경 변수 설정: 셸 프로필 또는 앱 .env에 OPENROUTER_API_KEY를 export합니다.
5. 유료 모델용 크레딧 충전: Credits에서 충전합니다. 5.5% 수수료(최소 $0.80), 암호화폐는 추가 5%. $10 이상 잔액에서 무료 모델 일일 상한이 올라갑니다.
6. curl로 스모크 테스트: anthropic/claude-3.5-sonnet 또는 무료 모델에 chat completion 1회를 보내 프로덕션 Agent 배선 전에 연결을 확인합니다.
7. 선택적으로 BYOK 활성화: 공급자 설정에 자사 OpenAI나 Anthropic 키를 등록합니다. 월 100만 요청까지 OpenRouter 서비스 요금 무료, 초과는 5%가 상당 사용량에 청구됩니다.

OpenRouter 문서와 요금 페이지는 업데이트됩니다. 프로덕션 예산 확정 전에 공식 소스를 다시 확인하시기 바랍니다.

https://openrouter.ai/docs

https://openrouter.ai/docs/faq

[ SECTION_06 ] // CODE 코드 예제: cURL·Python·Node.js·OpenAI SDK 교체

한국 개발자가 실제로 검색하는 4가지 패턴(원시 HTTP, Python requests, Node, OpenAI SDK 제로 마이그레이션)을 다룹니다.

$ 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 os
import requests

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"])

import os
from openai import OpenAI

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": "안녕하세요"}],
    extra_headers={
        "HTTP-Referer": "https://novakvm.com",
        "X-Title": "NOVAKVM Agent Demo",
    },
)

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: "OpenRouter를 한 문장으로 설명해 주세요." }],
});

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

동적 Agent UI를 위해 사용 가능 모델을 프로그램으로 나열하는 예제입니다.

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

[ SECTION_07 ] // HA 스트리밍과 모델 폴백으로 고가용성 확보

스트리밍은 OpenAI SDK와 동일하게 stream: true입니다. 청크를 순회하면 OpenRouter가 공급자 SSE를 투명 전달합니다.

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);
}

모델 폴백은 모델 레이어 가용성을 담당합니다. 프라이머리가 오류나 속도 제한에 걸리면 OpenRouter는 models 배열을 순서대로 시도합니다.

{
  "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": "안녕하세요" }]
}

게이트웨이 공급자 라우팅(동일 모델 ID 호스트 자동 전환)과 명시적 모델 폴백(Claude → GPT → Gemini)을 결합하면 단일 벤더 장애에 견디는 Agent 구성을 만들 수 있습니다. 비용 드리프트 디버깅 시 응답 메타데이터에서 실제 응답 모델을 로그에 남기시기 바랍니다.

[ SECTION_08 ] // PRICING OpenRouter 요금 해설: 무료 티어·크레딧·5.5%·BYOK

Agent 루프 예산화 전에 공개 요금 페이지에서 모델별 단가를 확인하시기 바랍니다. 리스트 가격만으로는 실제 지출을 예측하기 어렵고, 토큰량 랭킹이 더 정확합니다. 주간 랭킹 분석을 참고하세요.

https://openrouter.ai/models

[ SECTION_09 ] // SEO_PUBLISH 한국어 SEO와 다국어 공개 체크리스트(요약)

한국어 기사 노출이 정체되면 키워드 밀도보다 인덱싱과 네이티브 표현 문제인 경우가 많습니다. OpenRouter 튜토리얼용 압축 런북입니다.

저트래픽 진단(이 순서로 처리):

1. Google Search Console: /ko/ URL 검사. 노출 0은 순위 이전의 크롤/인덱스 문제입니다.
2. CDN/WAF 봇 차단: Googlebot이 빈 SPA나 WAF 챌린지가 아닌 완전 HTML을 받는지 확인합니다.
3. 언어별 canonical: 한국어 페이지 canonical은 novakvm.com/ko/blog/... 자신을 가리키며 다른 언어 URL을 가리키지 않습니다.
4. 사이트맵: 한국어 URL을 명시 나열. 오래된 사이트맵은 발견을 지연시킵니다.
5. 기계번역이 아닌 재작성: 제목과 FAQ는 「OpenRouter API 사용법」「OpenRouter 무료」 등 한국어 실검색어에 맞춥니다.

Schema: 튜토리얼에는 BlogPosting과 FAQPage JSON-LD를 함께 배포합니다. FAQ 질문문은 실검색어(「OpenRouter는 무료인가요?」 등)에 맞춥니다.

배포 채널:

• 한국어: Velog, 티스토리(canonical 자사 사이트), Brunch, X 스레드, 개발자 커뮤니티.
• 영어(병행): dev.to, Hacker News Show HN, Reddit r/LocalLLaMA.

P0~P2 액션:

• P0(이번 주): /ko/ GSC 인덱스 감사, WAF 봇 테스트, canonical·사이트맵 수정.
• P1(작성): 한국어 네이티브 재작성, 제목·리드·H2·FAQ에 키워드 매트릭스 반영, BlogPosting + FAQPage 스키마 추가.
• P2(배포): Velog/티스토리 신디케이션, GSC 사이트맵 재제출, 주간 노출 추적.

[ SECTION_10 ] // FAQ_CLOSE FAQ·추적 지표·NOVAKVM Mac Mini 7×24 Agent 호스팅

Q: OpenRouter는 무료로 사용할 수 있나요?
A: 부분적으로 가능합니다. 25+ 무료 모델이 있으며 미인증은 하루 약 50회, $10 이상 크레딧 후 하루 1,000회(20/분). 유료 프론티어 모델은 공급자 토큰 단가 + 크레딧 충전 5.5% 수수료입니다.

Q: 토큰 단가에 마크업이 있나요?
A: 토큰 마크업은 없습니다. 크레딧 충전 시 5.5%(최소 $0.80), BYOK 월 100만 req 초과 후 5%입니다.

Q: 프로덕션에서 안전한가요?
A: 널리 채택되지만 프롬프트는 OpenRouter 인프라를 경유합니다. 규제 대상 팀은 DPA와 데이터 경로를 확인하고 필요 시 직접 API를 선택하세요.

Q: 지원 모델은?
A: 400+ 모델, 70+ 공급자. GPT-4o, Claude 3.5 Sonnet, Gemini 2.5 Pro, Llama, DeepSeek, Qwen, Mistral 등. /api/v1/models로 최신 목록을 조회할 수 있습니다.

Q: 코드 수정 없이 모델 전환은?
A: model 파라미터를 변경하고 동일 OpenAI 호환 클라이언트를 사용합니다. 복원력이 필요하면 models 배열과 "route": "fallback"을 추가합니다.

Q: 직접 OpenAI/Anthropic 대비 가치는?
A: 멀티 모델 Agent, 빠른 A/B, 통합 청구의 중간 규모 이용에서는 Yes. 초대규모 단일 벤더, 독점 API, 엄격한 지연/거주지 요구에는 No입니다.

공개 후 추적 지표:

• Google Search Console: /ko/와 /en/ 노출·CTR·평균 순위를 분리. 노출 0은 인덱스 문제, 높은 노출 낮은 CTR은 제목/meta 재작성.
• 사이트 분석(Matomo/GA4): 언어별 오가닉, 이탈률, 튜토리얼 구간 체류 시간.
• 수동 스팟 체크: 월 1회 시크릿 모드에서 「OpenRouter API 사용법」 등 핵심 쿼리 3~5개를 검색해 순위 변동을 확인합니다.

• 400+ 모델 / 70+ 공급자: 단일 OpenAI 호환 게이트웨이(출처: OpenRouter docs, 2026년 7월).
• 토큰 마크업 없음: 크레딧 수수료 5.5%만, 최소 $0.80(출처: OpenRouter FAQ).
• 무료 티어: 미인증 약 50 req/일, $10 크레딧 후 1,000 req/일·20 req/분(출처: OpenRouter FAQ).
• BYOK: 월 100만 req 무료, 초과 5%(출처: OpenRouter FAQ).
• 게이트웨이 지연: 직접 공급자 대비 약 10~80ms 추가를 가정(2026 집약 벤치 참고).

OpenRouter는 통합 표면(키 1개, SDK 1개, 내장 페일오버)을 해결하지만 호스트 문제는 해결하지 않습니다. 몇 초마다 OpenRouter를 호출하는 장시간 Agent는 MacBook 덮개를 닫는 순간, OAuth 세션 만료, CI 러너 시간 제한으로 중단됩니다.

OpenRouter Agent 워크로드에서 흔한 대안의 한계: (1) 로컬 노트북 호스팅 — 절전, 서멀 스로틀링, 불안정 Wi-Fi가 7×24 도구 호출을 끊습니다. (2) Linux VPS만 — Xcode, Simulator, Metal이 없어 Apple Silicon에서 macOS 네이티브 Agent 스킬을 검증할 수 없습니다. (3) 공유 클라우드 Mac 슬라이스 — 이웃 테넌트 CPU 스파이크가 스트리밍 추론과 병렬 서브에이전트를 지연시킵니다. iOS CI/CD와 멀티 모델 Agent 자동화에 전용 Apple Silicon, 안정적 Metal, 일/주/월 탄력 청구가 필요한 프로덕션 환경에서는 NOVAKVM Mac Mini M4 / M4 Pro 베어메탈 클라우드 대여가 보통 더 나은 선택입니다. Hermes, OpenClaw, Claude Code, 커스텀 OpenRouter 클라이언트를 설정 파일 하나로 모델을 바꾸며 상시 온라인 노드에서 실행할 수 있습니다. 플랜 비교는 NOVAKVM 대여 가격 페이지, 트라이얼은 주문 페이지, 원격 접속은 고객 센터를 이용하시기 바랍니다.

아래는 작성 시점의 공개 소스입니다. 상류 문서가 업데이트되면 원본을 기준으로 하세요.

OpenRouter Documentation

OpenRouter FAQ

OpenRouter Models and Pricing