# Completions

> POST /completions reference: every request parameter with its support status, response and stream chunk fields, errors, limits and examples.

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

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

Generates text that continues a prompt. The request and response follow the OpenAI Completions format. The gateway meters it like a chat request and forwards the body to the model server. For conversations and tool calling, use Chat completions.

## Authentication

Authentication is the same on every endpoint the gateway fronts, and is documented on the [API Reference](https://kiln.bricksum.com/docs/en/api-reference) page.

## Request body

| Status | Description |
| --- | --- |
| supported | The gateway handles it, or a published measurement shows it works. |
| passed through | Forwarded to the model server; not verified by Kiln. |
| ignored | Accepted with 200, but not applied. The rest of the response is normal. |
| not supported | Rejected with an error, or not working on the models named in the description. |

### Common parameters

These are documented once on the [API Reference](https://kiln.bricksum.com/docs/en/api-reference) page. Listed here with what this endpoint does differently.

| Field | Type | required | Default | Status | Description |
| --- | --- | --- | --- | --- | --- |
| `model` | string | required |  | supported | Same as the shared definition. |
| `max_tokens` | integer |  |  | passed through | Forwarded to the model server; not verified by Kiln. |
| `stream` | boolean |  | `false` | supported | The gateway also reads the string "true" and the number 1 as true, and rewrites the field to a boolean before forwarding. Use stream_options below to keep the usage chunk. |

### Only on this endpoint

| Field | Type | required | Default | Status | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string \| array | required |  | supported | The text to continue. The gateway forwards the value unchanged and does not validate it. |
| `stream_options` | object |  |  | supported | Options for a streaming response. Send it only together with stream: true. |
| `stream_options.include_usage` | boolean |  | `false` | supported | When true, the stream ends with one extra chunk whose choices is empty and whose usage object holds the token counts and cost. The gateway sets this flag on every streaming request to meter tokens, and removes the usage chunk when you did not ask for it. |
| `temperature` | number |  |  | passed through | Forwarded to the model server; not verified by Kiln. Range: 0–2 |
| `top_p` | number |  |  | passed through | Forwarded to the model server; not verified by Kiln. Range: 0–1 |
| `n` | integer |  |  | passed through | Forwarded to the model server; not verified by Kiln. |
| `seed` | integer |  |  | passed through | Forwarded to the model server; not verified by Kiln. |
| `stop` | string \| array |  |  | passed through | Forwarded to the model server; not verified by Kiln. |
| `presence_penalty` | number |  |  | passed through | Forwarded to the model server; not verified by Kiln. Range: -2–2 |
| `frequency_penalty` | number |  |  | passed through | Forwarded to the model server; not verified by Kiln. Range: -2–2 |
| `logprobs` | integer |  |  | passed through | Forwarded to the model server; not verified by Kiln. |
| `echo` | boolean |  |  | passed through | Forwarded to the model server; not verified by Kiln. |
| `ignore_eos` | boolean |  |  | passed through | Forwarded to the model server; not verified by Kiln. The 400 (unsupported_parameter) check for gpt-oss models applies to /chat/completions only. |

OpenAI Completions parameters that are not listed here are forwarded to the model server in the same way. Kiln has not verified them.

## Response body

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | ID of the completion. |
| `object` | string | "text_completion". |
| `choices[].text` | string | The generated text. |
| `choices[].finish_reason` | string | "stop" or "length" (cut off by max_tokens). |
| `usage.prompt_tokens` | integer | Input tokens. |
| `usage.completion_tokens` | integer | Output tokens, including reasoning tokens. |
| `usage.total_tokens` | integer | Input plus output tokens. |
| `usage.prompt_tokens_details.cached_tokens` | integer | Input tokens served from the prefix cache. Present only when the model server reports it. |
| `usage.cost` | number | Amount in USD deducted from credits for this request. The gateway adds it. |
| `X-Neocloud-Generation-Id` | header | Response header with the ID of the usage event for this request. Store it with your logs. |

## Stream chunk

| Field | Type | Description |
| --- | --- | --- |
| `choices[].text` | string | The new text of this chunk. |
| `choices[].finish_reason` | string \| null | null until the last content chunk, which carries the reason. |
| `usage` | object | Only in the final chunk, and only when stream_options.include_usage is true. That chunk has an empty choices array. |
| `usage.cost` | number | Amount in USD deducted from credits for this request. The gateway adds it to the usage chunk. |

With stream: true, each data: line carries one chunk with the fields below. Keepalive comments, data: [DONE] and disconnects are described on the [Streaming](https://kiln.bricksum.com/docs/en/streaming) page.

## Errors

| Status | error.code | Cause | What to do |
| --- | --- | --- | --- |
| 400 |  | The model server rejected the request: malformed JSON, invalid parameters, or more than the model's context window (the Models page lists it per model). | Fix the payload. Do not retry as sent. |
| 404 | `model_not_found` | The model ID is not in the catalog. | Check the ID against GET /models. |
| 429 | `rate_limit_exceeded` | The organization already has 8 requests in flight. No rate-limit headers are sent. | Back off exponentially and retry. |
| 502 |  | The model backend returned an error or was unreachable. The body is plain text. | Retry with exponential backoff. |
| 503 |  | The service is in maintenance mode, or no model backend is available. | During maintenance, wait until the Retry-After date. Otherwise retry with exponential backoff. |

401, 402, 403 and 429 come from the gateway before the request reaches this endpoint. They are listed once on the [API Reference](https://kiln.bricksum.com/docs/en/api-reference) page.

Branch on the HTTP status and error.code, not on the message text. An empty error.code cell means the body carries no code. Every status code is listed on the [Errors](https://kiln.bricksum.com/docs/en/errors) page.

## Limits

Context length, request body size, timeouts and the per-organization rate limits apply here as well; they are listed once on the [API Reference](https://kiln.bricksum.com/docs/en/api-reference) page.

Headers and retry guidance for 429 are on the [Rate limits](https://kiln.bricksum.com/docs/en/rate-limits) page.

## Examples

### Request

**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);
```

### Response

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