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.

POST/completions

URL

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

Request

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

Response

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

The token counts and cost in these examples are illustrative figures measured on gpt-oss-120b, not qwen3-32b's.

Authentication

Authentication is the same on every endpoint the gateway fronts, and is documented on the API Reference page.

Request body

Support status

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 page. Listed here with what this endpoint does differently.

modelstringrequiredsupported
Same as the shared definition.
Full definition
max_tokensintegerpassed through
Forwarded to the model server; not verified by Kiln.
Full definition
streambooleansupported
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.
Default
false
Full definition

Only on this endpoint

promptstring | arrayrequiredsupported
The text to continue. The gateway forwards the value unchanged and does not validate it.
stream_optionsobjectsupported
Options for a streaming response. Send it only together with stream: true.
usage options
- include_usagebooleansupported
  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.
  Default
  false
temperaturenumberpassed through
Forwarded to the model server; not verified by Kiln.
Range
0–2
top_pnumberpassed through
Forwarded to the model server; not verified by Kiln.
Range
0–1
nintegerpassed through
Forwarded to the model server; not verified by Kiln.
seedintegerpassed through
Forwarded to the model server; not verified by Kiln.
stopstring | arraypassed through
Forwarded to the model server; not verified by Kiln.
presence_penaltynumberpassed through
Forwarded to the model server; not verified by Kiln.
Range
-2–2
frequency_penaltynumberpassed through
Forwarded to the model server; not verified by Kiln.
Range
-2–2
logprobsintegerpassed through
Forwarded to the model server; not verified by Kiln.
echobooleanpassed through
Forwarded to the model server; not verified by Kiln.
ignore_eosbooleanpassed 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

With stream: true, each data: line carries one chunk with the fields below. Keepalive comments, data: [DONE] and disconnects are described on the Streaming page.

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.

Errors

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 page.

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.
404model_not_found	The model ID is not in the catalog.	Check the ID against GET /models.
429rate_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 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 page.

Headers and retry guidance for 429 are on the Rate limits page.