Get started

Core parameters

The fields that appear on most requests, and how xKiro treats values a model cannot accept.

Model and messages#

Field	Type	Description
`model`required	string	Full ID with vendor prefix, e.g. `openai/gpt-5.6-sol`. A bare model name returns `404`.
`messages`required	array	The conversation. Send the whole history every time — the API is stateless and remembers nothing between calls.
`system`	string	Standing instructions. A top-level field on Messages; a `system` role message on Chat Completions.

Nothing is remembered between requests

There is no conversation ID. Multi-turn chat means resending the history — which is also why long conversations get more expensive per turn, and why counting tokens is worth doing.

Controlling length#

Field	Type	Description
`max_tokens`	integer	Ceiling on generated tokens. Required on Messages, optional on Chat Completions.
`stop / stop_sequences`	string[]	Generation ends when one of these appears. The sequence itself is not included in the output.

max_tokens is never raised for you

It is your cost ceiling, not a hint. xKiro clamps it down when it exceeds what a model allows, but never up — an integration that sets 500 deliberately must not be billed for 4,000.

Recognising a truncated answer

Check the finish reason on every response. length (Chat Completions) or max_tokens (Messages) means the model was cut off mid-thought — the text will look complete right up to the point it stops.

const choice = res.choices[0];
if (choice.finish_reason === "length") {
  // The answer is incomplete. Raise max_tokens, or ask for something shorter.
  // Rendering it as-is shows the user a sentence that just stops.
}

Sampling#

Field	Type	Description
`temperature`	numberdefault: 1	Randomness. 0 is near-deterministic and right for extraction and classification; 0.7–1.0 suits writing. Ranges differ by dialect (0–2 vs 0–1) and are clamped per model.
`top_p`	numberdefault: 1	Nucleus sampling. Use this or temperature — tuning both at once makes results hard to reason about.
`top_k`	integer	Sample from the K most likely tokens. Messages only.
`frequency_penalty`	number	−2 to 2. Discourages repeating tokens already used. Chat Completions only.
`presence_penalty`	number	−2 to 2. Encourages new topics. Chat Completions only.
`seed`	integer	Best-effort reproducibility. Do not build tests that require identical output — no provider guarantees it.

Sampling is ignored while reasoning is on

Reasoning models reject temperature and top_p, so xKiro removes them rather than letting the provider fail the request. See Reasoning.

Behaviour#

Field	Type	Description
`stream`	booleandefault: false	Emit server-sent events. Required in practice for anything over 95 seconds — see Streaming.
`reasoning_effort`	string	`none` … `max`. Omitting it is not the same as `none` — see Reasoning.
`response_format`	object	`{ "type": "json_object" }` constrains output to valid JSON. See Structured output.
`tools / tool_choice`	array / string	Function calling. See Tool calling.
`user`	string	Opaque identifier for your end user, recorded in your logs. Useful for tracing abuse back to an account without sending personal data.

What happens to values a model cannot take#

The rule is the same everywhere: fix it quietly where that is safe, fail loudly where it is not.

Out of range— clamped to the model's range. Failing a request because a model tops out at 1.5 instead of 2 helps nobody.
Not supported at all — dropped. Some providers reject unknown fields outright, which would turn a harmless parameter into a failed request.
Larger than the context window — rejected with 400 before any provider is called, so it costs you nothing.
Images to a model without vision — removed, with a note telling the model it could not see them, so it says so instead of inventing a description.