# Completions

> POST /completions のリファレンスです。リクエストパラメータごとの対応状況、レスポンスとストリームチャンクのフィールド、エラー、制限、サンプルを説明します。

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

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

プロンプトに続くテキストを生成します。リクエストとレスポンスは OpenAI Completions 形式に従います。ゲートウェイは chat リクエストと同じ方法で計測し、ボディをモデルサーバーに転送します。会話やツール呼び出しには Chat completions を使用してください。

## 認証

ゲートウェイが処理するエンドポイントの認証方法はすべて同じで、 [API リファレンス](https://kiln.bricksum.com/docs/ja/api-reference) ページで説明しています。

## リクエストボディ

| ステータス | 説明 |
| --- | --- |
| 対応 | ゲートウェイが処理するか、公開済みの実測で動作を確認した項目です。 |
| 転送のみ | モデルサーバーに転送されます。Kiln は動作を検証していません。 |
| 無視 | 200 で受け付けられますが、適用されません。レスポンスのその他の部分は通常どおりです。 |
| 非対応 | エラーで拒否されるか、説明に記載したモデルでは動作しません。 |

### 共通パラメータ

以下のパラメータの定義は [API リファレンス](https://kiln.bricksum.com/docs/ja/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 を含むチャンクが 1 つ追加されます。ゲートウェイはトークン計測のためにすべてのストリーミングリクエストでこの値を設定し、指定がなかった場合は 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: 行に以下のフィールドを持つチャンクが 1 つずつ入ります。keepalive コメント、data: [DONE]、切断時の動作は [ストリーミング](https://kiln.bricksum.com/docs/ja/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/ja/api-reference) ページに一度だけ記載しています。

メッセージの文言ではなく、HTTP ステータスと error.code で分岐してください。error.code の欄が空の場合、ボディに code はありません。すべてのステータスコードは [エラー](https://kiln.bricksum.com/docs/ja/errors) ページにあります。

## 制限

コンテキスト長、リクエストボディのサイズ、タイムアウト、組織ごとのレート制限もここに適用され、 [API リファレンス](https://kiln.bricksum.com/docs/ja/api-reference) ページに一度だけ記載しています。

429 のヘッダーと再試行の方法は [レート制限](https://kiln.bricksum.com/docs/ja/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"
  }
}
```