Skip to Content
Chat Completions

Chat Completions

POST https://api.devotel.com/v1/chat/completions

The one endpoint you need. Request and response shapes match the OpenAI Chat Completions API.

Request parameters

These are validated by the gateway:

ParameterTypeNotes
modelstring, requiredkimi-k3. See Models.
messagesarray, requiredAt least one message. Roles below.
streambooleantrue for SSE. See Streaming.
stream_optionsobject{ "include_usage": true } is forced on for every stream.
temperaturenumber0–2.
top_pnumber0–1.
max_tokensintegerPositive. Read the warning below before setting it.
stopstring | string[]At most 4 strings.
toolsarrayAny array of tool objects — see the note below.
tool_choicestring | objectauto, none, required, or a named function.
reasoning_effortstringnone, 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" }
ValueEffect
noneNo reasoning. Fastest and cheapest; best for extraction and rewriting
lowBrief reasoning
highExtended reasoning
maxDeepest 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

RoleUse
systemInstructions that frame the conversation
userInput from the person
assistantA previous model reply, including one carrying tool_calls
toolThe 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)..." }
  • content is the answer. Show it to users.
  • reasoning_content is 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_content back in later turns. Send role and content only.

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:

ModelReasons with no reasoning_effort sent
kimi-k3Yes
glm-5.2Yes
glm-5.3Yes
kimi-k2.6Yes
deepseek-4-flashNo
qwen3.8-maxNo

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_tokens to 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 at max_tokens: 16 once 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.