모델 목록과 Models API

모델 목록과 Models API

OpenRouter에는 400개가 넘는 모델이 올라와 있어요. 웹사이트 openrouter.ai/models에서 탐색하거나, Models API로 프로그래밍 방식으로 가져올 수 있어요. 새 모델 소식을 RSS 피드로 구독할 수도 있고요. 이 페이지에서는 Models API로 모델 목록을 필터링·정렬·조회하고, 응답 스키마를 해석하는 방법을 정리해요.

출처: https://openrouter.ai/docs/guides/overview/models

쿼리 파라미터

Models API는 쿼리 파라미터로 반환할 모델 목록을 걸러 줘요.

output_modalities 파라미터로 모델의 출력 능력을 기준으로 필터링해요. 콤마로 구분한 값을 넣거나, 출력 유형을 가리지 않는 "all"을 넣으면 돼요.

값 설명
text 텍스트 출력 모델 (기본값)
image 이미지를 생성하는 모델
audio 오디오 출력을 내는 모델
embeddings 임베딩 모델
all 모든 모델 포함, 모달리티 필터링 생략 
# 기본값 (텍스트 모델만)
curl "https://openrouter.ai/api/v1/models"

# 이미지 생성 모델만
curl "https://openrouter.ai/api/v1/models?output_modalities=image"

# 텍스트 + 이미지 모델
curl "https://openrouter.ai/api/v1/models?output_modalities=text,image"

# 모달리티 무관 전체
curl "https://openrouter.ai/api/v1/models?output_modalities=all"

같은 파라미터는 /v1/models/count 엔드포인트에도 있어서, 카운트가 목록 결과와 항상 일치해요.

supported_parameters는 모델이 지원하는 API 파라미터로 거르는 필터예요. 예를 들어 도구 호출(tools)을 지원하는 모델만 찾고 싶다면 이렇게 호출하면 돼요.

curl "https://openrouter.ai/api/v1/models?supported_parameters=tools"

sort는 서버 쪽에서 모델을 정렬해 반환해요. 아래 값 중 하나를 받아요.

값 설명
pricing-low-to-high 값싼 모델 우선 (프롬프트·컴플리션·요청·웹 검색 가격의 가중 평균)
pricing-high-to-low 비싼 모델 우선
context-high-to-low 컨텍스트 윈도우가 큰 순
throughput-high-to-low 초당 토큰이 높은 순 (p50 처리량)
latency-low-to-high 첫 토큰까지 시간이 짧은 순 (p50 지연)
most-popular 지난주 가장 많이 처리된 순
top-weekly most-popular와 동일
newest OpenRouter에 최근 추가된 순

정렬 기준 차원의 데이터가 없는 모델(가격·처리량 통계 없음)은 뒤에 정렬돼요. sort를 빼면 기본 순서(하위 호환)가 유지돼요.

# 값싼 모델 우선
curl "https://openrouter.ai/api/v1/models?sort=pricing-low-to-high"

# 최신 모델
curl "https://openrouter.ai/api/v1/models?sort=newest"

# 필터와 결합
curl "https://openrouter.ai/api/v1/models?sort=throughput-high-to-low&supported_parameters=tools"

단일 모델 조회

전체 목록을 받지 않고 GET /api/v1/model/{author}/{slug}로 단일 모델의 상세 정보만 뽑을 수 있어요. 이 엔드포인트는 별칭을 자동으로 풀어 줘요. 예컨대 anthropic/claude-3-5-sonnet은 정식 슬러그 anthropic/claude-3.5-sonnet으로 리다이렉트돼 그 데이터를 돌려주고, :free 같은 변형 접미사도 지원해요.

# 특정 모델 조회
curl "https://openrouter.ai/api/v1/model/openai/gpt-4o"

# 별칭 자동 해석
curl "https://openrouter.ai/api/v1/model/anthropic/claude-3-5-sonnet"

# 변형 접미사
curl "https://openrouter.ai/api/v1/model/openai/gpt-4:free"

모델이 존재하지 않고 다른 모델의 별칭도 아니라면 404를 돌려줘요. 응답은 목록 엔드포인트와 같은 Model 객체를 감싼 형태예요.

{
  "data": {
    "id": "openai/gpt-4o",
    "name": "GPT-4o",
    "pricing": { "prompt": "0.0000025", "completion": "0.00001" }
  }
}

