Chat completions

The chat completions endpoint takes standard OpenAI-format requests and returns text. Point any OpenAI-compatible client at the Kyara base URL to use it. The endpoint is text-only. See Unsupported Features for the capabilities, such as tool calling, that are not available.

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!" }
    ]
  }'

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.kyara-intelligence.com/v1",
  apiKey: process.env.KYARA_INTELLIGENCE_API_KEY,
});

const response = await client.chat.completions.create({
  model: "deepseek/deepseek-v4-flash",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices[0].message.content);

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.kyara-intelligence.com/v1",
    api_key=os.environ.get("KYARA_INTELLIGENCE_API_KEY"),
)

response = client.chat.completions.create(
    model="deepseek/deepseek-v4-flash",
    messages=[{"role": "user", "content": "Hello!"}],
)

print(response.choices[0].message.content)

Request bodies are limited to 16 MB. Larger requests are rejected with a 413 error.

string

required

The model ID to use for the request. Find available model IDs in the catalog or call GET /v1/models. An unknown ID returns a 400 error with the code model_not_found.

array

required

An array of message objects forming the conversation. Each object requires a role (system, developer, user, or assistant) and a content string. Content must be plain text. Multimodal arrays are rejected.A message can also carry an optional name (string) and, for assistant turns you are sending back, reasoning (string), reasoning_content (string), or reasoning_details (array). Any other field inside a message is rejected with a 400 error.

number

Sampling temperature between 0 and 2. Higher values produce more varied output; lower values produce more focused, deterministic output. Support varies per model.

number

Nucleus sampling probability mass. The model considers only the tokens comprising the top top_p probability mass. Support varies per model.

integer

Kyara extension. Limits sampling to the top k most likely tokens. Accepted by many models beyond the OpenAI standard.

number

Kyara extension. Discards tokens whose probability is below min_p times the probability of the most likely token. Support varies per model.

number

Penalizes tokens that have already appeared in the text so far, encouraging the model to move on to new topics. Support varies per model.

number

Penalizes tokens in proportion to how often they have appeared so far, reducing verbatim repetition. Support varies per model.

number

Kyara extension. Multiplicative penalty on repeated tokens, as used by many open-weight models. Values above 1 discourage repetition. Support varies per model.

integer

Maximum number of tokens to generate. You can use max_completion_tokens interchangeably. If you set neither, the limit defaults to 8192. Values above the model’s maximum output length are lowered to that maximum rather than rejected.

integer

Alias for max_tokens. Maximum number of tokens to generate in the completion. Defaults to 8192 and is capped at the model’s maximum output length.

boolean

Set to true to receive the response as Server-Sent Events. Defaults to false. See Streaming.

object

Accepted for compatibility. Token usage is always included in the final stream chunk, so you do not need to set include_usage.

object

Controls reasoning behaviour for models that support it. Pass an object with any of:

effort (string), one of "max", "xhigh", "high", "medium", "low", "minimal", or "none"
max_tokens (integer), the maximum tokens to spend on reasoning
enabled (boolean), turns reasoning on or off for models that support toggling it
exclude (boolean), when true the model still reasons but the reasoning text is left out of the response

The top-level reasoning_effort is also accepted and is folded into reasoning.effort. If you set both, reasoning.effort takes precedence.

string

Kyara extension. Groups requests that belong to one conversation so they are served from the same prompt cache, which lowers latency and cost on long chats. Send the same value for every turn of a conversation. Maximum 256 characters. If you omit it, every request from your account shares one session. See Sessions and prompt caching.

integer

Number of completion choices to generate. Only 1 is supported; any other value returns a 400 error. Defaults to 1.

string | array

One or more sequences where the model will stop generating further tokens.

integer

A seed for deterministic sampling. Passing the same seed and request parameters should produce the same result, though determinism is not guaranteed.

boolean

Whether to return log probabilities of the output tokens. Support varies per model.

integer

