OpenRouter 사용법 2026 — API 키 발급·모델 폴백·비용 한도까지 한 번에

OpenRouter 는 모델을 하나 더 파는 곳이 아니라, 여러 모델을 한 창구로 묶는 곳이다. 키 하나와 base URL 한 줄을 바꾸면 OpenAI·Anthropic·Google·오픈소스 모델을 같은 코드로 호출한다. 그래서 「어느 모델을 쓸 것인가」를 지금 결정하지 않아도 되고, 나중에 바꿀 때 코드를 다시 쓰지 않아도 된다.

결론부터 말하면, 회사에서 OpenRouter 를 쓸 때 갈리는 것은 호출 방법이 아니다. 호출은 다섯 줄이면 끝난다. 실제로 갈리는 것은 셋이다 — ① 요금이 어디에 붙나 ② 우리 프롬프트가 어느 공급자까지 가나 ③ 사람별·용도별로 한도를 어떻게 끊나. 이 글은 그 셋을 중심으로 정리했다.

OpenRouter 는 모델이 아니라 창구다

구조는 단순하다. 우리 코드는 OpenRouter 한 곳에만 요청을 보내고, OpenRouter 가 그 요청을 실제 모델 공급자에게 넘긴다. 돌아오는 응답 형식은 OpenAI 호환이다.

이 구조에서 얻는 것이 셋이다.

• 키가 하나다. 공급자마다 계정을 만들고 결제수단을 등록하고 키를 관리하지 않는다.
• 모델 교체가 문자열 한 줄이다. 코드 구조는 그대로 두고 모델 ID 만 바꾼다.
• 한 공급자가 죽어도 요청이 산다. 뒤에서 다른 공급자로 재시도된다(아래 라우팅 절).

반대로 잃는 것도 분명하다. 공급자와 직접 계약하는 대신 중간에 한 층이 생기므로, 데이터 경로와 장애 책임 구분이 한 단계 복잡해진다. 그 비용을 뒤에서 하나씩 적었다.

첫 호출까지 — base URL 한 줄과 키 하나

OpenAI SDK 를 쓰고 있다면 바꾸는 것은 두 줄이다.

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "요약해줘"}],
)

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":"요약해줘"}]}'

엔드포인트는 https://openrouter.ai/api/v1 이고, 채팅은 /api/v1/chat/completions 다. 필수 헤더는 Authorization: Bearer <키> 와 Content-Type: application/json 둘뿐이다. HTTP-Referer(사이트 URL)와 X-OpenRouter-Title(사이트 이름)은 선택이고, 공식 문서는 OpenRouter 순위표에 우리 앱이 뜨게 하는 용도라고 적는다 — 회사 내부용이라면 넣을 이유가 없다.

EU 안에서 처리해야 하는 요건이 있는 조직은 Business·Enterprise 플랜에서 https://eu.openrouter.ai/api/v1 를 쓸 수 있다.

모델 ID 는 「제공자/모델」 한 줄이다

모델 ID 는 provider/model 형태의 슬러그다. openai/..., anthropic/..., google/... 처럼 앞에 제공자가 붙는다. 쓸 수 있는 전체 목록은 GET /api/v1/models 로 받는다 — 문서에 박힌 목록을 보지 말고 이 엔드포인트를 한 번 찍어서 현재 값을 쓰는 게 맞다. 모델은 계속 뜨고 지므로, 코드에 모델 ID 를 하드코딩해 두면 반년 뒤에 404 를 본다.

운영에서는 모델 ID 를 설정값으로 빼 두는 것이 사실상 필수다. 그래야 모델 교체가 배포가 아니라 설정 변경이 된다.

요금: 추론에는 마크업이 없고, 충전에 수수료가 붙는다

여기가 가장 많이 오해받는 지점이다. OpenRouter 는 추론 단가에 마크업을 붙이지 않는다. 공식 FAQ 가 "공급자 가격을 그대로 전달하며 추론 가격에 마크업이 없다"고 적는다. 대신 크레딧을 충전할 때 수수료가 붙는다.

최소 수수료 $0.80 이 실무에서 더 아프다. $5 를 충전하면 수수료가 $0.80 이라 실효 16% 다. $100 을 충전하면 $5.50 로 표기 요율과 같아진다. 즉 소액을 자주 충전하는 방식이 가장 비싸다. 회사에서 쓴다면 충전 단위를 키우고 횟수를 줄이는 쪽이 단순히 싸다.

그리고 이 구조 때문에 「OpenRouter 가 비싸다」는 말과 「싸다」는 말이 둘 다 맞게 된다. 추론만 보면 직접 계약과 같고, 충전까지 포함하면 5.5% 가 얹힌다. 비교할 때는 어느 쪽을 세고 있는지 먼저 맞춰야 한다. 특정 모델의 요금제 자체를 따지는 중이라면 클로드 요금제 정리를 같이 본다.

