Early access: features, availability, and pricing may change as Kyara Intelligence evolves.

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/completions
curl 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 required

The model ID, from the catalog or GET /v1/models. An unknown ID returns 400 with the code model_not_found.

messages array required

The 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 reasoning
  • enabled (boolean): turns reasoning on or off, on models that can toggle it
  • exclude (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 send delta.reasoning chunks before any delta.content.
  • The final chunk has an empty choices array and carries the usage object. Usage is always sent, with or without stream_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.

StatuscodeMeaning
400nullThe request failed validation. message explains the problem and param names the field, such as messages.0.tool_calls for an unsupported message field.
400model_not_foundThe model ID isn't in the catalog.
403no_active_planNo active plan and no top-up credits.
403insufficient_balanceYour balance can't cover the estimated cost of the request.
429rate_limit_exceededThe model is temporarily rate limited. Retry with backoff.

Failed requests are never billed, whether they fail before generation starts or partway through a stream.