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.
https://gateway.kalsenti.ai/v1/chat/completionsOn 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
| Header | Notes |
|---|---|
Authorization | Your key, as Bearer sk-kalsenti-…. x-api-key works too. |
Content-Type | application/json |
Idempotency-Key | Optional. 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_tokensis 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_callsbooleanfalseasks for at most one tool call per reply.response_formatobject- Structured output, such as
{ "type": "json_object" }or ajson_schema, passed to the model as given. Not every model supports it: those that don’t refuse the request with a400. 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_calltoo.
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.
contentis a string, or an array of parts:textparts, andimage_urlparts with a web address or a base64data:URL.- A
textpart can carrycache_controlfor prompt caching, on models that support it. Input read from the cache is charged at the model’s cache read price. - An
assistantmessage can carry thetool_callsit made. Itsreasoning_contentcan be sent back too, and is passed on to models that use it. - A
toolmessage answers one tool call by itstool_call_id. Itscontentis a string, or a list oftextparts, which are joined. Other parts are refused with a400. refusalparts from earlier replies are dropped.
{
"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.
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":
"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:
"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
{
"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 thex-request-idheader. choicesarray- Always one choice, at index 0.
choices[0].message.contentstring or null- The reply.
nullwhen 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_reasonstringstop,length(it reachedmax_tokens),tool_callsorcontent_filter. With the olderfunctions,function_call.usage.prompt_tokensinteger- Input tokens, including any read from the cache.
usage.prompt_tokens_details.cached_tokenssays how many, when there are some. usage.completion_tokensinteger- Output tokens.
usage.completion_tokens_details.reasoning_tokenssays 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:
- The first chunk’s
deltais{ "role": "assistant" }. - Then chunks with
delta.content,delta.reasoning_contentordelta.tool_callsas the reply is written. - A chunk with an empty
deltaand thefinish_reason. - With
stream_options.include_usage, a chunk with emptychoicesand theusage. data: [DONE].
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:
| Field | Why |
|---|---|
n | More than one choice per request. Send separate requests instead. |
logprobs | Token log probabilities aren’t available. |
modalities | Only text replies. Anything other than ["text"] is refused. |
input_audio parts | Audio input isn’t supported. |
| Other content parts | Only 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.