Models API 표준

Models API는 확인되는 즉시 모든 LLM의 핵심 정보를 무료로 공개해요. 응답은 표준화된 JSON 형식이라 에지에 캐시되어 프로덕션 통합에 안정적으로 쓸 수 있어요.

루트 응답 객체

{
  "data": [ /* Model 객체 배열 */ ],
  "total_count": 150,        // 쿼리 조건에 맞는 모델 수
  "links": {
    "next": "/api/v1/models?offset=500&limit=500" // 다음 페이지 URL, 마지막이면 null
  }
}

페이지네이션은 옵트인이에요. offset과 limit를 모두 빼면 전체 목록이 반환되고 links.next는 null이 돼요. 페이지네이션하면 limit 기본값은 500(최대 1000)이고, links.next가 다음 페이지 준비된 URL을 담아요.

curl "https://openrouter.ai/api/v1/models?offset=0&limit=500"

Model 객체 스키마

data 배열의 각 모델은 다음 표준 필드를 포함해요.

필드 타입 설명
id string API 요청에 쓰는 고유 식별자 (예: "google/gemini-2.5-pro-preview")
canonical_slug string 절대 변하지 않는 정식 슬러그
name string 사람이 읽기 좋은 표시 이름
created number OpenRouter에 추가된 Unix 타임스탬프
description string 모델 능력·특성 상세 설명
context_length number 최대 컨텍스트 윈도우 크기(토큰)
architecture Architecture 모델 기술 능력을 설명하는 객체
pricing Pricing 최상위 제공자의 가격
top_provider TopProvider 주 제공자 설정 정보
per_request_limits 속도 제한 정보 (제한 없으면 null)
supported_parameters string[] 이 모델이 지원하는 API 파라미터 배열
default_parameters object | null 이 모델의 기본 파라미터 (없으면 null)
expiration_date string | null 모델 엔드포인트 지원 중단 날짜 (아니면 null)
benchmarks Benchmarks | undefined 제3자 벤치마크 순위 (데이터 없으면 생략)

Architecture 객체

{
  "input_modalities": ["file", "image", "text"],
  "output_modalities": ["text"],
  "tokenizer": "..." ,        // 사용하는 토큰화 방식
  "instruct_type": null       // 명령 형식 (해당 없으면 null)
}

Pricing 객체

모든 가격은 토큰/요청/단위당 USD예요. 값이 "0"이면 무료라는 뜻이에요.

{
  "prompt": "0.0000025",        // 입력 토큰당 비용
  "completion": "0.00001",      // 출력 토큰당 비용
  "request": "0",               // API 요청당 고정 비용
  "image": "0",                 // 이미지 입력당 비용
  "web_search": "0",            // 웹 검색 1회당 비용
  "internal_reasoning": "0",    // 내부 추론 토큰 비용
  "input_cache_read": "0",      // 캐시 입력 토큰 읽기당 비용
  "input_cache_write": "0",     // 캐시 입력 토큰 쓰기당 비용
  "overrides": []               // 조건부 가격 재정의
}

가격 재정의(Pricing Overrides): 일부 엔드포인트는 특정 조건에서 다른 요율을 매겨요. 토큰 임계값을 넘으면 비싸지는 긴 컨텍스트 가격이나, 피크 시간대에 더 비싼 시간대별 가격 같은 것이 여기 속해요. 이들은 pricing.overrides 배열로 표현돼요.

{
  // 조건: 프롬프트 토큰 총합이 이 임계값보다 클 때 적용
  "min_prompt_tokens": 200000,
  // 조건: 현재 UTC 시간이 이 일일 구간 안일 때
  "utc_start": 1630,   // 16:30 UTC 포함
  "utc_end": 30,       // 00:30 UTC 제외, 자정을 걸쳐 마감하면 wrap에 유의
  // 조건: 이 UTC 요일에만 적용 (없으면 매일)
  "utc_days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
  // 재정의된 가격 (기본 pricing과 같은 키·단위)
  "prompt": "0.000005",
  "completion": "0.00002",
  "input_cache_read": "0.0000005",
  "input_cache_write": "0.00000625"
}

