OpenRouter API 단일 키 400+ 모델 2026-07-24

OpenRouter API 실무 가이드：GPT·Claude·Gemini 단일 키 연동 (2026)

누가 읽어야 하나요? OpenRouter와 OpenAI·Anthropic·Google 직접 API 중 무엇을 선택할지 고민하는 백엔드·Agent 개발자입니다.얻는 것: 의사결정 비교표, API 키 3단계 설정, curl·Python·Node.js 실행 예제(스트리밍·폴백 JSON 포함), 토큰 마크업 없음·5.5% 충전 수수료·BYOK를 반영한 가격 설명.구성: 5가지 도입 이유, 4가지 비추천 시나리오, 검증 체크리스트, FAQ 8문항.

OpenRouter API 통합 게이트웨이: 하나의 API 키로 GPT Claude Gemini 모델 호출

목차

관련 글: OpenRouter 랭킹과 Agent 선정, 주간 토큰 랭킹.

핵심 요약

OpenRouter는 통합 LLM API 게이트웨이입니다. 하나의 OpenRouter API 키와 OpenAI 호환 엔드포인트(https://openrouter.ai/api/v1/chat/completions)로 400개 이상 모델을 model 문자열만 바꿔 호출합니다(예: openai/gpt-4o, anthropic/claude-3.5-sonnet). 기존 OpenAI SDK는 base_url과 api_key만 교체하면 되며, 토큰 마크업은 없습니다(크레딧 충전 시 5.5% 수수료).

01 · OpenRouter란?

  • 단일 엔드포인트: Authorization: Bearer $OPENROUTER_API_KEY + provider/model 형식 ID.
  • 이중 라우팅: model로 모델 선택, provider 객체로 공급자 선호(기본 가격 가중).
  • 내장 장애 조치: 업스트림 rate limit·5xx 시 models 배열로 자동 전환.
  • 투명한 가격: 토큰 단가는 업스트림과 동일. 플랫폼 수익은 충전 5.5%(최소 $0.80) 또는 BYOK 초과 5%.
  • 무료 티어: 25+ 무료 모델, 미충전 ~50 req/일, $10 충전 후 ~1,000 req/일, 무료 모델 20 req/분 제한.

하드 데이터 #1: 공개 리더보드에서 롤링 7일 28조+ 토큰 소비가 관측됩니다. 청구 분석 참고.

02 · 3가지 의사결정 함정

  1. 「무료 GPT」로 오해: 무료 모델은 있지만 GPT·Claude·Gemini 플래그십은 유료 크레딧을 소모합니다. 예산 알림 없이 쓰면 5.5% 수수료를 나중에 알게 됩니다.
  2. 지연 비용 무시: 게이트웨이 홉으로 전형적 10–80 ms 추가. 음성·저지연 트레이딩은 사전 벤치마크 필수.
  3. 일상 MacBook에서 A/B: Cursor·OpenClaw·커스텀 Agent가 키를 셸 프로필에 남기고 캐시를 오염시킵니다. 격리 하드웨어가 더 안전합니다.

03 · OpenRouter vs 직접 API

항목 OpenRouter 직접 API
API 키1키로 400+ 모델벤더별 계정·키·청구
SDK 마이그레이션OpenAI 호환 base_url 교체벤더 SDK 또는 어댑터
토큰 가격마크업 없음공시가
플랫폼 수수료충전 5.5%(최소 $0.80)게이트웨이 비용 없음
장애 조치내장 폴백자체 재시도·서킷브레이커
대시보드통합 사용량·비용·TTFT벤더별 콘솔
전용 기능일부만(Batch/Assistants 제한)전체 vendor 기능
최적 사용다중 모델·프로토타입·월 ~$10k 미만단일 모델 대규모·엄격 컴플라이언스

하드 데이터 #2: 월 100만 토큰 Claude Sonnet 기준 5.5% 수수료는 약 $4–8 — 3벤더 통합 유지보수보다 저렴한 경우가 많지만, 월 $50k+면 BYOK·직접 계약 비교가 필요합니다.

04 · OpenRouter를 쓰는 5가지 이유

이유 1: 하나의 키로 모든 모델

openai/gpt-4o에서 anthropic/claude-3.5-sonnet으로 model만 변경. 메시지 형식·스트림 파서 유지.

이유 2: 자동 장애 조치

models 폴백 체인으로 커스텀 서킷브레이커 제거(08절).

이유 3: 통합 청구·분석

단일 대시보드로 토큰 지출·지연·모델 mix 추적 — CLI 도구가 OpenRouter 트래픽 70%+를 차지.

이유 4: 토큰 마크업 없음

공식 FAQ에서 업스트림 pass-through 명시.

이유 5: 무료 모델로 프로토타입

Llama·Gemma·DeepSeek 무료 티어 등 25+ 모델로 해커톤·CI 스모크 테스트.

쓰지 말아야 할 경우

  • 단일 모델 초대규모(5.5%가 엔터프라이즈 직계약 초과)
  • OpenAI Batch·Assistants, Anthropic prompt cache 등 전용 API 필요
  • 미국 제3자 게이트웨이 금지 데이터 레지던시(BYOK 법무 검토 제외)
  • 50 ms 미만 추론 SLA

05 · API 키 3단계 설정

  1. 계정·키 생성: openrouter.ai GitHub/Google 로그인 → Keys에서 dev-mac-sandbox 등 환경별 이름으로 생성.
  2. 환경 변수·한도: export OPENROUTER_API_KEY="sk-or-..."(git 커밋 금지). 키별 credit limit 설정.
  3. curl 검증 후 IDE 연결: 아래 예제로 GPT·Claude·Gemini 각 1회 성공 확인 후 Cursor·LangChain·OpenClaw 연결.

06 · 코드 예제

6.1 curl

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": "양자컴퓨팅을 한 문장으로 설명해." } ] }'

6.2 Python

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

6.3 OpenAI SDK

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": "OpenRouter에서 인사!"}], ) print(completion.choices[0].message.content)

6.4 Node.js

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

하드 데이터 #3: 모델 ID는 provider/model 필수. 400+ 항목. gpt-4o 단독은 404.

07 · 스트리밍

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

08 · 폴백 라우팅 JSON

{ "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" }] }

