API reference

Chat completions

POST /v1/chat/completions takes a request in the OpenAI Chat Completions format and answers in the same format, whole or streamed.

POSThttps://gateway.kalsenti.ai/v1/chat/completions
On this page

Request body

curl https://gateway.kalsenti.ai/v1/chat/completions \
  -H "Authorization: Bearer $KALSENTI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash-1017-raw",
    "messages": [{ "role": "user", "content": "Write a haiku about the sea." }]
  }'

Headers

HeaderNotes
AuthorizationYour key, as Bearer sk-kalsenti-…. x-api-key works too.
Content-Typeapplication/json
Idempotency-KeyOptional. Stops a retried request from running twice. See Idempotency keys.

Body

modelstringrequired
A model id from GET /v1/models or the Models page.
messagesarrayrequired
The conversation so far, oldest first. See Messages and content.
max_tokensinteger
The most tokens the reply may use, at least 1. Left out, it’s 16,000. Asking for more than the model allows gives you the model’s maximum, without an error. max_completion_tokens is accepted too, and wins if you send both.
streamboolean
Send the reply as server-sent events while it’s written. See Streaming.
stream_optionsobject
{ "include_usage": true } adds a last chunk with the token counts. Without it a stream has no usage.
temperaturenumber
Sampling temperature, passed to the model as given.
top_pnumber
Nucleus sampling, passed to the model as given.
stopstring or array
Up to 4 sequences that end the reply when the model writes them.
toolsarray
Functions the model may call. See Tools.
tool_choicestring or object
"auto" (the default), "none", "required", or { "type": "function", "function": { "name": "…" } } to require one function.
parallel_tool_callsboolean
false asks for at most one tool call per reply.
response_formatobject
Structured output, such as { "type": "json_object" } or a json_schema, passed to the model as given. Not every model supports it: those that don’t refuse the request with a 400.
reasoning_effortstring
"minimal", "low", "medium" or "high". How much a reasoning model thinks before it answers. Models that don’t reason ignore it.
functions, function_callarray, string or object
The older way of declaring tools. Still accepted; replies then use function_call too.

Any other field is accepted and ignored. Fields that change what comes back but can’t be honoured are refused instead: see Not supported.

Messages and content

Each message has a role and content. Roles are system, developer, user, assistant and tool.

  • content is a string, or an array of parts: text parts, and image_url parts with a web address or a base64 data: URL.
  • A text part can carry cache_control for prompt caching, on models that support it. Input read from the cache is charged at the model’s cache read price.
  • An assistant message can carry the tool_calls it made. Its reasoning_content can be sent back too, and is passed on to models that use it.
  • A tool message answers one tool call by its tool_call_id. Its content is a string, or a list of text parts, which are joined. Other parts are refused with a 400.
  • refusal parts from earlier replies are dropped.
A message with an image
{
  "role": "user",
  "content": [
    { "type": "text", "text": "What is in this picture?" },
    { "type": "image_url", "image_url": { "url": "https://example.com/harbour.jpg" } }
  ]
}

Tools

Declare functions in tools with a name, a description and JSON Schema parameters. strict is passed on where the model supports it.

Request
curl https://gateway.kalsenti.ai/v1/chat/completions \
  -H "Authorization: Bearer $KALSENTI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash-1017-raw",
    "messages": [{ "role": "user", "content": "What is the weather in Leeds?" }],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Current weather for a city",
        "parameters": {
          "type": "object",
          "properties": { "city": { "type": "string" } },
          "required": ["city"]
        }
      }
    }]
  }'

When the model wants a function, the reply has tool_calls and finish_reason is "tool_calls":

Response (part)
"choices": [
  {
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_4b1e",
          "type": "function",
          "function": { "name": "get_weather", "arguments": "{\"city\":\"Leeds\"}" }
        }
      ]
    },
    "finish_reason": "tool_calls"
  }
]

Run the function yourself, then send the conversation back with its result in a tool message:

Next request’s messages
"messages": [
  { "role": "user", "content": "What is the weather in Leeds?" },
  {
    "role": "assistant",
    "content": null,
    "tool_calls": [
      { "id": "call_4b1e", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\":\"Leeds\"}" } }
    ]
  },
  { "role": "tool", "tool_call_id": "call_4b1e", "content": "{\"temp_c\": 11, \"sky\": \"overcast\"}" }
]

