Chat completions

대화에 대한 모델 응답을 생성합니다. 요청과 응답은 OpenAI Chat Completions 형식을 따릅니다. 아래 각 파라미터에는 현재 게이트웨이가 그 값을 어떻게 처리하는지 표시했습니다.

POST/chat/completions

URL

https://api.bricksum.com/v1/chat/completions

요청

bash

curl https://api.bricksum.com/v1/chat/completions \
  -H "Authorization: Bearer $KILN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-32b",
    "messages": [
      {"role": "system", "content": "Answer briefly."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 800
  }'

python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.bricksum.com/v1",
    api_key=os.environ["KILN_API_KEY"],
)

resp = client.chat.completions.create(
    model="qwen3-32b",
    messages=[
        {"role": "system", "content": "Answer briefly."},
        {"role": "user", "content": "Hello!"},
    ],
    max_tokens=800,
)
print(resp.choices[0].message.content)
print(resp.usage)

javascript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.bricksum.com/v1",
  apiKey: process.env.KILN_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "qwen3-32b",
  messages: [
    { role: "system", content: "Answer briefly." },
    { role: "user", content: "Hello!" },
  ],
  max_tokens: 800,
});
console.log(resp.choices[0].message.content);
console.log(resp.usage);

응답

200 OK

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "qwen3-32b",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello! How can I help?" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "cost": 0.000001155
  }
}

200 OK · text/event-stream

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"qwen3-32b","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"qwen3-32b","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"qwen3-32b","choices":[],"usage":{"prompt_tokens":9,"completion_tokens":12,"total_tokens":21,"cost":0.000001155}}

data: [DONE]

400 Bad Request

{
  "error": {
    "message": "Invalid 'messages': the array must contain at least one message.",
    "type": "invalid_request_error",
    "param": "messages",
    "code": "empty_array"
  }
}

이 예시의 토큰 수와 cost는 gpt-oss-120b에서 측정한 예시 값이며, qwen3-32b의 값이 아닙니다.

인증

게이트웨이가 처리하는 엔드포인트의 인증 방식은 모두 같으며, API 레퍼런스 페이지에서 설명합니다.

요청 본문

지원 상태

지원: 게이트웨이가 처리하거나, 공개된 실측에서 동작이 확인된 항목입니다.
전달만 함: 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
무시됨: 200으로 수락되지만 적용되지 않습니다. 응답의 나머지는 정상입니다.
미지원: 에러로 거부되거나, 설명에 적힌 모델에서 동작하지 않습니다.

공통 파라미터

아래 파라미터의 정의는 API 레퍼런스 페이지에 한 번만 정리했습니다. 여기에는 이 엔드포인트에서 다른 점만 적었습니다.

modelstring필수지원
공통 정의와 같습니다.
전체 정의 보기
messagesarray필수지원
배열이 비어 있거나 없으면 400(empty_array)으로 거부됩니다. 메시지는 role과 content로 이루어지며, 형태는 아래와 같습니다.
전체 정의 보기
system 메시지
- rolestring필수지원
  "system"로 지정합니다.
  허용 값
  system
- contentstring필수지원
  대화 전체에 적용할 지시문입니다.
user 메시지
- rolestring필수지원
  "user"로 지정합니다.
  허용 값
  user
- contentstring | array필수지원
  텍스트 또는 content 파트 배열입니다. 게이트웨이는 파트 배열을 변경 없이 전달합니다. 이미지 파트(image_url)는 이미지 입력을 받는 모델에서만 동작합니다. 모델 페이지를 확인하세요.
assistant 메시지
- rolestring필수지원
  "assistant"로 지정합니다.
  허용 값
  assistant
- contentstring | null지원
  이전 모델 응답입니다. 응답이 툴 호출이었다면 null일 수 있습니다.
- tool_callsarray지원
  모델이 반환한 tool_calls 배열입니다. 대응하는 tool 메시지 앞에 변경 없이 다시 보냅니다.
tool 메시지
- rolestring필수지원
  "tool"로 지정합니다.
  허용 값
  tool
- tool_call_idstring필수지원
  이 결과가 응답하는 툴 호출의 id입니다.
- contentstring필수지원
  툴을 실행한 결과입니다. 보통 JSON 문자열입니다.