한도: 무료 모델만 숫자가 정해져 있다

읽을 때 주의할 점이 셋이다.

• 기준은 「현재 잔액」이 아니라 「누적 구매액」이다. 한 번 10 크레딧을 샀으면 잔액이 줄어도 1,000 RPD 쪽에 남는다.
• 계정이나 키를 더 만들어도 한도가 안 늘어난다. 문서가 "용량을 전역으로 관리한다"고 못 박는다.
• 유료 모델에 플랫폼 상한이 없다는 말은 공급자 쪽 한도가 없다는 뜻이 아니다. 뒤쪽 공급자의 429 는 그대로 온다.

공급자 라우팅 — 아무것도 안 적으면 무엇이 일어나나

같은 모델을 여러 공급자가 서빙한다. 아무 옵션도 안 주면 OpenRouter 가 실효 가격·처리량·첫 토큰까지 시간·429 발생률·신뢰도·툴 호출 품질을 보고 요청마다 하나를 고른다. 상위 공급자들이 트래픽을 나눠 가지고, 각 요청은 그 비중에 따라 확률적으로 배정된다.

운영에서 알아 둘 동작이 셋이다.

• 오류율·429 가 다른 공급자보다 크게 나쁜 곳은 회복할 때까지 트래픽을 받지 않는다.
• 요청이 실패하면 남은 공급자 중에서 같은 방식으로 골라 재시도한다. 우리 코드에서 재시도를 짜지 않아도 한 겹이 이미 있다.
• 대화의 후속 요청은 프롬프트 캐시가 살아 있는 동안 같은 공급자에 붙는다. 긴 대화에서 캐시 할인을 받으려면 이 동작을 깨지 않는 게 낫다.

provider 옵션 — 실제로 쓰는 것은 네 개다

요청 본문에 provider 객체를 넣어 라우팅을 통제한다. 문서에 옵션이 여럿 있지만 회사 환경에서 실제로 손대는 것은 아래 넷이다.

{
  "model": "anthropic/claude-3.5-sonnet",
  "provider": {
    "data_collection": "deny",
    "allow_fallbacks": false,
    "order": ["anthropic"]
  },
  "messages": [{"role": "user", "content": "..."}]
}

data_collection: "deny" 와 allow_fallbacks: false 를 같이 쓰는 것이 핵심이다. 조건에 맞는 공급자가 하나도 없으면 요청은 조용히 다른 곳으로 가지 않고 실패한다. 데이터 경로를 보장해야 하는 조직에서는 실패하는 쪽이 정답이다. 이 밖에 ignore(특정 공급자 제외), sort("price"·"throughput"·"latency"), quantizations(int4·int8·fp8 등)가 있고, sort 를 쓰면 기본 라우팅은 우회된다.

모델 폴백 — 한 모델이 죽어도 서비스는 산다

공급자 폴백과 모델 폴백은 다른 층이다. models 배열에 여러 모델을 넣으면 서로의 대체가 된다.

{
  "models": [
    "anthropic/claude-3.5-sonnet",
    "openai/gpt-4o",
    "google/gemini-1.5-pro"
  ],
  "messages": [{"role": "user", "content": "..."}]
}

정렬 기본값은 sort.partition = "model" 이라 첫 모델의 엔드포인트를 전부 먼저 시도한 뒤 다음 모델로 넘어간다. "none" 으로 바꾸면 모델 구분 없이 전체 엔드포인트를 한 묶음으로 정렬한다. 성능 선호 조건(최소 처리량·최대 지연 등)을 못 맞추는 모델·공급자도 다른 선택지가 전부 실패하면 폴백으로는 남는다.

실무에서 이게 왜 중요한가. 모델 하나가 몇 시간 장애를 내는 일은 드물지 않고, 그때 폴백이 없으면 그 모델을 쓰는 사내 기능 전부가 멈춘다. 사내 도구라면 「조금 떨어지는 모델로라도 돌아가는 것」이 거의 언제나 낫다.

데이터가 어디로 가나 — 로깅·학습·EU 라우팅

회사 도입 심사에서 가장 먼저 걸리는 항목이다. 공식 문서 기준으로 확인되는 사실만 적는다.

