Chat Completions
POST https://api.devotel.com/v1/chat/completionsThe one endpoint you need. Request and response shapes match the OpenAI Chat Completions API.
Request parameters
These are validated by the gateway:
| Parameter | Type | Notes |
|---|---|---|
model | string, required | kimi-k3. See Models. |
messages | array, required | At least one message. Roles below. |
stream | boolean | true for SSE. See Streaming. |
stream_options | object | { "include_usage": true } is forced on for every stream. |
temperature | number | 0–2. |
top_p | number | 0–1. |
max_tokens | integer | Positive. Read the warning below before setting it. |
stop | string | string[] | At most 4 strings. |
tools | array | Any array of tool objects — see the note below. |
tool_choice | string | object | auto, none, required, or a named function. |
reasoning_effort | string | none, low, high or max. See below. |
Reasoning effort
kimi-k3 thinks before it answers, and reasoning_effort decides how much:
{
"model": "kimi-k3",
"messages": [{ "role": "user", "content": "Plan a database migration." }],
"reasoning_effort": "high"
}| Value | Effect |
|---|---|
none | No reasoning. Fastest and cheapest; best for extraction and rewriting |
low | Brief reasoning |
high | Extended reasoning |
max | Deepest reasoning. Slowest and most expensive |
Higher effort means more reasoning tokens, and reasoning tokens are billed as output — the expensive direction, at 5× the input rate. Lower effort is faster and cheaper.
Measure the trade-off with usage.completion_tokens, which always includes reasoning. Asking
kimi-k3 for 17 × 23 cost 8 completion tokens at none and 53 at high — the same correct answer,
6× the output. Some responses also break the figure out under
usage.completion_tokens_details.reasoning_tokens, but the provider does not populate that on every
response (both calls above reported 0 there), so do not build a cost model on it.
Omit the field to let the model use its own default. That is not the same as "none", which
actively asks it not to reason. An unknown value is rejected with a 400 naming the four allowed
options.
A key can carry a default, set on the API keys page , which
applies whenever a request does not send reasoning_effort. An explicit value in the request
always wins — see Authentication.
Tool entries are forwarded exactly as sent. The gateway checks only that tools is an array of
objects and that tool_choice is a string or an object; it imposes no per-type shape. A
{"type": "function", …} definition, a bare {"type": "web_search"}, a provider extension carrying
keys we have never seen — all pass through untouched, and the model decides what it supports. If it
does not support a tool type, its own error comes back as a
502 upstream_error carrying the provider’s message.
Unlisted parameters are forwarded unchanged. seed, presence_penalty, frequency_penalty,
response_format, parallel_tool_calls, user and anything else the provider accepts pass
straight through — the gateway validates what it knows and does not strip the rest, so SDK
features keep working without waiting on us.
Message roles
| Role | Use |
|---|---|
system | Instructions that frame the conversation |
user | Input from the person |
assistant | A previous model reply, including one carrying tool_calls |
tool | The result of a tool call; needs tool_call_id |
content may be a string, null (on assistant turns that only call tools), or an array of parts
for image input — see Models for what the model does with them and how they
are billed:
{
"role": "user",
"content": [
{ "type": "text", "text": "What is in this image?" },
{ "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0..." } }
]
}Response
{
"id": "chatcmpl-...",
"object": "chat.completion",
"created": 1787058728,
"model": "kimi-k3",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "The weather in Izmir right now is 31°C and sunny.",
"reasoning_content": "The tool returned 31°C and sunny, so I will report that."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 200,
"completion_tokens": 115,
"total_tokens": 315
}
}finish_reason is stop when the model finished, tool_calls when it wants a tool run, or
length if it hit a token cap.
Reasoning content
Kimi K3 thinks before it answers, and returns that thinking separately.
"message": {
"content": "Hello there, how are you?",
"reasoning_content": "The user asked for exactly five words. Let me count: Hello(1) there(2)..."
}contentis the answer. Show it to users.reasoning_contentis the thinking. It is not addressed to the user. Hide it, or put it behind a “Thinking” toggle the way the Devotel chat app does.- Do not send
reasoning_contentback in later turns. Sendroleandcontentonly.
Reasoning tokens are output tokens
Reasoning is counted inside completion_tokens and billed at the output rate. Some responses also
break it out:
"usage": {
"prompt_tokens": 94,
"completion_tokens": 799,
"total_tokens": 893,
"completion_tokens_details": { "reasoning_tokens": 782 }
}That is a real measurement: a “write a haiku about proxies” request spent 782 reasoning tokens to produce a 72-character poem. Budget accordingly — short answers are not cheap answers with this model.
Be careful with max_tokens. The cap covers reasoning and the answer. Set it too low and
the model spends the budget thinking, then gets cut off with finish_reason: "length" and an
empty content. If you do not have a specific reason to cap output, leave max_tokens unset —
that is what the Devotel chat app does.
Reasoning models and max_tokens
kimi-k3 is not the only model that thinks before it answers. The models below were measured
sending a hidden reasoning pass even with no reasoning_effort field in the request at all:
| Model | Reasons with no reasoning_effort sent |
|---|---|
kimi-k3 | Yes |
glm-5.2 | Yes |
glm-5.3 | Yes |
kimi-k2.6 | Yes |
deepseek-4-flash | No |
qwen3.8-max | No |
Only models someone has actually sent a trivial, tightly-capped request to are listed here — the rest of the catalogue has not been checked either way. Measured October 3, 2026.
For a model in the “Yes” column, a small max_tokens can come back with no answer. The cap covers
the hidden reasoning pass and the visible answer out of the same budget — cut off mid-thought,
most of these models return exactly this:
{
"choices": [
{
"finish_reason": "length",
"message": { "content": null, "reasoning_content": "The user wants me to reply with..." }
}
]
}That is a real 200, with real billed tokens, and no visible answer — indistinguishable from “no
answer” to any code that reads message.content without checking finish_reason first.
Traced live (2026-10-03) from two developer reports of models “returning no answer”: reproduces on
demand, identically whether the request goes direct to DigitalOcean or through this gateway — not
an outage, not a gateway bug, just this budget interaction.
Two fixes. Either is enough on its own:
- Set
max_tokensto at least 1024, or leave it unset entirely — give the model room to finish thinking and still have budget left to answer. - Send
"reasoning_effort": "none"— skips the hidden pass. Confirmed live: the same models above answer immediately even atmax_tokens: 16once this is set.
kimi-k3 behaves a little better than the rest of the “Yes” column: a cutoff lands the partial
THINKING text in content itself (see the warning above) rather than leaving it null — never
silently empty, just an unhelpful fragment. The same two fixes still apply.
Cached prompt tokens
The provider reports prompt-cache activity when it applies. These fields pass through untouched and vary by request:
"usage": {
"prompt_tokens": 200,
"prompt_tokens_details": { "cached_tokens": 12 },
"cache_read_input_tokens": 0,
"cache_created_input_tokens": 0
}Treat them as informational — prompt_tokens and completion_tokens are what Devotel meters.
Request size
Request bodies are capped at 20 MB. Larger requests get 413.
Not available yet
/v1/embeddings, /v1/completions (the legacy endpoint) and image generation are not implemented.
Unknown paths return 404 with code unknown_url.