max_tokensinteger지원
보낸 값 그대로 모델 서버로 전달됩니다. 이 상한에서 생성이 멈추면(finish_reason: "length") 비스트리밍 응답의 content가 비어 있을 수 있습니다.
전체 정의 보기
streamboolean지원
게이트웨이는 문자열 "true"와 숫자 1도 true로 읽으며, 전달하기 전에 이 필드를 boolean으로 다시 씁니다.
기본값
false
전체 정의 보기
toolsarray지원
OpenAI function 정의 형식으로 보냅니다.
전체 정의 보기
function 툴
- typestring필수지원
  "function"으로 지정합니다.
  허용 값
  function
- function.namestring필수지원
  모델이 tool_calls에서 사용하는 이름입니다.
- function.descriptionstring필수지원
  함수가 하는 일입니다. description이 없는 함수는 400으로 거부됩니다.
- function.parametersobject지원
  함수 인자의 JSON Schema입니다.
tool_choice= "auto"string지원
문자열 "auto"로 보냅니다.
전체 정의 보기
tool_choice= "required" | {"type": "function", ...}string | object미지원
강제 툴 선택입니다. "required" 또는 함수 이름을 지정해 보냅니다. qwen3-32b에서는 강제 툴 선택이 명확한 에러 없이 실패합니다(2026-09-26 실측). tool_choice를 "required"로 보내면 본문이 평문 "Internal Server Error"인 HTTP 500이 오고, 함수를 지정하면 arguments가 빈 200(finish_reason "stop")이 옵니다. 둘 다 4xx가 아니므로 재시도로 해결되지 않습니다. tool_choice는 "auto"만 보내세요.
전체 정의 보기

이 엔드포인트에만 있는 파라미터

stream_optionsobject지원
스트리밍 응답 옵션입니다. stream: true와 함께 보낼 때만 사용하세요.
usage 옵션
- include_usageboolean지원
  true이면 스트림 끝에 choices가 비어 있고 usage 객체에 토큰 수와 cost가 담긴 청크가 하나 더 옵니다. 게이트웨이는 토큰 계측을 위해 모든 스트리밍 요청에 이 값을 설정하며, 요청하지 않은 경우 usage 청크를 제거합니다.
  기본값
  false
parallel_tool_callsboolean미지원
모델 페이지에서 병렬 툴 호출이 지원으로 표시된 모델에서만 적용되며, qwen3-32b는 해당하지 않습니다. gpt-oss-120b 실측에서는 요청이 200으로 수락되고, 모델이 응답마다 툴을 최대 하나만 호출했습니다. qwen3-32b에서는 parallel_tool_calls 설정이 적용되지 않습니다. 이는 응답에 툴 호출이 하나만 온다는 뜻이 아닙니다. parallel_tool_calls: false를 보내도 한 응답에 툴 호출이 여러 건 올 수 있습니다. tool_calls의 모든 항목에 각각 tool 메시지로 답하세요.
reasoning_effortstring지원
보낸 값 그대로 모델에 전달됩니다. gpt-oss-120b는 low, medium, high를 받으며, 다른 모델이 이 값을 따르는지는 공개되지 않았습니다. 값이 높을수록 reasoning 토큰을 더 쓰므로 지연 시간과 출력 토큰이 늘어납니다.
허용 값
low, medium, high
temperaturenumber전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
범위
0–2
top_pnumber전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
범위
0–1
ninteger전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
seedinteger전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
presence_penaltynumber전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
범위
-2–2
frequency_penaltynumber전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
범위
-2–2
stopstring | array무시됨
수락되지만 적용되지 않습니다. stop 문자열 이후에도 생성이 계속됩니다.
response_formatobject미지원
json_object와 json_schema는 아직 동작하지 않습니다. 요청은 200으로 수락되지만 content가 비어 반환됩니다. JSON이 필요하면 프롬프트에서 JSON으로만 답하도록 지시하고, 클라이언트에서 결과를 파싱해 검증하세요.
ignore_eosboolean미지원
gpt-oss 모델에서 true를 보내면 모델에 도달하기 전에 400(unsupported_parameter)으로 거부됩니다. 다른 모델에서는 모델 서버로 전달됩니다.

여기에 없는 OpenAI chat 파라미터도 같은 방식으로 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않은 항목입니다.

응답 본문