• 기본은 비로깅이다. 타임스탬프·모델·토큰 수 같은 요청 메타데이터는 남고, 프롬프트와 응답 본문은 기본적으로 저장되지 않는다. 오류가 나도 마찬가지다.
• 로깅을 켜면 사용 요금을 1% 할인받는다. 설정에서 켜는 선택 항목이다. 거꾸로 말하면, 아무 설정도 안 건드린 상태가 비로깅이다.
• 로깅하거나 정책이 확인되지 않은 공급자는, 개인정보 설정의 모델 학습 토글을 켜지 않는 한 라우팅 대상에서 빠진다. 그리고 조건에 맞는 공급자가 없으면 요청이 실패한다.
• EU 라우팅: eu.openrouter.ai 로 보낸 요청은 EU 에서 복호화되어 유럽(EU·EEA·영국·스위스) 공유 엔드포인트로 간다. 다만 계정·청구 데이터는 미국에서 처리될 수 있다고 문서가 명시한다.

주의할 표현이 하나 있다. 문서는 프롬프트가 학습에 쓰이지 않도록 공급자와 협의한다고 적되 "가능한 경우"라는 단서를 단다. 즉 전면 보증이 아니다. 그래서 사내 문서·고객 데이터가 프롬프트에 들어가는 용도라면, 위의 data_collection: "deny" 를 코드에서 강제하고 그 사실을 보안 심사 문서에 적는 편이 안전하다.

국외 이전 자체가 막히는 조직이라면 게이트웨이가 아니라 다른 층의 문제다 — 온프레미스 LLM 구축이나 로컬 LLM 운영 쪽을 먼저 본다.

BYOK — 이미 있는 계정을 그대로 꽂을 때

이미 OpenAI·Anthropic 과 직접 계약이 있고 크레딧이 남아 있다면, 그 키를 OpenRouter 에 등록해서 쓰는 방식(BYOK)이 있다. 이때 추론비는 우리 공급자 계정에서 직접 빠지고, OpenRouter 에는 수수료만 낸다.

• Pay-as-you-go 플랜은 월 $25,000 까지 BYOK 수수료가 없다. 기준은 요청 건수가 아니라 정가 기준 추론 비용이다.
• 그 한도를 넘는 사용분은 같은 모델·공급자를 OpenRouter 에서 썼을 때 가격의 5% 를 크레딧에서 차감한다.
• Enterprise 는 별도 협의다.

실질적으로 대부분의 중소 규모 조직은 BYOK 수수료를 낼 일이 없다. 월 $25,000 은 작은 선이 아니다. 기존 계약을 유지하면서 라우팅·폴백·사용량 가시성만 얻고 싶을 때 쓰는 선택지다.

사람별·용도별 키와 월 한도

회사에서 쓸 때 가장 실용적인 기능인데 가장 안 알려져 있다. 관리 API 키로 런타임 키를 코드로 찍어낼 수 있다.

생성할 때 limit(크레딧 한도)을 같이 준다. 수정할 때는 disabled(즉시 차단), limit_reset(예: 'daily' — UTC 자정 리셋), include_byok_in_limit(BYOK 사용분을 한도에 포함할지)을 바꾼다. 현재 키의 소진 상황은 GET /api/v1/key 로 본다.

{
  "limit": 1000,
  "limit_reset": "daily",
  "limit_remaining": 842,
  "include_byok_in_limit": false,
  "usage_daily": 158,
  "usage_weekly": 902,
  "usage_monthly": 3140
}

이게 왜 중요한가. 팀 하나에 키 하나를 공유하면 누가 얼마를 썼는지 영원히 모른다. 사람별·용도별로 키를 쪼개고 각 키에 월 한도를 걸면, 비용 사고가 전사 장애가 아니라 한 사람의 한도 초과로 끝난다. 조직 관리자가 설정하는 예산 한도는 가드레일 예산 → 워크스페이스 예산 → 키 자체 한도 순으로 검사되고, 창은 UTC 자정에 리셋된다.

다만 여기까지가 게이트웨이의 일이다. 키와 한도는 개발자가 코드로 관리하는 층이고, 직원이 실제로 쓰는 화면·폴더 권한·감사 기록은 다른 층에 있다. 그 층까지 같이 세우려면 트리나 AX 같은 사내 AI 업무 공간을 올리는 쪽이 맞다 — 사람별 사용량과 월 한도, 사람별 접근 권한(권한 없는 폴더는 이름조차 뜨지 않는다), 감사 로그를 직원이 쓰는 화면과 같은 자리에서 관리한다. 코드가 AGPL-3.0 으로 공개돼 있어 자체 서버에 직접 올리는 쪽은 라이선스 비용이 들지 않는다.

회사에 넣을 때 실제로 막히는 세 가지

① 결제가 선충전이고 USD 다. 크레딧을 먼저 사고 쓰는 구조라 월말 정산에 익숙한 경리 프로세스와 어긋난다. 충전 수수료 최소 $0.80 때문에 소액 다회 충전이 불리하다는 점도 여기서 같이 설명해야 한다. 품의를 올릴 때는 「월 N 달러를 한 번에 충전」 형태로 적는 편이 통과가 빠르다.

