Chat completionsEndpoints

POST /v1/chat/completions

Scope: models
Tier: All tiers
Price: Per token, see Models
Free credit: Yes

Send a list of messages and get the model's reply. The format is OpenAI's, so the OpenAI SDKs work as they are; see OpenAI SDKs for which fields are forwarded.

Before you begin

A key with the models scope. See Authentication.
A model id from Models, or auto.
Enough balance for the call's hold. See Price.

Request body

Parameter	Type	Default	Description
`model`Required	string	·	A model id from `GET /v1/models`, or `auto`. Unknown ids get 404 `model_not_found`; a paused model gets 503 `model_unavailable`.
`messages`Required	array	·	1 to 256 messages, up to 1,000,000 characters of text in all. Roles: `system`, `developer` (read as system), `user`, `assistant` (may carry `tool_calls`) and `tool` (needs `tool_call_id`). `content` is a string or an array of `text` parts.
`max_tokens`	integer	`4,096`	Output cap, 1 to 32,768; larger values are lowered to 32,768. `max_completion_tokens` is also read and wins. It sizes the hold, so a lower value needs less balance.
`temperature`	number	`0.7`	0 to 2. Values outside are clamped.
`top_p`	number	`1`	0 to 1. Values outside are clamped.
`tools`	array	·	Function tools in OpenAI format, up to 64. Names are 1 to 64 characters.
`stream`	boolean	`false`	Stream the answer as server-sent events. See Streaming.

Other OpenAI fields are ignored. The body is limited to 1 MB.

Response

Field	Type	Description
`id`	string	`chatcmpl-…`
`model`	string	The model that answered.
`choices[0].message.content`	string	The answer.
`choices[0].message.tool_calls`	array	Present when the model calls a tool.
`choices[0].finish_reason`	string	Why it stopped, such as `stop`, `length` or `tool_calls`.
`usage.prompt_tokens`	integer	Prompt tokens billed.
`usage.completion_tokens`	integer	Completion tokens billed.
`usage.prompt_tokens_details.cached_tokens`	integer	Prompt tokens served from cache, billed at the cached price.
`kaer.request_id`	string	Same as the `x-request-id` header.
`kaer.cost_usd`	number	What the call cost.
`kaer.free_credit_usd`	number	The part of the cost paid from free credit.

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "x1-kaer",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello! How can I help?" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 9,
    "total_tokens": 21,
    "prompt_tokens_details": { "cached_tokens": 0 }
  },
  "kaer": { "request_id": "req_…", "cost_usd": 0.0000048, "free_credit_usd": 0.0000048 }
}

The response also carries these headers: x-request-id, the x-ratelimit-* headers and x-kaer-cost-usd.

Price

Prompt tokens × the input price + completion tokens × the output price, with cached prompt tokens at the cached price when the model has one. Prices are per 1M tokens and come from the live model list.

Worked example (at the listed price, the most a call can cost)

1,000 prompt and 500 completion tokens on `x1-kaer`	1,000 × $0.10/1M + 500 × $0.40/1M	$0.0003
The same call 10,000 times	10,000 × $0.0003	$3.00
Hold for a 4,000 character prompt with the default `max_tokens` (4,096)	prompt estimate + max_tokens of output, at the dearest band, + 25%	$0.00230825

Before the model runs, the gateway holds an upper bound: the prompt estimated generously plus max_tokens of output at the dearest band, plus 25%. The call settles at its actual cost and the rest of the hold is released at once.

Why this matters: your balance has to cover the hold, not just the final cost. A lower max_tokens shrinks the hold.

Errors

Status	Code	When
400	`invalid_json`	The body is not valid JSON. Images also needs a JSON object.
400	`model_required`	`model` is missing.
400	`messages_required`	`messages` is missing or empty.
400	`too_many_messages`	More than 256 messages.
400	`invalid_request_error`	The model service refused the body: an unsupported role or content part, a `tool` message without `tool_call_id`, more than 64 tools, or over 1,000,000 characters of text.
404	`model_not_found`	No such model on the platform.
413	`body_too_large`	The body is over the endpoint's limit: chat 1 MB, search 16 KB, batch 64 KB, images 8 KB, mail 512 KB.
429	`too_many_streams`	Your account already has its tier's maximum of open streams.
502	`upstream_unreachable`	The model service did not answer. Nothing was charged.
502	`upstream_error`	The model provider failed, or the edge lost its connection to the API.
503	`model_unavailable`	The model is paused for now.

You are not charged for failed calls. For auth, balance and rate errors, see Errors.

Send a request

This request sets a system message and caps the answer at 200 tokens.

curl https://api.kaer.ai/v1/chat/completions \
  -H "Authorization: Bearer $KAER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "x1-kaer",
    "messages": [
      {"role": "system", "content": "Answer in one paragraph."},
      {"role": "user", "content": "Explain quantum computing."}
    ],
    "max_tokens": 200
  }'