항목은 모든 조건 필드가 요청과 일치할 때 적용돼요. 여러 항목이 걸리면 나중 항목이 키별로 이겨요. 항목에 없는 가격 키는 기본 가격을 상속해요. 최상위 pricing 키는 항상 기본 조건에서의 가격을 반영하고, overrides가 조건부 예외를 담아요.

시간대별 조건은 피크/비피크 가격을 표현해요. overrides 배열은 항상 (피크와 비피크 모두) 하루 24시간 전체를 나란히 늘어놓아, 순간마다 정확히 하나가 일치하게 해요 — 그래서 소비자는 폴백 경로가 필요 없어요. 다음은 16:30~00:30 UTC 사이 반값인 모델 예시예요.

"pricing": {
  "prompt": "0.00000028",
  "completion": "0.00000042",
  "overrides": [
    { "utc_start": 30, "utc_end": 1630, "prompt": "0.00000028", "completion": "0.00000042" },
    { "utc_start": 1630, "utc_end": 30, "prompt": "0.00000014", "completion": "0.00000021" }
  ]
}

utc_days로 범위를 정한 항목은 주간 일정을 표현해요. 피크 구간이 평일만 적용되는 모델은 다음과 같이 보여요 (주말에는 전체 일별 가격만).

"pricing": {
  "prompt": "0.00000028",
  "completion": "0.00000042",
  "overrides": [
    { "utc_days": ["monday","tuesday","wednesday","thursday","friday"], "utc_start": 30, "utc_end": 1630, "prompt": "0.00000056", "completion": "0.00000084" },
    { "utc_days": ["monday","tuesday","wednesday","thursday","friday"], "utc_start": 1630, "utc_end": 30, "prompt": "0.00000028", "completion": "0.00000042" },
    { "utc_days": ["saturday","sunday"], "prompt": "0.00000028", "completion": "0.00000042" }
  ]
}

새 조건 필드는 시간이 지나면 추가될 수 있어요. 인식하지 못하는 조건 필드를 담은 항목은 그 가격을 적용하지 말고 건너뛰어야 해요. 최상위 pricing 키가 항상 기본 조건 가격을 반영하니까요.

Top Provider 객체

{
  "context_length": 200000,    // 제공자별 컨텍스트 한도
  "max_completion_tokens": 8000, // 응답 최대 토큰
  "is_moderated": false        // 콘텐츠 검열 적용 여부
}

입력·출력 토큰은 모델 컨텍스트 윈도우를 공유해요. 그래서 max_completion_tokens는 max_tokens의 상한일 뿐 보장된 출력 크기가 아니에요. 요청의 실제 최대 출력은 입력 토큰을 빼고 남은 컨텍스트로 제한돼요.

Benchmarks 객체

제3자 벤치마크에서 평가된 모델에만 나타나요. 현재는 Design Arena 순위를 포함해요.

{
  "design_arena": [
    {
      "arena": "models",
      "category": "website",
      "elo": 1520,
      "win_rate": 0.62,
      "rank": 3
    }
  ]
}

순위는 OpenRouter에 등록된 모델 사이에서 계산된 것이지, 외부 전체 리더보드가 아니에요. 벤치마크 데이터가 없는 모델은 benchmarks 필드를 아예 생략해요.

지원 파라미터

supported_parameters 배열은 각 모델에서 동작하는 OpenAI 호환 파라미터를 알려 줘요. 대표적으로 tools(함수 호출), tool_choice, max_tokens, temperature, top_p, reasoning(내부 추론 모드), structured_outputs(JSON 스키마 강제), response_format, stop, frequency_penalty, presence_penalty, seed(결정적 출력) 등이 있어요.

모델마다 토큰화 방식이 달라요. GPT·Claude·Llama처럼 여러 글자를 한 덩어리로 나누는 모델이 있는가 하면, PaLM처럼 글자 단위로 토큰화하는 모델도 있어요. 그래서 입력·출력이 같아도 모델에 따라 토큰 수(따라서 비용)가 달라져요. 비용은 해당 모델의 토큰화 기준으로 표시·청구돼요. 정확한 입력·출력 토큰 수는 응답의 usage 필드로 확인할 수 있어요.

원하는 모델이나 제공자가 OpenRouter에 없다면 Discord 채널에서 알려 줄 수 있어요.

더 알아보기