Chat completions

Generates a model response for a conversation. The request and response follow the OpenAI Chat Completions format. Each parameter below is marked with what the gateway does with it today.

POST/chat/completions

URL

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

Request

bash

curl https://api.bricksum.com/v1/chat/completions \
  -H "Authorization: Bearer $KILN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-32b",
    "messages": [
      {"role": "system", "content": "Answer briefly."},
      {"role": "user", "content": "Hello!"}
    ],
    "max_tokens": 800
  }'

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.chat.completions.create(
    model="qwen3-32b",
    messages=[
        {"role": "system", "content": "Answer briefly."},
        {"role": "user", "content": "Hello!"},
    ],
    max_tokens=800,
)
print(resp.choices[0].message.content)
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.chat.completions.create({
  model: "qwen3-32b",
  messages: [
    { role: "system", content: "Answer briefly." },
    { role: "user", content: "Hello!" },
  ],
  max_tokens: 800,
});
console.log(resp.choices[0].message.content);
console.log(resp.usage);

Response

200 OK

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "qwen3-32b",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello! How can I help?" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "cost": 0.000001155
  }
}

200 OK · text/event-stream

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"qwen3-32b","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"qwen3-32b","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1710000000,"model":"qwen3-32b","choices":[],"usage":{"prompt_tokens":9,"completion_tokens":12,"total_tokens":21,"cost":0.000001155}}

data: [DONE]

400 Bad Request

{
  "error": {
    "message": "Invalid 'messages': the array must contain at least one message.",
    "type": "invalid_request_error",
    "param": "messages",
    "code": "empty_array"
  }
}

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
messagesarrayrequiredsupported
An empty or missing array is rejected with 400 (empty_array). A message is a role and a content, in the shapes below.
Full definition
system message
- rolestringrequiredsupported
  Set to "system".
  Allowed values
  system
- contentstringrequiredsupported
  Instructions that apply to the whole conversation.
user message
- rolestringrequiredsupported
  Set to "user".
  Allowed values
  user
- contentstring | arrayrequiredsupported
  Text, or an array of content parts. The gateway forwards a parts array unchanged. Image parts (image_url) work only on models whose input includes images; see the Models page.
assistant message
- rolestringrequiredsupported
  Set to "assistant".
  Allowed values
  assistant
- contentstring | nullsupported
  An earlier model reply. It can be null when the reply was a tool call.
- tool_callsarraysupported
  The tool_calls array the model returned. Send it back unchanged before the matching tool message.
tool message
- rolestringrequiredsupported
  Set to "tool".
  Allowed values
  tool
- tool_call_idstringrequiredsupported
  The id of the tool call this result answers.
- contentstringrequiredsupported
  The result of running the tool, usually a JSON string.
max_tokensintegersupported
Sent to the model server as given. If generation stops at this cap (finish_reason: "length"), a non-streaming response can return empty content.
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.
Default
false
Full definition
toolsarraysupported
Sent as OpenAI function definitions.
Full definition
function tool
- typestringrequiredsupported
  Set to "function".
  Allowed values
  function
- function.namestringrequiredsupported
  The name the model uses in tool_calls.
- function.descriptionstringrequiredsupported
  What the function does. A function without a description is rejected with 400.
- function.parametersobjectsupported
  JSON Schema of the function arguments.
tool_choice= "auto"stringsupported
Sent as the string "auto".
Full definition
tool_choice= "required" | {"type": "function", ...}string | objectnot supported
Forced tool choice, sent as "required" or as a named function. On qwen3-32b (measured 2026-09-26), forced tool choice fails without a clear error: tool_choice "required" returns HTTP 500 with a plain-text "Internal Server Error" body, and naming a function returns 200 with empty arguments (finish_reason "stop"). Neither is a 4xx, so do not retry it — send tool_choice "auto" only.
Full definition

Only on this endpoint

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
parallel_tool_callsbooleannot supported
Applied only on models whose Parallel tool calls cell on the Models page is yes; qwen3-32b is not one of them. Measured on gpt-oss-120b: the request is accepted with 200, and the model calls at most one tool per reply. On qwen3-32b the parallel_tool_calls setting is not applied, which is not the same as replies holding one call: even with parallel_tool_calls: false, one reply can carry several tool calls. Answer every entry in tool_calls with its own tool message.
reasoning_effortstringsupported
Forwarded to the model as sent. gpt-oss-120b accepts low, medium and high; whether another model honours it is not published. Higher values spend more reasoning tokens, which adds latency and output tokens.
Allowed values
low, medium, high
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.
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
stopstring | arrayignored
Accepted, but not applied. Generation continues past the stop string.
response_formatobjectnot supported
json_object and json_schema do not work yet. The request is accepted with 200, but content comes back empty. To get JSON, tell the model in the prompt to reply with JSON only, then parse and validate the result in your client.
ignore_eosbooleannot supported
On gpt-oss models, true is rejected with 400 (unsupported_parameter) before the request reaches the model. On other models it is forwarded to the model server.

OpenAI chat 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 chat completion.
object	string	"chat.completion".
created	integer	Creation time in Unix seconds.
model	string	The model ID that produced the response.
choices[].index	integer	Position of the choice.
choices[].message.role	string	"assistant".
choices[].message.content	string \| null	The generated text. It can be empty when finish_reason is "length", and null when the reply is a tool call.
choices[].message.tool_calls	array	Tool calls the model wants you to run: id, type and function.name with function.arguments as a JSON string.
choices[].finish_reason	string	"stop", "length" (cut off by max_tokens) or "tool_calls".
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
object	string	"chat.completion.chunk".
choices[].delta.content	string	The new text of this chunk.
choices[].delta.tool_calls	array	Tool call fragments. Concatenate function.arguments across chunks by index.
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
400empty_array	messages is empty or missing.	Send at least one message.
400unsupported_parameter	ignore_eos: true on a gpt-oss model.	Remove ignore_eos.
400	The model server rejected the request: malformed JSON, invalid parameters, a function without a description, 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.