Completions

프롬프트에 이어지는 텍스트를 생성합니다. 요청과 응답은 OpenAI Completions 형식을 따릅니다. 게이트웨이는 chat 요청과 같은 방식으로 계측하고 본문을 모델 서버로 전달합니다. 대화와 툴 호출에는 Chat completions를 사용하세요.

POST/completions

URL

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

요청

bash

curl https://api.bricksum.com/v1/completions \
  -H "Authorization: Bearer $KILN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-32b",
    "prompt": "The capital of France is",
    "max_tokens": 32
  }'

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.completions.create(
    model="qwen3-32b",
    prompt="The capital of France is",
    max_tokens=32,
)
print(resp.choices[0].text)
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.completions.create({
  model: "qwen3-32b",
  prompt: "The capital of France is",
  max_tokens: 32,
});
console.log(resp.choices[0].text);
console.log(resp.usage);

응답

200 OK

{
  "id": "cmpl-...",
  "object": "text_completion",
  "created": 1710000000,
  "model": "qwen3-32b",
  "choices": [
    { "index": 0, "text": " Paris, a city on the Seine.", "finish_reason": "stop" }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 7,
    "total_tokens": 12,
    "cost": 0.000000665
  }
}

200 OK · text/event-stream

data: {"id":"cmpl-...","object":"text_completion","created":1710000000,"model":"qwen3-32b","choices":[{"index":0,"text":" Paris","finish_reason":null}]}

data: {"id":"cmpl-...","object":"text_completion","created":1710000000,"model":"qwen3-32b","choices":[{"index":0,"text":"","finish_reason":"stop"}]}

data: {"id":"cmpl-...","object":"text_completion","created":1710000000,"model":"qwen3-32b","choices":[],"usage":{"prompt_tokens":5,"completion_tokens":7,"total_tokens":12,"cost":0.000000665}}

data: [DONE]

404 Not Found

{
  "error": {
    "message": "The model `not-a-model` does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

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

인증

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

요청 본문

지원 상태

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

공통 파라미터

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

modelstring필수지원
공통 정의와 같습니다.
전체 정의 보기
max_tokensinteger전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
전체 정의 보기
streamboolean지원
게이트웨이는 문자열 "true"와 숫자 1도 true로 읽으며, 전달하기 전에 이 필드를 boolean으로 다시 씁니다. usage 청크를 받으려면 아래의 stream_options를 사용하세요.
기본값
false
전체 정의 보기

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

promptstring | array필수지원
이어서 생성할 텍스트입니다. 게이트웨이는 값을 변경 없이 전달하며 검증하지 않습니다.
stream_optionsobject지원
스트리밍 응답 옵션입니다. stream: true와 함께 보낼 때만 사용하세요.
usage 옵션
- include_usageboolean지원
  true이면 스트림 끝에 choices가 비어 있고 usage 객체에 토큰 수와 cost가 담긴 청크가 하나 더 옵니다. 게이트웨이는 토큰 계측을 위해 모든 스트리밍 요청에 이 값을 설정하며, 요청하지 않은 경우 usage 청크를 제거합니다.
  기본값
  false
temperaturenumber전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
범위
0–2
top_pnumber전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
범위
0–1
ninteger전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
seedinteger전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
stopstring | array전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
presence_penaltynumber전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
범위
-2–2
frequency_penaltynumber전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
범위
-2–2
logprobsinteger전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
echoboolean전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다.
ignore_eosboolean전달만 함
모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. gpt-oss 모델에 대한 400(unsupported_parameter) 검사는 /chat/completions에만 적용됩니다.

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

응답 본문

필드	타입	설명
id	string	completion의 ID입니다.
object	string	"text_completion"입니다.
choices[].text	string	생성된 텍스트입니다.
choices[].finish_reason	string	"stop" 또는 "length"(max_tokens에서 잘림)입니다.
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], 연결 끊김은 스트리밍 페이지에서 설명합니다.

필드	타입	설명
choices[].text	string	이 청크에서 새로 생성된 텍스트입니다.
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	원인	조치
400	모델 서버가 요청을 거부했습니다. JSON 형식 에러, 잘못된 파라미터, 모델 페이지에 나오는 모델별 컨텍스트 길이를 넘는 컨텍스트가 원인입니다.	요청 본문을 수정하세요. 그대로 재시도하지 마세요.
404model_not_found	모델 ID가 카탈로그에 없습니다.	GET /models로 ID를 확인하세요.
429rate_limit_exceeded	조직에서 이미 8개의 요청이 처리 중입니다. 레이트 리밋 헤더는 포함되지 않습니다.	지수 백오프로 재시도하세요.
502	모델 백엔드가 에러를 반환했거나 연결할 수 없습니다. 본문은 일반 텍스트입니다.	지수 백오프로 재시도하세요.
503	서비스가 점검 중이거나 사용 가능한 모델 백엔드가 없습니다.	점검 중에는 Retry-After 시각까지 기다리세요. 그 밖에는 지수 백오프로 재시도하세요.

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

제한

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

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