OpenRouter API 가이드: 하나의 API로 주요 AI 모델 활용

API 키 하나, 엔드포인트 하나, 그 뒤에 수백 개의 언어 모델. 이것이 OpenRouter API의 핵심 제안입니다. OpenAI 스키마를 그대로 사용하기 때문에 대부분의 앱은 base URL만 바꾸면 도입할 수 있습니다. 이 가이드는 제로에서 프로덕션급 호출까지 안내합니다.

배울 내용:

• 키를 만들고 curl, Python, TypeScript로 첫 요청 보내기

• 모델 슬러그(vendor/model)를 읽고 :free, :nitro, :floor 같은 배리언트 사용하기

• 스트리밍, 요청 제한, 다중 모델 폴백 처리하기

• 플랫폼 비용 구조를 파악하고, 멀티모달 게이트웨이가 더 나은 경우 알아두기

OpenRouter의 작동 방식

모델 카탈로그

OpenRouter에는 OpenAI, Anthropic, Google, Meta, Mistral, DeepSeek, Qwen 등의 수백 개 모델이 등록되어 있으며, 각 모델 페이지에 토큰당 가격과 컨텍스트 사양이 나와 있습니다 ^[1].

요청이 흐르는 과정

요청이 통합 엔드포인트에 도착하면 라우터가 해당 모델의 업스트림 프로바이더를 선택하고(많은 모델이 여러 프로바이더를 갖습니다) 실행한 뒤, 응답을 OpenAI 형식으로 정규화합니다. 기본적으로 프로바이더 선택은 가격과 가용성의 균형을 맞춥니다 ^[2].

비용

추론은 프로바이더 정가 그대로 청구되며 마진이 없습니다. 플랫폼은 크레딧 구매 시 5.5%(최소 $0.80) 수수료를 부과하고, 무료 모델은 하루 50회 요청으로 제한됩니다($10+ 크레딧을 구매하면 하루 1,000회) ^[3].

빠른 시작

1. 계정과 키 만들기

가입하고 소액 크레딧 팩을 구매한 뒤(무료 티어 상한도 함께 올라갑니다) 대시보드에서 키를 발급하세요. 키는 베어러 토큰이므로 반드시 서버 측에 보관해야 합니다.

2. curl로 첫 요청

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

3. Python과 TypeScript

공식 OpenAI SDK를 그대로 사용할 수 있습니다:

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="google/gemini-2.5-pro",
    messages=[{"role": "user", "content": "Three taglines for a coffee app"}],
)

import OpenAI from "openai";

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

모델 슬러그와 배리언트

슬러그 읽기

모델 ID는 vendor/model-name 형식을 따릅니다. 예를 들어 anthropic/claude-sonnet-4.5 또는 deepseek/deepseek-chat입니다. 모델 페이지에 표시된 문자열이 API가 기대하는 문자열 그대로입니다.

접미사 배리언트

배리언트는 라우팅 힌트일 뿐 다른 가중치가 아닙니다 — 같은 모델, 다른 프로바이더 선택입니다 ^[2].

모델 고르기

카탈로그를 가격, 컨텍스트 윈도우, 모달리티로 필터링한 뒤 자신의 작업으로 벤치마크하세요. 실용적인 사다리는 이렇습니다: :free 배리언트로 프로토타입을 만들고, 중급 모델로 출시하고, 어려운 10%의 요청에는 프론티어 모델을 남겨 둡니다.

프로덕션 고려 사항

스트리밍

"stream": true를 설정하고 server-sent events를 소비하면 됩니다 — OpenAI 스트리밍 규약과 동일하므로 기존 스트리밍 UI 코드가 그대로 작동합니다.

요청 제한과 재시도

제한은 고정 티어가 아니라 크레딧 잔액에 따라 확장됩니다. 429 응답에는 지수 백오프로 대응해야 합니다. 무료 모델은 하루 50/1,000 상한을 기준으로 예산을 잡으세요 ^[3].

폴백

우선순위를 매긴 models 배열을 전달하면, 오류나 요청 제한이 발생했을 때 라우터가 서버 측에서 다음 모델을 재시도합니다 ^[4]:

{
  "model": "openai/gpt-5.2",
  "models": ["anthropic/claude-sonnet-4.5", "deepseek/deepseek-chat"],
  "messages": [{ "role": "user", "content": "..." }]
}

언어 모델만으로 부족할 때

OpenRouter가 통합하는 것은 텍스트입니다. 로드맵에 "제품 이미지 생성"이나 "동영상 클립 추가"가 등장하는 순간, 다시 벤더별 개별 연동으로 돌아가게 됩니다 — 게이트웨이가 해당 모달리티를 기본으로 지원하지 않는 한 말이죠.

미디어 모델까지 포함하는 통합 API

APIMart는 같은 원키 패턴을 채팅, 이미지(GPT-Image-2), 비디오(Sora 2, Kling, Veo), 오디오(Suno)에 걸친 500+ 모델에 적용합니다.

정가가 아닌 정가 이하의 가격

모델은 대략 공식 가격보다 20% 낮게 제공되며, 모델별 정가 대비 할인가는 가격 페이지에 공개되어 있습니다 — 별도의 수수료 계산이 필요 없습니다.

같은 코드 그대로 전환

엔드포인트가 OpenAI 호환이므로 위의 빠른 시작 코드는 base URL과 키만 바꾸면 동작합니다. 모델 레지스트리와 폴백 로직도 손대지 않고 그대로 옮겨집니다.

정리

OpenAI SDK를 통합 엔드포인트로 향하게 하고, 모델은 vendor/model 슬러그로 참조하며, 비용이나 속도가 중요하면 :floor나 :nitro를 사용하고, 프로덕션 전에 models 폴백 배열을 추가하세요. 그리고 실제 비용은 정가에 5.5% 충전 수수료를 더한 값이라는 점을 기억해야 합니다 ^[3]. 앱에 이미지, 비디오, 오디오까지 필요하다면 처음부터 이를 지원하는 게이트웨이로 시작하세요.