Only function tools work on every model. Built-in tool types, such as a web search tool, are accepted by some models and refused by others with a 400 and the code unsupported_tool_type. Kalsenti doesn’t run tools for API requests: your code runs them.

Response

Response
{
  "id": "chatcmpl_5f0c2a9e41d7b83c6a1e9f04",
  "object": "chat.completion",
  "created": 1793270400,
  "model": "deepseek-v4.1-flash-1017-raw",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Grey waves fold and break,\nsalt wind carries the gulls home,\nthe tide keeps its time."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 24,
    "total_tokens": 39
  }
}
idstring
Starts with chatcmpl_. This isn’t the request ID you’d give support: that’s the x-request-id header.
choicesarray
Always one choice, at index 0.
choices[0].message.contentstring or null
The reply. null when the model only called tools.
choices[0].message.reasoning_contentstring
The model’s reasoning, when it returns any.
choices[0].message.tool_callsarray
Function calls the model made, if any.
choices[0].finish_reasonstring
stop, length (it reached max_tokens), tool_calls or content_filter. With the older functions, function_call.
usage.prompt_tokensinteger
Input tokens, including any read from the cache. usage.prompt_tokens_details.cached_tokens says how many, when there are some.
usage.completion_tokensinteger
Output tokens. usage.completion_tokens_details.reasoning_tokens says how many were reasoning, when the model reports it.

What you’re charged is worked out from these counts. See How a request is priced.

Streaming

curl -N https://gateway.kalsenti.ai/v1/chat/completions \
  -H "Authorization: Bearer $KALSENTI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash-1017-raw",
    "stream": true,
    "stream_options": { "include_usage": true },
    "messages": [{ "role": "user", "content": "Write a haiku about the sea." }]
  }'

With "stream": true, the reply comes as text/event-stream. Each event is a data: line holding a chat.completion.chunk:

  1. The first chunk’s delta is { "role": "assistant" }.
  2. Then chunks with delta.content, delta.reasoning_content or delta.tool_calls as the reply is written.
  3. A chunk with an empty delta and the finish_reason.
  4. With stream_options.include_usage, a chunk with empty choices and the usage.
  5. data: [DONE].
Events
data: {"id":"chatcmpl_9d2e61b0c4f7a83e5b1d0c27","object":"chat.completion.chunk","created":1793270400,"model":"deepseek-v4.1-flash-1017-raw","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl_9d2e61b0c4f7a83e5b1d0c27","object":"chat.completion.chunk","created":1793270400,"model":"deepseek-v4.1-flash-1017-raw","choices":[{"index":0,"delta":{"content":"Grey waves"},"finish_reason":null}]}

data: {"id":"chatcmpl_9d2e61b0c4f7a83e5b1d0c27","object":"chat.completion.chunk","created":1793270400,"model":"deepseek-v4.1-flash-1017-raw","choices":[{"index":0,"delta":{"content":" fold and break,"},"finish_reason":null}]}

data: {"id":"chatcmpl_9d2e61b0c4f7a83e5b1d0c27","object":"chat.completion.chunk","created":1793270400,"model":"deepseek-v4.1-flash-1017-raw","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl_9d2e61b0c4f7a83e5b1d0c27","object":"chat.completion.chunk","created":1793270400,"model":"deepseek-v4.1-flash-1017-raw","choices":[],"usage":{"prompt_tokens":15,"completion_tokens":24,"total_tokens":39}}

data: [DONE]

If nothing has been sent for 15 seconds, for example while a model thinks, a comment line (: keep-alive) keeps the connection open. SSE clients and the SDKs skip it.

A problem before the reply starts comes back as a normal error with its status code. If the model fails part way through, the stream ends with one error event instead of [DONE]: see Errors during a stream.

Not supported

These are refused with a 400, rather than quietly giving you something different:

FieldWhy
nMore than one choice per request. Send separate requests instead.
logprobsToken log probabilities aren’t available.
modalitiesOnly text replies. Anything other than ["text"] is refused.
input_audio partsAudio input isn’t supported.
Other content partsOnly text and image_url parts are accepted. Files aren’t.

The error names the field in param, for example "param": "n", "message": "n is not supported". Other fields you might send to similar APIs, such as seed, presence_penalty, frequency_penalty, logit_bias and user, are ignored.