Number of most likely tokens to return at each position, with their log probabilities. Requires logprobs: true. Support varies per model.

string

An identifier for the end user of your application. If you omit it, Kyara fills it with your account ID.

Response

A successful request returns a JSON object matching the OpenAI chat completions schema.

{
  "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 }
  }
}

string

A unique identifier for the completion.

string

Always "chat.completion" for non-streaming responses.

integer

Unix timestamp (seconds) of when the completion was created.

string

The model ID you requested. This always matches the public catalog ID.

array

An array of completion choices.

Show Choice object

integer

Zero-based index of this choice in the array.

object

The generated message. Contains role ("assistant") and content (string). For reasoning models, reasoning (string) holds the reasoning text unless you set reasoning.exclude.

string

The reason generation stopped. Common values: "stop", "length".

object

Token usage for the request.

Show Usage object

integer

Number of tokens in the input messages.

integer

Number of tokens in the generated output, including reasoning tokens.

integer

Total tokens consumed (prompt_tokens + completion_tokens).

object

Breakdown of the prompt. cached_tokens is the number of prompt tokens served from cache.

object

Breakdown of the output. reasoning_tokens is the number of tokens spent on reasoning.

Responses can include a few additional OpenAI-compatible fields, such as choices[].logprobs and choices[].message.refusal, which are passed through when present. Fields that are not part of the public contract, such as system_fingerprint, are never included.

Streaming

Set "stream": true to receive the response as Server-Sent Events. Each data: event carries a chat.completion.chunk object. The stream terminates with data: [DONE].

curl

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",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Hello!" }
    ]
  }'

A few things to expect from the stream:

The first chunk usually carries only the assistant role. Reasoning models then send chunks with delta.reasoning before any delta.content.
The final chunk has an empty choices array and carries the usage object. You do not need stream_options.include_usage; usage is always sent.
If generation fails partway through, the stream ends with an error event instead of [DONE], and you are not charged for the request:

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 charged only for the output produced up to that point.

Sessions and prompt caching

Kyara keeps requests that share a session_id on the same prompt cache, so each turn of a long conversation reuses the cached prefix instead of re-processing it. This lowers latency and input cost. Cached prompt tokens are reported in usage.prompt_tokens_details.cached_tokens. Pass a stable session_id per conversation (a chat ID, for example). If you omit it, all requests from your account share one session, which works well for a single user and less well for an app that serves many conversations in parallel. session_id is accepted on every request and never changes what the model sees.

Errors

Errors use the OpenAI error envelope: { "error": { "message", "type", "param", "code" } }.

Status	`code`	Meaning
`400`	`invalid_json`	The request body is not valid JSON.
`400`	`null`	The request failed validation. `message` explains the problem and `param` names the field, for example `messages.0.foo` for an unsupported message field.
`400`	`model_not_found`	The `model` ID is not in the catalog.
`401`	`invalid_api_key`	The API key is missing or not recognized. See Authentication.
`403`	`no_active_plan`	Your account has no active subscription and no top-up credits.
`403`	`insufficient_balance`	Your balance cannot cover the estimated cost of the request. See Plans and credits.
`403`	`content_policy_violation`	Your input was flagged by content moderation.
`413`	`request_too_large`	The request body exceeds 16 MB.
`429`	`rate_limit_exceeded`	The model is temporarily rate limited. Retry with backoff.
`500`	`null`	An unexpected error. You are not charged.
`503`	`service_unavailable`	Generation is temporarily unavailable. Retry later. You are not charged.

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

Model IDs and pricing can change during early access. Use the models page as the current source of truth for available models.

Features such as tool calling, structured outputs, vision, and embeddings are not supported. See Unsupported Features for the complete list.

Get Started

Integrations

API Reference

Reference

Request

Response

Streaming

Sessions and prompt caching

Errors

​Request

​Response

​Streaming

​Sessions and prompt caching

​Errors

Request

Response

Streaming

Sessions and prompt caching

Errors