API reference
Chat completions
Generate text from a conversation. Standard OpenAI request format, streaming over Server-Sent Events, and a few Kyara extensions.
The chat completions endpoint takes standard OpenAI requests and returns text, so any OpenAI-compatible client can call it. It is text-only: see Unsupported features for what is not available, such as tool calling.
Request
POST https://api.kyara-intelligence.com/v1/chat/completionscurl https://api.kyara-intelligence.com/v1/chat/completions \
-H "Authorization: Bearer $KYARA_INTELLIGENCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek/deepseek-v4-flash",
"messages": [
{ "role": "user", "content": "Hello!" }
]
}'Authenticate with your API key or an OAuth access token; see Authentication. Request bodies are limited to 16 MB, and larger ones are rejected with 413.
Parameters
Unknown top-level parameters are dropped without an error, so clients that send extra OpenAI fields keep working.
Invalid values in the parameters below are rejected with 400.
model string requiredThe model ID, from the catalog or GET /v1/models. An unknown ID returns 400 with the code model_not_found.
messages array requiredThe conversation so far, with at least one message. Each message needs a role (system, developer, user or assistant) and a content string. Content
must be plain text; multimodal content arrays are rejected.
A message may also carry a name string and, on assistant turns you send back, the model's earlier
reasoning as reasoning, reasoning_content (strings) or reasoning_details (array). Any other field in a message is rejected with 400.
temperature number Sampling temperature, usually between 0 and 2. Higher values give more varied output, lower values more focused output. Support varies by model.
top_p number Nucleus sampling: the model only considers the tokens making up the top top_p probability mass. Support varies by model.
top_k number Kyara extension. Limits sampling to the k most likely tokens. Support varies by model.
min_p number Kyara extension. Discards tokens whose probability is below min_p times that of the most likely token. Support varies by model.
presence_penalty number Penalizes tokens that already appeared, nudging the model toward new topics. Support varies by model.
frequency_penalty number Penalizes tokens in proportion to how often they appeared, reducing verbatim repetition. Support varies by model.
repetition_penalty number Kyara extension. A multiplicative penalty on repeated tokens, as used by many open-weight models; values above 1 discourage repetition. Support varies by model.
max_completion_tokens integer The maximum number of tokens to generate. Must be positive. Defaults to 8192, and
values above the model's maximum output length are lowered to that maximum rather than rejected.
max_tokens integer The older name for max_completion_tokens, with the same rules. If you send both, max_completion_tokens wins.
stream boolean Set to true to receive the response as Server-Sent Events. Defaults to false. See Streaming.
stream_options object Accepted for compatibility, with include_usage and include_obfuscation booleans. Usage
is always sent in the final chunk, so you don't need include_usage.
reasoning object Controls reasoning on models that support it. Any of:
effort:"max","xhigh","high","medium","low","minimal"or"none"max_tokens(integer): the most tokens to spend on reasoningenabled(boolean): turns reasoning on or off, on models that can toggle itexclude(boolean): the model still reasons, but the reasoning text is left out of the response
Other fields in the object are rejected with 400. See Reasoning.
reasoning_effort string The OpenAI-style shortcut for reasoning.effort, with the same values. If you set both, reasoning.effort wins.
session_id string Kyara extension. Groups the requests of one conversation so they share a prompt cache. Up to 256 characters. When omitted or empty, every request from your account shares one session. See Sessions and prompt caching.
stop string or array Up to four sequences where the model stops generating.
seed number A seed for sampling. The same seed and parameters should give the same result, though determinism isn't guaranteed.
logprobs boolean Whether to return log probabilities of the output tokens. Support varies by model.
top_logprobs number How many of the most likely tokens to return at each position, with their log probabilities. Needs logprobs: true. Support varies by model.
n integer The number of choices to generate. Only 1 is supported; any other value returns 400.
user string An identifier for the end user of your app. Defaults to your account ID.
Response
A successful request returns a JSON object in the OpenAI chat completion format.
{
"id": "gen-1755600000-AbCdEfGhIjKlMnOp",
"object": "chat.completion",
"created": 1755600000,
"model": "deepseek/deepseek-v4-flash",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "Hello! How can I help you today?" },
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 9,
"completion_tokens": 9,
"total_tokens": 18,
"prompt_tokens_details": { "cached_tokens": 0 },
"completion_tokens_details": { "reasoning_tokens": 0 }
}
}id string A unique identifier for the completion.
object string Always "chat.completion".
created integer Unix timestamp, in seconds, of when the completion was created.
model string The model ID you requested, always as it appears in the catalog.
choices[].message object The generated message: role ("assistant") and content. On reasoning models, reasoning holds the reasoning text unless you set reasoning.exclude.
choices[].finish_reason string Why generation stopped, usually "stop" or "length".
usage.prompt_tokens integer Tokens in the input messages.
usage.completion_tokens integer Tokens in the output, reasoning included.
usage.total_tokens integer The sum of prompt_tokens and completion_tokens.
usage.prompt_tokens_details.cached_tokens integer Prompt tokens served from the prompt cache.
usage.completion_tokens_details.reasoning_tokens integer Output tokens spent on reasoning.
Other OpenAI-compatible fields, such as choices[].logprobs and choices[].message.refusal,
are passed through when present. Fields outside the public format, such as system_fingerprint, are never
included.
Streaming
Set "stream": true to receive Server-Sent Events. Each data: event carries a chat.completion.chunk object, and the stream ends with data: [DONE].
curl -N https://api.kyara-intelligence.com/v1/chat/completions \
-H "Authorization: Bearer $KYARA_INTELLIGENCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek/deepseek-v4-flash",
"stream": true,
"messages": [
{ "role": "user", "content": "Hello!" }
]
}'- The first chunk usually carries only the assistant
role. Reasoning models then senddelta.reasoningchunks before anydelta.content. - The final chunk has an empty
choicesarray and carries theusageobject. Usage is always sent, with or withoutstream_options.include_usage. - If generation fails partway through, the stream ends with an error event instead of
[DONE], and the request is not billed:
data: {"error":{"message":"Upstream stream failed","type":"server_error","param":null,"code":"upstream_stream_error"}}If you close the connection early, generation stops and you are billed for the prompt and the output produced so far; see Cancelling a request.
Reasoning
Reasoning models think before they answer. Their reasoning arrives in message.reasoning, or in delta.reasoning when streaming, and counts toward completion_tokens. Use the reasoning object to set the effort, cap the reasoning tokens, or leave the text out of the response:
{
"model": "deepseek/deepseek-v4-flash",
"reasoning": { "effort": "low", "exclude": true },
"messages": [
{ "role": "user", "content": "Is 1,001 a prime number?" }
]
}To keep a multi-turn conversation coherent, send the earlier reasoning back on the assistant messages in reasoning, reasoning_content or reasoning_details. Which models reason is shown
on each model's page in the catalog. A response with reasoning but no
visible text is not billed.
Sessions and prompt caching
Requests that share a session_id are served from the same prompt cache, so each turn of a long
conversation reuses the already processed beginning instead of processing it again. That lowers latency and input
cost. Cached prompt tokens are reported in usage.prompt_tokens_details.cached_tokens.
{
"model": "deepseek/deepseek-v4-flash",
"session_id": "chat_8f14e45f",
"messages": [
{ "role": "system", "content": "You are a concise assistant." },
{ "role": "user", "content": "Summarize our plan so far." }
]
}Send a stable session_id per conversation, such as your chat ID. Without one, all requests from your
account share a single session, which suits a single user and works less well for an app serving many conversations at
once. session_id never changes what the model sees.
Errors
Errors use the OpenAI error envelope. The ones you are most likely to meet here are below; see Errors for every code and when to retry.
| Status | code | Meaning |
|---|---|---|
400 | null | The request failed validation. message explains the problem and param names the field,
such as messages.0.tool_calls for an unsupported message field. |
400 | model_not_found | The model ID isn't in the catalog. |
403 | no_active_plan | No active plan and no top-up credits. |
403 | insufficient_balance | Your balance can't cover the estimated cost of the request. |
429 | rate_limit_exceeded | The model is temporarily rate limited. Retry with backoff. |
Failed requests are never billed, whether they fail before generation starts or partway through a stream.