# Completions

> POST /completions 레퍼런스입니다. 요청 파라미터별 지원 상태, 응답과 스트림 청크 필드, 에러, 제한, 예제를 설명합니다.

Source: https://kiln.bricksum.com/docs/ko/api-reference/completions

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

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

## 인증

게이트웨이가 처리하는 엔드포인트의 인증 방식은 모두 같으며, [API 레퍼런스](https://kiln.bricksum.com/docs/ko/api-reference) 페이지에서 설명합니다.

## 요청 본문

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

### 공통 파라미터

아래 파라미터의 정의는 [API 레퍼런스](https://kiln.bricksum.com/docs/ko/api-reference) 페이지에 한 번만 정리했습니다. 여기에는 이 엔드포인트에서 다른 점만 적었습니다.

| 필드 | 타입 | 필수 | 기본값 | 상태 | 설명 |
| --- | --- | --- | --- | --- | --- |
| `model` | string | 필수 |  | 지원 | 공통 정의와 같습니다. |
| `max_tokens` | integer |  |  | 전달만 함 | 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. |
| `stream` | boolean |  | `false` | 지원 | 게이트웨이는 문자열 "true"와 숫자 1도 true로 읽으며, 전달하기 전에 이 필드를 boolean으로 다시 씁니다. usage 청크를 받으려면 아래의 stream_options를 사용하세요. |

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

| 필드 | 타입 | 필수 | 기본값 | 상태 | 설명 |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string \| array | 필수 |  | 지원 | 이어서 생성할 텍스트입니다. 게이트웨이는 값을 변경 없이 전달하며 검증하지 않습니다. |
| `stream_options` | object |  |  | 지원 | 스트리밍 응답 옵션입니다. stream: true와 함께 보낼 때만 사용하세요. |
| `stream_options.include_usage` | boolean |  | `false` | 지원 | true이면 스트림 끝에 choices가 비어 있고 usage 객체에 토큰 수와 cost가 담긴 청크가 하나 더 옵니다. 게이트웨이는 토큰 계측을 위해 모든 스트리밍 요청에 이 값을 설정하며, 요청하지 않은 경우 usage 청크를 제거합니다. |
| `temperature` | number |  |  | 전달만 함 | 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. 범위: 0–2 |
| `top_p` | number |  |  | 전달만 함 | 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. 범위: 0–1 |
| `n` | integer |  |  | 전달만 함 | 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. |
| `seed` | integer |  |  | 전달만 함 | 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. |
| `stop` | string \| array |  |  | 전달만 함 | 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. |
| `presence_penalty` | number |  |  | 전달만 함 | 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. 범위: -2–2 |
| `frequency_penalty` | number |  |  | 전달만 함 | 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. 범위: -2–2 |
| `logprobs` | integer |  |  | 전달만 함 | 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. |
| `echo` | boolean |  |  | 전달만 함 | 모델 서버로 전달됩니다. Kiln이 동작을 검증하지 않았습니다. |
| `ignore_eos` | boolean |  |  | 전달만 함 | 모델 서버로 전달됩니다. 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를 담은 응답 헤더입니다. 로그와 함께 저장하세요. |

## 스트림 청크

| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `choices[].text` | string | 이 청크에서 새로 생성된 텍스트입니다. |
| `choices[].finish_reason` | string \| null | 마지막 content 청크 전까지 null이며, 마지막 청크에 종료 사유가 담깁니다. |
| `usage` | object | stream_options.include_usage가 true일 때만 마지막 청크에 포함됩니다. 이 청크의 choices 배열은 비어 있습니다. |
| `usage.cost` | number | 이 요청으로 크레딧에서 차감되는 금액(USD)입니다. 게이트웨이가 usage 청크에 추가합니다. |

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

## 에러

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

401, 402, 403, 429는 요청이 이 엔드포인트에 도달하기 전에 게이트웨이가 반환합니다. 이 에러들은 [API 레퍼런스](https://kiln.bricksum.com/docs/ko/api-reference) 페이지에 한 번만 정리했습니다.

메시지 문구가 아니라 HTTP 상태와 error.code로 분기하세요. error.code 칸이 비어 있으면 본문에 code가 없다는 뜻입니다. 전체 상태 코드는 [에러](https://kiln.bricksum.com/docs/ko/errors) 페이지에 있습니다.

## 제한

컨텍스트 길이, 요청 본문 크기, 타임아웃, 조직별 레이트 리밋도 여기에 그대로 적용되며, [API 레퍼런스](https://kiln.bricksum.com/docs/ko/api-reference) 페이지에 한 번만 정리했습니다.

429의 헤더와 재시도 방법은 [레이트 리밋](https://kiln.bricksum.com/docs/ko/rate-limits) 페이지에 있습니다.

## 예제

### 요청

**cURL**
```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**
```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**
```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**
```json
{
  "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
  }
}
```

**text/event-stream**
```text
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**
```json
{
  "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"
  }
}
```