요청 파라미터
받는 것, 무시하는 것, 거절하는 것
POST /chat/completions 와 POST /completions 의 본문에 들어가는 파라미터는 세 무리로 나뉩니다.
- 게이트웨이가 먹는 것 — 우리가 읽고 소비하며 업스트림으로 넘기지 않습니다. 라우팅 파라미터가 여기 속합니다.
- 우리가 채워 넣는 것 — 여러분이 무엇을 보내든 우리 값으로 덮어씁니다.
- 그대로 흘려보내는 것 — 나머지 전부. 샘플링 파라미터와 툴 정의가 여기 속합니다.
이 구분을 알아야 "왜 이 파라미터는 효과가 없지?"라는 질문에 스스로 답할 수 있습니다.
1. 게이트웨이가 먹는 파라미터
modelstring호출할 모델 id. 예: google/gemma-4-26b-a4b. 생략하면 서비스 기본 모델을 씁니다. 모르는 id 면 400 model_not_found 입니다.
modelsstring[]후보 체인. 앞에서부터 순서대로 시도하고, 응답을 시작한 후보에서 멈춥니다. 배열이 비어 있지 않으면 model 보다 우선합니다.
배열 안의 모르는 id 는 조용히 빠집니다 — "이 중에 되는 걸로" 라는 뜻이기 때문입니다. 전부 모르는 id 일 때만 400 model_not_found 입니다. 단일 model 은 그렇지 않고 곧바로 400 입니다.
자세한 규칙은 모델 폴백에 있습니다.
providerobjectprovider 선택 규칙. 아래 순서로 적용합니다.
| 필드 | 타입 | 동작 |
|---|---|---|
order | string[] | 그 provider slug 순서로 체인을 재정렬합니다. 목록에 없는 후보는 뒤로 갑니다 |
only | string[] | 그 slug 만 남깁니다 |
ignore | string[] | 그 slug 를 뺍니다 |
sort | "price" | "throughput" | "latency" | 판매 단가 오름차순 / 처리량 내림차순 / 지연 오름차순 |
allow_fallbacks | boolean | false 면 체인을 첫 후보 하나로 자릅니다 |
max_price | {prompt?, completion?} | USD/토큰 상한. 현재 환율을 곱해 우리 KRW 판매 단가와 비교합니다 |
require_parameters | boolean | true 면 요청 본문에 실린 파라미터를 전부 지원하는 후보만 남깁니다 |
data_collection | "allow" | "deny" | 메타를 아는 후보에만 적용합니다 |
zdr | boolean | 위와 같습니다 |
quantizations | string[] | 양자화 방식이 알려진 후보만 걸러냅니다 |
필터링 결과 후보가 하나도 남지 않으면 404 no_endpoints_found 입니다. 메타 값을 모르는 후보는 통과시킵니다 — 모른다는 이유로 로컬 슬롯이 통째로 사라지지 않게 하려는 것입니다. Provider 라우팅을 보세요.
routestring"fallback" 을 받습니다. openrouter 에서 deprecated 된 값이라 동작은 기본값과 같지만, 400 을 내지 않고 조용히 받아줍니다. 기존 코드가 이 값을 보내고 있어도 고칠 필요가 없습니다.
transformsstring[]받되 무시합니다. 메시지 변환은 구현하지 않습니다. 오류를 내지 않는 것은 openrouter 코드가 그대로 돌아가야 하기 때문이고, 아무 일도 하지 않는다는 사실은 여기 적어 둡니다.
pluginsobject[]받되 무시합니다. 플러그인(PDF 파싱 등)은 구현하지 않습니다.
promptstring | string[]/completions 전용입니다. 문자열 배열이면 \n 으로 이어 붙여 messages:[{role:"user"}] 한 건으로 바꿉니다. /chat/completions 에 보내면 그냥 버려집니다.
2. 우리가 채워 넣는 파라미터
messagesobject[]필수/chat/completions 필수입니다. 배열이 아니거나 비어 있으면 400 invalid_request 입니다. 각 항목에 문자열 role 이 있어야 하고, 없으면 역시 400 입니다. content 는 검사하지 않고 그대로 업스트림에 넘깁니다.
streamboolean기본 false. true 일 때만 SSE 로 응답합니다. 정확히 불리언 true 여야 합니다 — 문자열 "true" 는 비스트리밍으로 처리됩니다.
stream_optionsobject여러분이 보낸 값은 버려지고 스트리밍일 때 항상 {"include_usage": true} 로 덮어씁니다. 이 옵션이 없으면 업스트림이 usage 를 안 주고, 그러면 마지막 usage 청크에 비용을 실을 수 없습니다(스트리밍).
3. 그대로 흘려보내는 파라미터
위 두 무리에 들지 않은 모든 필드는 손대지 않고 업스트림에 전달합니다. 우리가 화이트리스트를 두지 않기 때문에, 모델이 아는 파라미터는 우리가 몰라도 통합니다.
| 파라미터 | 타입 | 통상 기본값 |
|---|---|---|
max_tokens | integer | 모델 기본 |
temperature | float, 0.0–2.0 | 1.0 |
top_p | float, 0.0–1.0 | 1.0 |
top_k | integer, 0 이상 | 0 (끔) |
frequency_penalty | float, −2.0–2.0 | 0.0 |
presence_penalty | float, −2.0–2.0 | 0.0 |
repetition_penalty | float, 0.0–2.0 | 1.0 |
seed | integer | 없음 |
stop | string 또는 string[] | 없음 |
logit_bias | {[token_id]: -100…100} | 없음 |
response_format | object | 없음 |
tools, tool_choice | object[] / string·object | 없음 |
모델이 무엇을 지원하는지 확인하기
각 모델의 supported_parameters 는 GET /models 응답에 있습니다. 필터로도 쓸 수 있습니다.
curl "https://openrouter.myip.co.kr/api/v1/models?supported_parameters=tools"우리 로컬 GPU 모델의 값은 이렇습니다.
| 모델 | supported_parameters |
|---|---|
google/gemma-4-26b-a4b | max_tokens, temperature, top_p, top_k, stop, seed, frequency_penalty, presence_penalty, repetition_penalty, logit_bias, response_format, tools, tool_choice |
lgai/exaone-4.0-32b | 위와 같고 tools·tool_choice 는 없습니다 |
지원 목록에 없는 파라미터를 보내도 우리가 막지는 않습니다. 업스트림이 무시하거나 오류를 낼 뿐입니다. 확실히 거르고 싶다면 provider.require_parameters: true 를 쓰세요.
전체 예제
curl https://openrouter.myip.co.kr/api/v1/chat/completions \
-H "Authorization: Bearer $MYIP_API_KEY" \
-H "Content-Type: application/json" \
-H "HTTP-Referer: https://myapp.example" \
-H "X-Title: My App" \
-d '{
"models": ["google/gemma-4-26b-a4b", "lgai/exaone-4.0-32b"],
"provider": { "sort": "price", "allow_fallbacks": true },
"messages": [
{"role": "system", "content": "너는 간결한 한국어 비서다."},
{"role": "user", "content": "TCP 3-way handshake 를 세 문장으로 설명해줘"}
],
"max_tokens": 300,
"temperature": 0.3,
"top_p": 0.9,
"seed": 42,
"stop": ["\n\n끝"]
}'파라미터 때문에 나는 오류
| 상태 | error_type | 언제 |
|---|---|---|
| 400 | invalid_request | 본문이 JSON 객체가 아님, messages 누락·빈 배열, role 없는 메시지, /completions 의 prompt 가 문자열도 문자열 배열도 아님 |
| 400 | model_not_found | model 이 모르는 id, 또는 models[] 가 전부 모르는 id |
| 404 | no_endpoints_found | provider 필터가 후보를 전부 지움 |
나머지 오류는 오류와 디버깅에 있습니다.
마지막 수정 2026. 9. 5.