필드	타입	설명
id	string	chat completion의 ID입니다.
object	string	"chat.completion"입니다.
created	integer	생성 시각(Unix 초)입니다.
model	string	응답을 생성한 모델 ID입니다.
choices[].index	integer	choice의 순번입니다.
choices[].message.role	string	"assistant"입니다.
choices[].message.content	string \| null	생성된 텍스트입니다. finish_reason이 "length"이면 비어 있을 수 있고, 응답이 툴 호출이면 null일 수 있습니다.
choices[].message.tool_calls	array	모델이 실행을 요청한 툴 호출입니다. id, type, function.name과 JSON 문자열인 function.arguments를 담습니다.
choices[].finish_reason	string	"stop", "length"(max_tokens에서 잘림), "tool_calls" 중 하나입니다.
usage.prompt_tokens	integer	입력 토큰 수입니다.
usage.completion_tokens	integer	출력 토큰 수입니다. reasoning 토큰을 포함합니다.
usage.total_tokens	integer	입력과 출력 토큰의 합계입니다.
usage.prompt_tokens_details.cached_tokens	integer	프리픽스 캐시에서 처리된 입력 토큰 수입니다. 모델 서버가 보고할 때만 포함됩니다.
usage.cost	number	이 요청으로 크레딧에서 차감되는 금액(USD)입니다. 게이트웨이가 추가합니다.
X-Neocloud-Generation-Id	header	이 요청의 usage 이벤트 ID를 담은 응답 헤더입니다. 로그와 함께 저장하세요.

스트림 청크

stream: true이면 각 data: 줄에 아래 필드를 가진 청크가 하나씩 담깁니다. keepalive 주석, data: [DONE], 연결 끊김은 스트리밍 페이지에서 설명합니다.

필드	타입	설명
object	string	"chat.completion.chunk"입니다.
choices[].delta.content	string	이 청크에서 새로 생성된 텍스트입니다.
choices[].delta.tool_calls	array	툴 호출 조각입니다. function.arguments를 index별로 이어 붙이세요.
choices[].finish_reason	string \| null	마지막 content 청크 전까지 null이며, 마지막 청크에 종료 사유가 담깁니다.
usage	object	stream_options.include_usage가 true일 때만 마지막 청크에 포함됩니다. 이 청크의 choices 배열은 비어 있습니다.
usage.cost	number	이 요청으로 크레딧에서 차감되는 금액(USD)입니다. 게이트웨이가 usage 청크에 추가합니다.

에러

메시지 문구가 아니라 HTTP 상태와 error.code로 분기하세요. error.code 칸이 비어 있으면 본문에 code가 없다는 뜻입니다. 전체 상태 코드는 에러 페이지에 있습니다.

상태 · error.code	원인	조치
400empty_array	messages가 비어 있거나 없습니다.	메시지를 하나 이상 보내세요.
400unsupported_parameter	gpt-oss 모델에 ignore_eos: true를 보냈습니다.	ignore_eos를 제거하세요.
400	모델 서버가 요청을 거부했습니다. JSON 형식 에러, 잘못된 파라미터, description이 없는 함수, 모델 페이지에 나오는 모델별 컨텍스트 길이를 넘는 컨텍스트가 원인입니다.	요청 본문을 수정하세요. 그대로 재시도하지 마세요.
404model_not_found	모델 ID가 카탈로그에 없습니다.	GET /models로 ID를 확인하세요.
429rate_limit_exceeded	조직에서 이미 8개의 요청이 처리 중입니다. 레이트 리밋 헤더는 포함되지 않습니다.	지수 백오프로 재시도하세요.
502	모델 백엔드가 에러를 반환했거나 연결할 수 없습니다. 본문은 일반 텍스트입니다.	지수 백오프로 재시도하세요.
503	서비스가 점검 중이거나 사용 가능한 모델 백엔드가 없습니다.	점검 중에는 Retry-After 시각까지 기다리세요. 그 밖에는 지수 백오프로 재시도하세요.

401, 402, 403, 429는 요청이 이 엔드포인트에 도달하기 전에 게이트웨이가 반환합니다. 이 에러들은 API 레퍼런스 페이지에 한 번만 정리했습니다.

제한

컨텍스트 길이, 요청 본문 크기, 타임아웃, 조직별 레이트 리밋도 여기에 그대로 적용되며, API 레퍼런스 페이지에 한 번만 정리했습니다.

429의 헤더와 재시도 방법은 레이트 리밋 페이지에 있습니다.