Documentation · Reference
Chat Completions API
Tenvor answers the OpenAI Chat Completions request. This page lists what you can send, what comes back, how streaming ends, and what each error means.
Endpoint and key
- Base URL
https://orchestrator.tenvor.io/v1- Chat
POST /v1/chat/completions- Header
Authorization: Bearer sk-dc-…- Body
Content-Type: application/json, within the model's input limit (max_input_bytesin the public catalog)- Models
GET /v1/models
Give your SDK the base URL, not the full chat address. Create a key in the Console. It can spend your balance, so keep it in an environment variable or your secret store.
The request
Send one JSON object. Duplicate keys are refused. Optional null fields mean absent. model and messages are required. Integers must use integer JSON notation.
| Fields | Rule |
|---|---|
model, messages | Use a served model and an ordered text conversation. |
stream, stream_options | stream is boolean. stream_options requires stream:true. include_usage adds the usage event. include_obfuscation is a boolean with no effect. |
max_tokens, max_completion_tokens | Positive integers. If both are present they must be equal. The output limit is clamped to the safe remainder of the context. X-Tenvor-Output-Limit gives requested and applied limits when clamped. |
temperature, top_p, top_k, min_p, seed | Ranges: temperature 0–2; top_p and min_p 0–1; top_k 1–100000; seed 0–4294967294. top_k and seed are independent. Defaults are temperature 0.8 and top_p 0.95. Thinking also defaults top_k to 20 and min_p to 0. |
presence_penalty, frequency_penalty, repetition_penalty, repeat_penalty | Presence and frequency range from -2 to 2 over a fixed 64-token window. Repetition is greater than 0 and at most 2. repeat_penalty is an alias; two values must agree. |
stop | One string or at most four. Each is nonempty, at most 256 bytes and has no NUL. Refused with thinking. |
tools, tool_choice, parallel_tool_calls, functions, function_call | Function tools. Legacy functions and function_call map to tools and tool_choice. Do not combine the two forms. With no tools, auto and none become none; parallel_tool_calls is dropped. |
response_format | text, json_object or json_schema. JSON uses the supported schema subset. JSON with active tools or thinking is refused. |
reasoning_effort, reasoning, thinking, enable_thinking, thinking_budget, chat_template_kwargs, include_reasoning, reasoning_format | See Thinking for limits, aliases and conflicts. |
These fields are accepted and have no effect: n:1, logprobs:false, top_logprobs:null, logit_bias:{}, user, safety_identifier, prompt_cache_key, prompt_cache_retention, metadata, store, service_tier, modalities and verbosity. The four identifier/cache fields are strings. metadata maps strings to strings; store is boolean. service_tier accepts auto or default; modalities accepts only ["text"]; verbosity accepts low, medium or high.
X-Tenvor-Ignored-Parameters names accepted fields with no effect, including stream_options.include_obfuscation. Optional null values are absent. n above one, logprobs:true, non-null top_logprobs and nonempty logit_bias are refused. audio, prediction and web_search_options are refused unless null. Unknown fields return 400 unknown_parameter. The error param names the field; messages name supported replacements where available.
Order your messages
Leading system and developer messages merge into one system message. A later system or developer message returns 400 invalid_message_order. The last message must be user or tool. Every tool result must match an open tool call. Empty assistant placeholders are removed. Text parts join with newlines; other content types return unsupported_content_type. Function-role messages and assistant function_call are refused; use tool_calls. Message name, refusal, annotations, cache_control and reasoning_details have no effect.
What works today
Works today
- Chat completions
- System, user and assistant messages
- Streaming
- Function tools, run by your code
temperature,top_p,stop,max_tokens- Idempotency keys
- Usage and charge for every request
- Fetch a result again by its id
- JSON mode, structured output and sampler controls
reasoning_effortthinking levels, with the thinking returned asreasoning_content
Not yet
- Image input
- Embeddings
- Audio
Unsupported fields are refused. Accepted fields with no effect are named in X-Tenvor-Ignored-Parameters.
The response and its receipt
A request that does not stream gets one JSON body. billing in it is the itemised receipt.
{
"id": "chatcmpl-…",
"object": "chat.completion",
"model": "chat-35b-moe",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! How can I help you today?"
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 14,
"completion_tokens": 9,
"total_tokens": 23
},
"billing": {
"full_input_tokens": 14,
"cached_input_tokens": 0,
"output_tokens": 9,
"charged_micro_usd": …
}
}full_input_tokens | 14 | Tokens you sent, at the full input rate. |
|---|---|---|
cached_input_tokens | 0 | Input tokens billed at the cached rate, half the full input rate. It reads 0 on a first request and on any request that did not ask for reuse. |
output_tokens | 9 | Tokens in the reply. |
charged_micro_usd | … | What you are charged, in millionths of a dollar: 1,000,000 is $1. The rates are on Pricing. |
The response header X-Request-Id is the id of this request. Keep it: it is how you fetch the result again.
usage contains prompt_tokens, prompt_tokens_details.cached_tokens, completion_tokens and total_tokens. Thinking is included in completion_tokens. There is no completion_tokens_details or reasoning_tokens count. tenvor_reasoning reports level, budget_tokens, effective_budget_tokens, completed and reasoning_bytes. Max reports null budget_tokens and effective_budget_tokens, although its thinking still stops at four fifths of max_tokens. X-Tenvor-Reasoning reports the level, budget and exclusion setting.
Streaming
Send "stream": true and the reply arrives as server-sent events. Each event is a chat.completion.chunk. The first carries the assistant role, then come the text chunks, then a chunk with the finish_reason. With "stream_options": {"include_usage": true} one more event follows, with an empty choices list and the usage. The stream ends with data: [DONE].
While a node works, a comment line (: keep-alive) can arrive about every 15 seconds. Ignore it. The assistant-role event and the keep-alive comments are not model output.
Tenvor does not promise one update per token, text straight away, or an even pace. A stream can stay quiet for a while before its first text, so build your interface and your timeouts for that.
The receipt of a streamed request
A streamed response ends with token usage, not the itemised receipt. Fetch the receipt at GET /v1/results/{id}, with the id from the X-Request-Id response header.
A finish_reason ends a completed stream. A failure ends with an error event then [DONE]. inference_failed is a failed job; request_output_limit includes paid usage and billing. stream_interrupted may follow a charged completion. Fetch the stored result if delivery is interrupted. A stream that fails after output has started is not retried, and Tenvor does not resume it. The finish chunk may carry tenvor_reasoning without reasoning_bytes. Closing a streaming connection requests cancellation.
Tools
Only function tools are accepted. tool_choice accepts none, auto, required or a named function. Tool arguments must be JSON-object strings. An empty string becomes {}. strict is accepted; the supported schema subset is enforced for every call. Unsupported schema keywords return invalid_tool_schema or invalid_response_format with details.keyword. Run tools in your code after the completed tool_calls terminal, then send matching tool results.
Thinking
The model can think before it answers. Send reasoning_effort to allow it, and say for how long. The value is a limit on the thinking, not how hard the model works, and the model often stops sooner. Leave it out and the model answers directly.
| reasoning_effort | The model may think for |
|---|---|
none | Not at all. This is the default. |
low | Up to 1,024 tokens. |
medium | Up to 4,096 tokens. |
high | Up to 8,192 tokens. |
xhigh | Up to 16,384 tokens. API only. |
max | As long as it needs, up to four fifths of max_tokens. |
The live levels and their limits are the reasoning entry in the public catalog and tenvor.reasoning in GET /v1/models.
Instant is none. The alias minimal means low. Boolean enable controls select Medium. Max has no thinking budget of its own, but the four-fifths rule applies to it.
Max has no thinking budget of its own. Thinking stops at four fifths of max_tokens, so the last fifth is kept for the answer. Set max_tokens high enough for both thinking and the answer.
After a forced close at the thinking budget, the model may keep reasoning in the answer. Two limits to know. A prompt that asks the model to write the literal text <think> can end the reply early with no answer, and you are still charged for what was generated. A prompt that quotes a literal </think> can make thinking text appear in the answer.
reasoning accepts effort, max_tokens, enabled and exclude. An empty object enables Medium. An explicit budget is 1,024 through 32,768 tokens. Do not send effort and max_tokens together in this object. Equal settings from different sources are allowed; different settings return 400 conflicting_parameters.
thinking accepts a boolean or an object with type enabled or disabled and an optional budget_tokens. enable_thinking accepts a boolean; thinking_budget requires enable_thinking:true. chat_template_kwargs accepts enable_thinking and preserve_thinking:true.
include_reasoning:false or reasoning.exclude:true hides thinking while it remains billed. reasoning_format accepts auto, deepseek or none. With none, the raw thinking stays inline in content. Exclusion takes precedence. reasoning_tokens is not reported.
The thinking comes back apart from the answer. A response has it in choices[0].message.reasoning_content. When you stream, it arrives as delta.reasoning_content events before the first content event, and the two never share an event. Both are there only when you asked for thinking. It is the model's working, not part of the answer, so show it or leave it out as you like.
- What it costs. Thinking is output. It is counted in
completion_tokensand charged at the output rate, even when the reply ends with no answer.usagehas no separate count for it. A few extra tokens that mark where the thinking starts and ends are counted too. - The reply limit.
max_tokenslimits the whole reply, thinking included, and must be at least 256 when thinking is on. For a bounded level, B_eff = min(B, floor(0.8 × O)), where O is the applied output limit; formaxit is floor(0.8 × O). A limit of 2,000 allows at most 1,600 tokens of thinking, even withhighormax. - A reply can end while the model is still thinking. With a small
max_tokensthefinish_reasoncan belengthandcontentempty. The model can also stop on its own before it closes its thinking:finish_reasonisstop,contentis empty andtenvor_reasoning.completedis false.reasoning_contentthen holds what the model thought, and the reply is billed like any other, because the tokens were generated. Ask again with a largermax_tokensor a lower level. - Stream from medium up. Thinking can take minutes. A stream shows it as it arrives and keeps the connection open: see streaming.
- One at a time. An account can have one heavy thinking request running at a time. Heavy means Max or an effective thinking budget of at least 8,192 tokens. The account job limit is checked first. A second job is refused with a 429. Chat, Work and API requests share the account.
- What it cannot be combined with. With thinking on,
stop, JSONresponse_formatand atool_choicethat forces a call ("required"or a named function) are refused with a 400. - Tools. The model may think before it calls a tool. While that call is open, send its
reasoning_contentback on the assistant message that carries it. Thinking on earlier turns is ignored, so you need not send it. - Idempotency keys. Changing normalized thinking settings under the same
Idempotency-Keyis a 409. Aliases with the same meaning are equivalent.
Fetch a result again
GET /v1/results/{id} returns the stored result. Use X-Request-Id or GET /v1/results with the same Idempotency-Key. Completed is 200; pending is 202 with Retry-After: 2; canceled is 200 with the charge; expired is 410. A failed result is 503 inference_failed, except a proven paid request_output_limit is 422 with usage and billing. Use include_reasoning=false to omit thinking from a stored response.
Results are kept for at least 30 days. There is no fixed deletion deadline for request content. Reusing an idempotency key replays the stored outcome; it does not run a failed job again.
A key protects against a duplicate charge for at least 30 days after its first accepted request. After that its record may be removed, and a later POST with the same key is then treated as a new request and may incur a new charge. Looking up a result by key (GET /v1/results) follows the same window, so keep the X-Request-Id: it finds the original request after the key's record is gone. Output availability is separate. This takes effect at general availability.
Without streaming, the server waits up to 4,100 seconds for the result and allows 10 seconds to write it. Prefer streaming for long replies. If delivery breaks, fetch the stored result with the same identity.
Errors
Errors have error.message, type, param and code. param names the field, or is null. Some errors include details. Read Retry-After before sending again.
| Status | Code or type | Meaning |
|---|---|---|
| 400 | invalid_json, unknown_parameter, unsupported_parameter, unsupported_value, invalid_type, invalid_value, missing_required_parameter, conflicting_parameters, unsupported_combination | Invalid request. The field path is in param. |
| 400 | invalid_message_order, unsupported_content_type, unsupported_tool_type, invalid_tool_schema, invalid_response_format | Unsupported message, content, tool or schema. |
| 400 | context_length_exceeded, completion_limit_exceeded, max_tokens_too_small_for_reasoning | The input does not fit, an output allowance is refused, or thinking has fewer than 256 output tokens. Oversized output is normally clamped. |
| 401 | missing_api_key, invalid_api_key | Missing, disabled or invalid credentials. |
| 402 | insufficient_quota | Available balance cannot cover the reservation. details may include required_reservation_micro_usd. |
| 403 | client_account_required | This route requires a client account. |
| 404 | model_not_found, result_not_found, job_not_found, unsupported_endpoint, unknown_endpoint | Model, result, job or endpoint not found. |
| 405 | method_not_allowed | Use a method from Allow. |
| 408 | request_timeout | Reading the request body timed out. |
| 409 | idempotency_conflict | The key was used for different input. |
| 413 | request_too_large | Request exceeds the input byte bound. |
| 422 | request_output_limit | A paid request hit its output cap before a required result. usage and billing describe the charge. A stream carries this as an error event, then [DONE]. Fetching the result returns 422 again. |
| 429 | concurrent_job_limit, concurrent_reasoning_limit | Another account job or heavy thinking job is active. Retry-After is 1 or 5 seconds respectively. The account job limit is checked first. |
| 429 | server_busy | The server is at its limit of running requests. Nothing was started or charged. Retry-After is 5 seconds. |
| 429 | rate_limit_error | Request limiter. Wait for Retry-After. |
| 503 | capacity_queue_expired, payment_unavailable, no_node_available, service_draining, stream_unavailable | Capacity, payment readiness, maintenance or service failure. Retry-After is 1 for capacity_queue_expired, 5 for payment_unavailable and no_node_available, and 15 for service_draining. stream_unavailable has no default retry delay. |
| 503 | no_node_available | No node that can serve the model is online, so the request did not reach a node. Wait for the Retry-After seconds. |
If a request fails on a node before any output is sent, Tenvor may retry it once on another node, if one is free. You are not charged for the attempt that failed. A retry is invisible to you. The request keeps its id, a stream carries on under that id, and you get one result and one receipt. Nothing in the response says a retry happened.
A retry is not a promise
A retry is not a promise that the request completes. It takes extra time, and it needs a second node that is free soon. A request is retried at most once, and never after you cancel it.
After admission, inference_failed is an error event. stream_interrupted means delivery was interrupted and can follow a charged completion. Fetch the stored result before deciding what happened. Neither a generic 503 nor a broken connection proves no charge.
Content checked . Live limits and prices can change.