Cafe24 LLM Router는 OpenAI SDK 호환 API를 제공합니다. 하나의 API Key로 OpenAI, Anthropic, Google, DeepSeek 등 여러 프로바이더의 모델을 사용할 수 있습니다.

Authentication

API를 호출하려면 먼저 API Key가 필요합니다.

1. API Key 발급

API 키 관리 페이지에서 키를 생성합니다. 키는 생성 시 한 번만 표시되므로 안전하게 저장하세요.

2. 연결 테스트

Quick Start

API Key가 준비되었으면 Chat Completion을 호출합니다.

Auto Routing

cafe24/auto 모델을 사용하면 프롬프트를 분석하여 코딩, 추론, 번역, 창작 등 task 유형을 자동 판별하고 최적 모델을 선택합니다.

Allowed Models (Account 영구 설정)

매 요청에 model_pool을 보내는 대신, 라우팅 설정 의 Allowed Models 필드에 와일드카드 패턴을 저장하면 모든 cafe24/auto 호출에 자동 적용됩니다 (per-request model_pool이 없을 때).

적용 범위

Auto Router 관련 설정 (cost_quality_balance, model_pool, Account의 allowed_models)은 cafe24/auto 모델로 호출했을 때만 적용됩니다. 다른 모델 (Qwen/Qwen3-32B, deepseek-ai/DeepSeek-V3.1 등) 호출 시에는 무시됩니다. 계정의 Access Control 과 데이터 정책은 언제나 적용되며, 막힌 모델은 후보에서 제외됩니다.

응답

Provider Routing

요청의 provider 객체로 프로바이더 선택을 제어합니다. 설정은 3-layer로 머지됩니다: Account < Preset < Request (request 최우선).

API(/api/v1) 요청에서 해석되는 provider 필드는 위 표의 필드뿐입니다. max_price, require_parameters, quantizations, preferred_min_throughput, preferred_max_latency 는 지원하지 않습니다 — 함께 보내도 요청은 정상 처리되지만 해당 조건은 적용되지 않으므로, 비용 상한이 걸린 것으로 기대하고 호출하지 마세요.

정책 우선순위 (3-layer)

Provider Routing 설정은 3개 layer로 머지됩니다. Account < Preset < Request (request가 최우선).

쉽게 말하면

• Account 는 큰 울타리입니다. 사용자 본인이 Web 설정에서 정한 정책이며, 모든 요청에 항상 먼저 적용됩니다.
• Preset 과 Request 는 그 울타리 안에서 동작합니다. Account 가 차단한 provider 는 Preset 이나 Request 에서 다시 허용할 수 없습니다.
• "무엇만 허용한다"(only) 는 가장 좁은 범위로 좁혀지고, "무엇을 차단한다"(ignore) 는 모두 합쳐서 차단합니다. 즉 안전한 방향으로 머지됩니다.
• "어느 순서로 시도할지"(order), "무엇 기준으로 정렬할지"(sort) 같은 단일 값은 Request 가 명시한 값이 가장 우선합니다 (없으면 Preset, 없으면 Account 순).

필드별 Merge 규칙

Account / Preset / Request 가 모두 지정되어 있을 때 각 필드별 머지 동작입니다. 한 layer 만 지정되어 있으면 그 값이 그대로 사용됩니다.

위 표는 머지 규칙이고, layer 별로 지정 가능한 필드는 다릅니다. Request layer (/api/v1 요청의 provider 객체)에서 해석되는 필드는 order·only·ignore·sort·allow_fallbacks·zdr·data_collection 7개이고(위 Provider Routing 참고), 계정 단위 설정으로 저장되는 값은 only·ignore·sort 와 Access Control 1단계의 데이터 정책(보관·학습·처리 지역)입니다.

시나리오 예시

실제 사용 상황에서 각 layer 의 설정이 어떻게 합쳐지는지 보여드립니다.

Access Control — 모델별 프로바이더 범위

