Skip to content
tenvoralpha
GuidesChat Completions

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_bytes in 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.

Request fields
FieldsRule
model, messagesUse a served model and an ordered text conversation.
stream, stream_optionsstream 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_tokensPositive 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, seedRanges: 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_penaltyPresence 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.
stopOne 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_callFunction 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_formattext, 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_formatSee 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_effort thinking levels, with the thinking returned as reasoning_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.

What comes backsample, abridged200 OK
{
  "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": …
  }
}
The receipt: the billing object of the response above
full_input_tokens14Tokens you sent, at the full input rate.
cached_input_tokens0Input 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_tokens9Tokens 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.

Thinking levels
reasoning_effortThe model may think for
noneNot at all. This is the default.
lowUp to 1,024 tokens.
mediumUp to 4,096 tokens.
highUp to 8,192 tokens.
xhighUp to 16,384 tokens. API only.
maxAs 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_tokens and charged at the output rate, even when the reply ends with no answer. usage has no separate count for it. A few extra tokens that mark where the thinking starts and ends are counted too.
  • The reply limit. max_tokens limits 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; for max it is floor(0.8 × O). A limit of 2,000 allows at most 1,600 tokens of thinking, even with high or max.
  • A reply can end while the model is still thinking. With a small max_tokens the finish_reason can be length and content empty. The model can also stop on its own before it closes its thinking: finish_reason is stop, content is empty and tenvor_reasoning.completed is false. reasoning_content then holds what the model thought, and the reply is billed like any other, because the tokens were generated. Ask again with a larger max_tokens or 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, JSON response_format and a tool_choice that 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_content back 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-Key is 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.

Errors from the API
StatusCode or typeMeaning
400invalid_json, unknown_parameter, unsupported_parameter, unsupported_value, invalid_type, invalid_value, missing_required_parameter, conflicting_parameters, unsupported_combinationInvalid request. The field path is in param.
400invalid_message_order, unsupported_content_type, unsupported_tool_type, invalid_tool_schema, invalid_response_formatUnsupported message, content, tool or schema.
400context_length_exceeded, completion_limit_exceeded, max_tokens_too_small_for_reasoningThe input does not fit, an output allowance is refused, or thinking has fewer than 256 output tokens. Oversized output is normally clamped.
401missing_api_key, invalid_api_keyMissing, disabled or invalid credentials.
402insufficient_quotaAvailable balance cannot cover the reservation. details may include required_reservation_micro_usd.
403client_account_requiredThis route requires a client account.
404model_not_found, result_not_found, job_not_found, unsupported_endpoint, unknown_endpointModel, result, job or endpoint not found.
405method_not_allowedUse a method from Allow.
408request_timeoutReading the request body timed out.
409idempotency_conflictThe key was used for different input.
413request_too_largeRequest exceeds the input byte bound.
422request_output_limitA 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.
429concurrent_job_limit, concurrent_reasoning_limitAnother account job or heavy thinking job is active. Retry-After is 1 or 5 seconds respectively. The account job limit is checked first.
429server_busyThe server is at its limit of running requests. Nothing was started or charged. Retry-After is 5 seconds.
429rate_limit_errorRequest limiter. Wait for Retry-After.
503capacity_queue_expired, payment_unavailable, no_node_available, service_draining, stream_unavailableCapacity, 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.
503no_node_availableNo 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.