② 모델 ID 하드코딩. 도입 첫 주에 짠 코드가 반년 뒤 깨지는 가장 흔한 원인이다. 모델 ID 는 환경변수나 설정 테이블로 뺀다.

③ 데이터 경로를 아무도 안 적어 둔다. data_collection 을 기본값으로 두면 「어느 공급자까지 가는가」에 답할 수 없다. 보안 검토가 들어오는 순간 전부 다시 봐야 한다. 첫날에 deny 를 박아 두는 비용이 가장 싸다.

세 가지 모두 기술 문제가 아니라 도입 절차 문제다. 그래서 게이트웨이를 붙이는 작업과 사내 규정·품의·보안 검토를 같이 끌고 가야 일정이 안 밀린다.

언제 OpenRouter 가 답이 아닌가

반대로 맞는 경우는 분명하다. 모델을 아직 못 정했거나, 여러 모델을 비교하면서 운영하거나, 사람별·용도별로 비용을 끊어야 하거나, 한 모델 장애에 서비스가 멈추면 안 될 때다.

도입 순서 — 4주

3주차가 가장 자주 건너뛰어진다. 그리고 그 결과가 반년 뒤 「AI 비용이 왜 이렇게 나왔는지 모르겠다」로 돌아온다. 키를 쪼개는 작업은 나중에 할수록 비싸진다.

자주 묻는 질문

OpenRouter 를 쓰면 직접 계약보다 비싼가? 추론 단가는 같다. 마크업이 없다고 공식 문서가 적는다. 차이는 크레딧 충전 수수료 5.5%(최소 $0.80) 다. 충전 단위를 키우면 표기 요율에 수렴한다. 이미 직접 계약이 있다면 BYOK 로 추론비를 기존 계정에서 빼고 라우팅만 얹는 방법도 있다.

무료 모델로 운영에 쓸 수 있나? 한도가 정해져 있다. 누적 구매 10 크레딧 미만이면 하루 50 요청, 그 이상이면 하루 1,000 요청이고 분당 20 요청이다. 사내 도구 한 개의 테스트에는 되고 운영에는 안 된다. 계정이나 키를 더 만들어도 한도는 안 늘어난다.

프롬프트가 학습에 쓰이나? 프롬프트와 응답은 기본적으로 저장되지 않는다. 다만 문서가 "가능한 경우" 학습에 쓰이지 않도록 한다고 적어 전면 보증은 아니다. 사내 데이터를 넣는다면 data_collection: "deny" 와 allow_fallbacks: false 를 코드에서 강제하고, 조건에 맞는 공급자가 없을 때 요청이 실패하도록 둔다.

사람마다 쓴 비용을 알 수 있나? 키를 사람별·용도별로 쪼개면 된다. 관리 API 로 키를 생성할 때 limit 을 주고 limit_reset: 'daily' 로 주기를 건다. 키 하나를 공유하면 사후에 쪼갤 방법이 없다.

모델이 사라지면 어떻게 되나? 모델 ID 가 유효하지 않게 된다. 그래서 GET /api/v1/models 로 현재 목록을 확인하고, 모델 ID 를 설정값으로 빼고, models 배열에 폴백을 둔다. 이 셋을 하면 모델 은퇴가 장애가 아니라 설정 변경이 된다.

정리

• OpenRouter 는 모델이 아니라 창구다. base URL 한 줄과 키 하나로 여러 공급자를 같은 코드로 부른다.
• 추론에는 마크업이 없고 충전에 5.5%(최소 $0.80)가 붙는다. 소액 다회 충전이 가장 비싸다.
• 라우팅은 안 건드려도 돌아가지만, 회사에서는 data_collection: "deny" + allow_fallbacks: false 를 첫날에 박아 둔다. 맞는 공급자가 없으면 실패하는 것이 정답이다.
• models 배열로 모델 폴백을 둔다. 한 모델의 장애가 사내 기능 전체를 멈추지 않게 하는 가장 싼 방법이다.
• 키를 사람별·용도별로 쪼개고 월 한도를 건다. 나중에 할수록 비싸지고, 안 하면 비용 추적이 영원히 불가능해진다.

모델 선택과 게이트웨이 구성에서 끝나지 않고 사내 자료 연결·권한 설계·내재화까지 한 번에 세우는 일은 AX 컨설팅에서 함께 진행한다. 운영에 올린 뒤 호출·지연·오류를 보는 층은 LLM 모니터링 도구 비교에 정리해 뒀다.