09 · Models API

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

10 · 요금: 5.5%·BYOK·무료 티어

유형 율 비고
유료 토큰업스트림 공시가마크업 없음
크레딧 충전5.5%(최소 $0.80)잔액 충전 시
BYOK월 100만 req 무료초과 5%
무료 모델$0~50/일 → $10 후 ~1,000/일
무료 제한20 req/분무료 엔드포인트

11 · 5단계 검증

  1. 격리 머신에서 disposable 키 발급 → curl 3모델 테스트
  2. OpenAI SDK base_url 교체 → schema 일치 확인
  3. stream: true TTFT 직접 API와 비교
  4. fallback JSON 의도적 실패 → 체인 성공 확인
  5. CSV 저장 → 키 폐기·환경 삭제

12 · FAQ

Q: 무료인가요?
A: 25+ 무료 모델. 플래그십은 유료 크레딧.

Q: 마크업?
A: 토큰 마크업 없음. 5.5% 충전 또는 BYOK 5%.

Q: 직접 OpenAI보다 나을까?
A: 다중 모델·중간 규모면 대체로 Yes. 초대규모 단일 모델은 직접 API.

Q: 기존 Python 코드?
A: base_url·키·provider/model만 변경.

Q: 폴백?
A: models + route: fallback.

Q: 모델 수?
A: 400+. GET /api/v1/models.

Q: 프로덕션 안전?
A: 널리 사용. 키 분리·교체 필수.

Q: 스트리밍?
A: stream: true, OpenAI 호환 SSE.

13 · 대여 Mac으로 OpenRouter 다중 모델 테스트

Linux VPS에서도 curl은 동작하지만, 실무에서는 Cursor BYOK, OpenClaw 게이트웨이, macOS Keychain 격리, IDE Agent 병행 검증이 핵심입니다. 일상 MacBook에서 GPT·Claude·Gemini A/B를 돌리면 키가 .zshrc에 남고 캐시가 섞입니다.

3일 라우팅 스프린트에 Mac mini 구매는 고정비가 큽니다. 일일 과금 대여는 키 생성→벤치마크→폐기→노드 삭제 사이클에 맞습니다. 브라우저 채팅 UI는 스트림 파서·폴백·모델별 비용 로그 검증에 부적합합니다. 격리 Apple Silicon 대여 Mac은 실험 키를 Keychain에서 분리하고 Cursor·OpenClaw에 OpenRouter를 연결해도 프로덕션 프로필을 오염시키지 않습니다. Mac mini M4 대여 TCO 참고.

14 · 참고 자료

최종 업데이트: 2026-07-24