라우팅 설정 의 Access Control 에서 모델을 추가하면, 칩 안에 그 모델을 제공하는 프로바이더가 버튼으로 보입니다. 버튼마다 그 프로바이더에서의 실제 결과(차단 / 허용)가 적혀 있고, 누르면 그 프로바이더에서만 바뀝니다. 모델을 추가하면 처음에는 모든 프로바이더에 적용됩니다(차단 모드는 모두 차단, 허용 모드는 모두 허용). 와일드카드 항목(anthropic/claude-*)은 패턴에 맞는 모델을 제공하는 프로바이더가 나옵니다. 프로바이더 목록에서 이미 막힌 프로바이더는 점선 버튼으로 보이고, 모델 칩에서는 풀 수 없습니다. 같은 모델에 맞는 다른 항목(예: *claude-opus-4-7)이 결과를 정하면 버튼에 * 가 붙고, 버튼에 마우스를 올리면 그 항목 이름이 보입니다 — 버튼 글자는 언제나 저장했을 때의 실제 결과입니다.

규칙은 하나입니다 — 요청이 쓸 수 있는 프로바이더 중 허용된 곳이 있으면 그곳으로 라우팅하고, 없으면 403 입니다. 이 규칙은 모든 엔드포인트에 적용됩니다 — 채팅(/v1/chat/completions·/v1/messages·/v1/responses)뿐 아니라/v1/embeddings, /v1/images/*, /v1/audio/*, /v1/rerank, /v1/videos/generations, /v1/systemone 도 같습니다. 차단한 짝은 폴백·재시도를 포함해 어떤 경우에도 호출하지 않습니다. 단, BYOK(본인 키) 호출에는 프로바이더 범위가 적용되지 않습니다 — 범위를 고르지 않은 모델 항목은 BYOK 호출에도 그대로 적용됩니다.

데이터 정책 — 보관(ZDR)·프롬프트 학습·처리 지역

라우팅 설정의 Access Control 1단계 "데이터 정책 필터" 에서, 프로바이더가 프롬프트를 보관하는지(ZDR)·학습에 쓰는지·어느 지역에서 처리하는지에 따라 호출할 곳을 한 번에 정합니다. 판정 기준은 관리자가 관리하는 프로바이더·모델별 데이터 정책이며, 모델 화면의 프로바이더 표에 배지(보관 안 함 / 보관함 / 학습에 씀 / 보관 미확인 / 학습 미확인 / 미확인)로 보입니다. Access Control 2단계(프로바이더·모델 제한)와 함께 적용되어, 둘 다 통과한 프로바이더로만 보냅니다.

{
  "model": "anthropic/claude-opus-4-7",
  "messages": [{ "role": "user", "content": "..." }],
  "provider": { "zdr": true, "data_collection": "deny" }
}

모든 라우팅 설정의 우선순위 — 한눈에

Provider 객체 머지 외에도 모델 선택, 화이트리스트, BYOK, 키 선택, 캐시 등 다양한 설정이 서로 다른 위치에서 결정됩니다.
각 설정이 어디서 정해지고, 충돌 시 무엇이 이기는지를 한눈에 정리했습니다.

모델 ID 형식

cafe24 LLM Router 는 모델 문자열 전체를 그대로 모델 ID 로 사용합니다. 모델 ID 에 / 가 포함돼 있어도(예: deepseek-ai/DeepSeek-V3.1) 그 전체가 하나의 모델 ID 이며,/ 앞부분을 provider 로 해석하지 않습니다. GET /api/v1/models 가 반환한 id 를 그대로model 필드에 넣으면 됩니다.

대표 모델 ID

같은 모델을 여러 프로바이더가 서로 다른 표기로 등재하기도 합니다 (예: MiniMaxAI/MiniMax-M3 와 minimax/minimax-m3). 이런 모델은 GET /api/v1/models 목록에 대표 모델 ID(author/slug, 소문자) 하나로만 실립니다. 프로바이더가 등재한 표기로 호출해도 같은 모델로 해석되므로 기존 호출은 그대로 동작합니다 (/ 가 있는 표기는 대소문자를 구분하지 않고, / 가 없는 표기는 등재된 그대로 일치해야 합니다). 어느 프로바이더가 어떤 표기로 등재했는지는 단건 조회 GET /api/v1/models/{model_id} 응답의 providers[].model_id 에 실립니다 (목록 응답에는 없습니다). Models 페이지의 모델 상세 프로바이더 목록에서도 같은 내용을 볼 수 있습니다.

Provider 선택은 provider 객체로

특정 provider 로 강제하거나 우선순위를 두려면 모델 prefix 가 아니라 위 Provider Routing 의provider 객체(order / only / ignore)를 사용합니다. 동일 모델을 여러 provider 가 제공할 때(예: deepseek-ai/DeepSeek-V3.1 은 deepinfra·siliconflow모두 제공) 그중 하나를 선택할 수 있습니다.

프로바이더가 등재한 표기로 부르는 것은 그 프로바이더를 지정하는 것이 아닙니다. / 가 들어간 표기는 대표 모델 그룹의 진입점이므로, 그 그룹을 제공하는 다른 프로바이더로 라우팅될 수 있습니다. 예를 들어 zai-org/GLM-5 로 불러도 glm-5 로 등재한 다른 프로바이더가 응답할 수 있습니다. 프로바이더를 고정하는 방법은 provider.only 뿐입니다.

존재하지 않는 모델

어느 프로바이더에도 등재되지 않은 모델 ID 를 호출하면 404 model_not_found 를 반환합니다. 이는 시맨틱 캐시 hit 으로도 우회되지 않습니다. 반대로 /api/v1/models 목록에 보이지 않더라도 대표 모델 ID 로 묶인 프로바이더별 등재 표기는 그대로 호출됩니다 (위 대표 모델 ID 참고).

Reserved Model ID

cafe24/auto 는 / 가 있지만 모델 ID 가 아니라 Auto Router 트리거입니다. 모델 매칭 대신 자동 선택 라우팅으로 동작합니다.

BYOK 모델 ID

BYOK(본인 키)로 호출할 때는 claude-sonnet-4-6 와 같은 형식의 prefix 없는 모델 ID 로만 호출 가능합니다. (anthropic/claude-sonnet-4-6 처럼 provider/ prefix 가 붙은 형식은 BYOK 경로에서 지원되지 않습니다.)

Fallback Chain

models 배열의 각 항목도 동일하게 모델 ID 전체로 지정합니다. 앞 모델이 실패하면 다음으로 전환됩니다.

Model Features

Model Suffix

모델 ID 뒤에 :suffix를 붙여 동작을 변경합니다.

Model Fallback

model 필드와 함께 models 배열로 순차 시도할 모델 체인을 지정합니다. 첫 모델이 실패하면 다음 모델로 자동 전환됩니다. model 필드는 필수이며, models만 단독 사용은 불가합니다.

Sticky Routing

동일 대화를 같은 프로바이더로 라우팅하여 KV 캐시를 활용합니다. Multi-turn 대화 시 자동 적용됩니다.

Presets

프리셋은 모델 + 프로바이더 라우팅 + 샘플링 파라미터를 하나의 설정으로 묶어 재사용하는 기능입니다. 수정 시 자동으로 버전 스냅샷이 저장됩니다.

프리셋 사용 (3가지 방법)

요청 파라미터가 프리셋 값을 오버라이드합니다. 프리셋 설정 페이지에서 UI로 생성하거나 API로 직접 관리합니다.

Semantic Cache

동일하거나 유사한 요청에 대해 캐시된 응답을 반환하여 비용을 절감하고 응답 속도를 높입니다.

우선순위

API Key OFF > 요청 OFF > API Key 설정 > 글로벌 기본값. API Key에서 OFF한 경우 요청에서 ON할 수 없습니다.

캐시 스코프

시맨틱 캐시는 대표 모델 ID 단위로 동작합니다. 같은 모델을 가리키는 표기는 모두 한 캐시를 공유합니다 — 대표 모델 ID 로 부르든(zai-org/glm-5), 프로바이더가 등재한 표기로 부르든 (glm-5) 같습니다. 어느 프로바이더가 응답했는지도 구분하지 않습니다.

단, provider 객체로 프로바이더를 지정한 요청은 그 프로바이더 전용 캐시를 씁니다. only · ignore · order 중 하나라도 있으면 지정으로 봅니다. 지정한 요청에는 다른 프로바이더가 만든 응답이 나가지 않으며, 지정 없는 요청의 캐시와도 섞이지 않습니다. 계정 설정(라우팅 설정)에 걸어 둔 only · ignore 도 같습니다 — 계정이 막아 둔 프로바이더의 응답이 캐시로 나가는 일은 없습니다.

대표 모델 ID 가 없는 모델(한 프로바이더만 등재한 모델 등)은 등재된 표기 단위로 동작합니다. 캐시를 아예 쓰지 않으려면 요청에 "cache": {"semantic": false} 를 넣으십시오.

모델 ID 와 캐시

• 유효한 모델 ID → 캐시 정상 hit
• 미등록 모델 ID (예: Qwen/Qwen3-NotExist) → 캐시 lookup 전 차단되어 404 model_not_found

즉 잘못된 모델 ID 호출이 캐시 hit 으로 silently 성공하는 일은 없습니다.

캐시 엔트리는 캐시 관리 페이지에서 조회/삭제할 수 있습니다.

Metadata

요청에 metadata를 포함하면 사용량을 팀, 프로젝트, 환경 등으로 분류하여 추적할 수 있습니다. 프로바이더에 전달되지 않으며 로그에만 저장됩니다.

사용 현황에서 metadata key-value 조합별 사용량을 집계할 수 있습니다.

Request/Response Body 저장

계정 단위 요청/응답 본문 저장 정책을 본인이 직접 토글합니다. default OFF — 디버깅이 필요할 때만 ON 으로 변경하세요. 본문 저장 OFF 상태에서는 시맨틱 캐시도 자동 비활성화됩니다.

Privacy Filter

LLM 호출 직전 요청 내용 중 민감정보(PII)만 식별해 마스킹 후 프로바이더로 전송하는 기능입니다. 본문 저장 정책과는 독립적으로 동작하지만, 마스터 스위치가 ON 이면 시맨틱 캐시는 자동 비활성화됩니다. 프라이버시 설정 페이지에서 룰을 관리합니다.

Base URL: https://llm-router.cafe24.com/api/v1

Models

Response — data[] 항목

목록 응답에는 단가와 프로바이더별 등재 표기가 실리지 않습니다. 둘 다 아래 단건 조회 또는 Models 페이지에서 확인하세요. cafe24/auto 는 프로바이더가 정해져 있지 않아 providers 와 model_type 이 없습니다.

단건 조회 — GET /api/v1/models/{model_id}

대표 모델 ID 로 물어도, 프로바이더가 등재한 표기로 물어도 같은 모델의 상세가 옵니다. 찾는 순서는 다음과 같습니다.

응답 id 는 대표 모델 ID 입니다 (대표 ID 가 없는 모델은 등재된 표기 그대로). 나머지 필드는 목록 항목과 같고 providers 배열만 프로바이더별 상세로 넓어집니다. 같은 프로바이더가 두 표기로 등재했다면 providers 에 두 번 나오며 model_id 로 구분합니다.

값이 없는 키는 아예 나오지 않습니다 — 예를 들어 캐시 단가가 없는 모델에는 cache_read 가 없습니다. 컨텍스트 길이 구간에 따라 단가가 달라지는 모델은 기본 구간 값만 실리므로, 구간별 요금은 Models 페이지에서 확인하세요. 하나로 좁혀지지 않는 모델 ID 로 조회하면 404 가 옵니다.

Chat Completions

응답의 extra_fields.routing_info 에 실제로 요청을 처리한 프로바이더와 모델이 실려 옵니다 (provider, resolved_model_used, latency). cafe24/auto 나 Preset 처럼 모델이 런타임에 정해지는 경우 어디로 나갔는지 확인할 수 있습니다. 이 필드는 Embeddings · Rerank · Speech to Text 응답에도 함께 옵니다.

Responses

지원 범위가 좁습니다. Responses 규격을 구현한 프로바이더의 OpenAI 계열 모델에서만 동작합니다. 그 밖의 모델은 아래처럼 거절되므로, 범용으로 쓸 경로가 필요하면 Chat Completions 를 쓰세요.

Request Body

Response

Chat Completions 와 구조가 다릅니다 — 본문은 choices[].message.content 가 아니라 output[].content[].text 에 있고, 토큰 이름도 input_tokens · output_tokens 입니다. SDK 를 쓰면 response.output_text 로 바로 꺼냅니다. 끝까지 못 간 응답은 status 가 incomplete 이고 incomplete_details.reason 에 사유(예: max_output_tokens)가 실립니다. 이때도 소비한 토큰은 과금됩니다.

Embeddings

Response

data 는 입력 순서대로 오고 index 로도 확인할 수 있습니다.벡터 차원은 모델마다 다릅니다 (실측: google/embeddinggemma-300m 은 768). 저장소 스키마를 잡기 전에 실제 응답 길이를 확인하세요. 과금은 입력 토큰 기준이며 출력 벡터 크기와 무관합니다.

Images

Request Body

Response

b64_json 과 url 중 무엇이 올지는 모델이 정합니다 — 실측에서 stabilityai/sdxl-turbo · google/nano-banana-2-lite 는 b64_json, 일부 편집 모델은 만료되는 임시 url 을 줍니다. 두 키를 모두 확인하고, url 은 받은 즉시 내려받아 보관하세요. base64 는 선두 바이트로 실제 포맷을 판별하는 편이 안전합니다 (/9j/ = JPEG, iVBORw0 = PNG).

response_format 은 보내지 마세요. 반환 형태는 위처럼 모델이 정하며, 값을 지정하면 프로바이더가 거절할 수 있습니다 — 실측에서 stabilityai/sdxl-turbo 에 response_format: "url" 을 주면 422 가 납니다.

이미지 응답에는 usage 가 없습니다 — 현재 제공하는 이미지 모델은 전부 장당 과금이라 토큰 집계가 없습니다. 비용은 Activity 의 usage_krw_micro 로 확인하세요 (그 행의 토큰 값은 0 입니다).

모든 이미지 모델이 편집을 지원하지는 않습니다. 지원하지 않는 모델로 /images/edits 를 호출하면 프로바이더가 404 를 돌려줍니다. 편집 입력이 2장 이상이면 multipart 파일 필드명이 image[] 가 됩니다 (1장이면 image).

Rerank

벡터 검색으로 넓게 뽑은 뒤 이 API 로 좁히면 LLM 에 넣는 문서 수를 줄일 수 있습니다.

Response

results 는 관련도 내림차순이고 index 는 보낸 documents 의 원본 위치입니다. return_documents 를 주지 않으면 document.text 가 빈 문자열로 옵니다 — 키 자체는 오므로, 원문이 필요하면 index 로 되찾거나 return_documents: true 를 주세요. 과금은 질의와 문서를 합한 입력 토큰 기준입니다.

Text to Speech

응답 본문이 원시 오디오 바이트라 파일로 그대로 저장하거나 플레이어에 바로 넘기면 됩니다 — .json() 으로 파싱하면 깨집니다.

응답

본문은 오디오 바이트이고 포맷은 Content-Type 으로 알려 줍니다. 추적용 X-Request-ID 헤더도 함께 옵니다.

과금

• 토큰이 아니라 input 의 문자 수로 과금됩니다. 한글 1자와 영문 1자는 같은 1자입니다.
• 생성된 오디오 길이·파일 크기는 과금과 무관합니다 — speed 를 올려 짧게 만들어도 비용은 그대로입니다.
• Activity 에서 이 호출의 토큰은 0 으로 기록됩니다. 비용은 usage_krw_micro 로 보세요.

Speech to Text

JSON 이 아니라 multipart/form-data 로 보내야 하며, 파일은 26 MiB 까지 받습니다. 초과하면 요청이 거절됩니다.

Response

과금은 오디오 길이(초) 기준이며 인식된 글자 수와 무관합니다. TTS 와 마찬가지로 Activity 의 토큰 값은 0 이고 비용은 usage_krw_micro 에 실립니다.

System One NEW

분류·배정·필터처럼 답의 형식이 정해진 판단에 씁니다. 질문 여러 개를 한 요청에 보내면 답도 한 응답에 모두 옵니다.

TypeSafe 의 System One API 규격을 따릅니다. 게이트웨이는 인증·라우팅·과금만 하고, state·questions 와 응답 본문은 바꾸지 않고 전달합니다. OpenAI 규격이 아니므로 OpenAI SDK 로는 호출할 수 없습니다. HTTP 로 직접 호출하거나 TypeSafe 공식 SDK 를 쓰세요.

질문 정의

모든 질문에 type 과 instructions(질문 문장)를 씁니다. criteria 는 유형마다 형식이 다릅니다.

질문 정의의 세부 형식은 게이트웨이가 아니라 프로바이더가 검사합니다. 형식이 틀리면 400(provider_error)이 오고, message 에 프로바이더의 오류 문구가 그대로 담깁니다.

예시

TypeSafe SDK 로 호출할 때

응답

answers 의 키는 요청한 질문 이름과 같고, 답마다 type 이 함께 옵니다. 아래는 위 curl 요청의 실제 응답입니다 (dev 실측). 확률 값은 같은 요청이어도 호출마다 조금 다를 수 있습니다 (실측: 같은 요청에서 score 0.42 / 0.40). 응답의 model 에는 요청한 대표 모델 ID 가 아니라 프로바이더에 등록된 이름(jev-1.13.0)이 옵니다.

스트리밍은 없습니다. 답이 모두 나온 뒤 한 번에 응답합니다.

오류

과금

• 응답 usage 의 input_tokens·output_tokens 에 모델 단가를 곱합니다. 단가는 Models 페이지에서 확인하세요.
• state 가 길수록 입력 토큰이 늘어납니다. 판단에 필요한 부분만 보내세요.
• 질문은 한 요청에 모으세요. 같은 state 를 요청마다 다시 보내면 그만큼 입력 토큰을 다시 냅니다.

여기부터는 LLM 을 호출하는 API 가 아니라, 발급받은 키의 사용량을 조회하고 키를 관리하는 API 입니다. 사용량은 같은 데이터를 두 가지 형태(Usage·Activity)로 제공하며, 인증은 동일하게 API Key 를 씁니다.

Usage

날짜는 KST 기준이며 to 는 해당일을 포함합니다.

Query Parameters

Response

주의

• 조회 범위는 최근 90일입니다. 더 이전을 요청해도 오류가 아니라 자동으로 조정되며, data_complete: false 와 available_from 으로 알려줍니다.
• model 과 model_requested 가 다를 수 있습니다. cafe24/auto 나 별칭으로 호출하면 실제 선택된 모델이 model 에 들어갑니다.
• 과금 기준은 KRW(usage_krw_micro)입니다. usage_usd 는 모델 USD 단가로 산출한 참고값이며, 단가 미등록 모델이 있으면 usd_complete: false 로 표시됩니다.
• 조회 대상은 기본적으로 요청에 사용한 키 자신입니다. 예외로 관리 키로 호출하면 내 계정 전체 사용량이 합산되어 반환되고, api_key_id 파라미터로 소유 키 하나로 좁힐 수 있습니다 (비소유 키 지정은 404). 다른 사용자의 사용량은 어떤 경우에도 조회할 수 없습니다.
• 요청 한도는 키당 분당 10회 · 하루 1,000회이며, /usage·/activity·/keys 호출을 합산해 셉니다 (키 생성·수정·삭제 같은 쓰기 요청 포함). 초과하면 429 를 반환합니다. LLM 호출 한도와는 별도 카운터입니다.
• 위 표에 없는 쿼리 파라미터를 보내면 400 입니다 (지원하지 않는 쿼리 파라미터: …, 허용 목록 포함). 오타나 미지원 옵션이 조용히 무시된 채 다른 구간이 집계되는 일을 막기 위한 동작입니다.

Activity

표준 activity 스키마와 필드 호환이라 기존 사용량 조회 클라이언트를 그대로 붙일 수 있습니다. 조회 대상은 기본적으로 인증에 쓴 키 자신입니다. 관리 키로 호출하면 내 계정 전체 사용량이 합산되고, api_key_id 로 소유 키 하나로 좁힐 수 있습니다 (비소유 키 지정은 404).

Query Parameters

셋 다 생략하면 최근 30일입니다. 보존 기간은 90일이며, 더 긴 구간이 필요하면 응답의 available_from 을 보고 from 을 지정하세요. 보존 기간을 벗어난 구간은 자동으로 잘리고 warning 으로 알립니다. 요청 구간 전체가 조회 범위 밖이면 400 입니다. 위 표에 없는 쿼리 파라미터를 보내도 400 입니다 (지원하지 않는 쿼리 파라미터: …, 허용 목록 포함) — 오타나 미지원 옵션이 조용히 무시된 채 다른 구간이 집계되는 일을 막기 위한 동작입니다.

Response — data[] 항목

metadata 별 분해

요청 body 에 metadata 를 실어 보냈다면(Metadata 참조),group_by=metadata:<key> 로 그 키의 값별 사용량을 나눠 볼 수 있습니다. 기존 축(일자·모델·프로바이더)은 그대로 두고 한 축이 더해지는 형태입니다.

group_by 를 주지 않으면 응답 구조가 전혀 달라지지 않습니다. 기존 호환 클라이언트를 쓰고 있다면 이 파라미터를 보내지 않는 한 영향이 없습니다. metadata 없이 보낸 요청도 누락되지 않고 metadata_value 가 빈 문자열인 행에 모이므로, 분해 전후의 합계는 항상 같습니다.

Response — 최상위 필드

주의

금액은 usage_krw_micro 를 쓰세요. usage(USD)는 조회 시점의 단가로 환산한 참고값이라, 단가가 개정되면 같은 과거 구간을 다시 조회했을 때 값이 달라집니다.usage_krw_micro 는 호출 시점에 확정된 청구액이라 변하지 않습니다.

요청 한도는 키당 분당 10회 · 하루 1,000회이며, /usage·/activity·/keys 호출을 합산해 셉니다 (키 생성·수정·삭제 같은 쓰기 요청 포함). 초과하면 429 를 반환합니다. (LLM 호출 한도와는 별도 카운터입니다.)

Management API

관리 키(management key)로 API 키를 프로그래밍 방식으로 생성·조회·수정·삭제합니다. CI/온보딩 자동화에서 키를 발급하고, 위의 Usage 로 사용량을 함께 조회하는 식으로 씁니다. 관리 키는 콘솔 > 관리 키에서만 발급됩니다.

생성 Body

키 객체

주의

• 키 원문은 생성 응답에서만 1회 제공됩니다. 다시 조회할 수 없습니다.
• 생성되는 키는 항상 LLM 호출용(inference) 입니다 — 관리 키를 API 로 복제할 수는 없습니다 (발급은 콘솔에서만).
• 수정(POST)에서 한도를 무제한으로 되돌리려면 clear_limit: true, 리셋 주기 해제는 clear_limit_reset: true 를 보내세요 (null 은 "미변경").
• 앞단 네트워크가 PATCH 메서드를 405 로 차단합니다. 키 수정은 POST /api/v1/keys/{key_id} 로 보내세요 (PATCH 와 같은 Body·응답. PATCH 로 보내면 405 입니다).
• 관리 키로 수행한 모든 생성·수정·삭제는 감사 기록으로 남고, 콘솔 > 관리 키의 활동 이력에 표시됩니다.
• 관리 키로 Usage·Activity 를 호출하면 내 계정 전체 사용량 합산이 반환됩니다. 특정 키만 보려면 api_key_id 파라미터로 좁히세요. LLM 호출용 키로 호출하면 그 키 자신의 사용량만 나옵니다.
• 요청 한도는 키당 분당 10회 · 하루 1,000회이며, /usage·/activity·/keys 호출을 합산해 셉니다 (키 생성·수정·삭제 같은 쓰기 요청 포함). 초과하면 429 를 반환합니다.
• 요청 body 에 정의되지 않은 필드가 있으면 400 (Extra inputs are not permitted) 입니다. /usage·/activity 도 표에 없는 쿼리 파라미터를 400 으로 거부합니다 — 오타·미지원 옵션이 조용히 무시되지 않도록 의도된 동작입니다.

Request Parameters

POST /api/v1/chat/completions 요청 body 파라미터. 다른 엔드포인트도 공통 파라미터를 지원합니다.

Required

Sampling

Routing

Tracking

OpenAI 공식 SDK를 그대로 사용합니다. base_url만 LLM Router로 변경하면 됩니다. Anthropic·Google 등 다른 프로바이더의 모델도 GET /api/v1/models 가 반환한 모델 ID (예: anthropic/claude-opus-4-8)를 model 에 넣어 같은 SDK 로 호출합니다.

Python (OpenAI SDK)

OpenAI, Google, DeepSeek 등 OpenAI 호환 모델에 사용합니다.

Node.js (OpenAI SDK)

curl

모든 엔드포인트를 curl로 직접 호출할 수 있습니다.