API reference
Chat completions
POST /v1/chat/completionsOpenAI-compatible. The official openai SDKs work with baseURL set to https://api.utmost.site/v1.
Request
curl https://api.utmost.site/v1/chat/completions \
-H "Authorization: Bearer $UTMOST_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"messages": [
{"role": "system", "content": "You are a concise security reviewer."},
{"role": "user", "content": "What does SameSite=Lax protect against?"}
],
"max_completion_tokens": 400
}'Parameters
These are the only parameters accepted. Unknown parameters are ignored. A null value is treated as not set.
| Parameter | Type | Notes |
|---|---|---|
model |
string | Required. A model id, or auto, auto-fast, auto-best. See Routing. |
messages |
array | Required, at least one. Roles: system, developer, user, assistant, tool. |
stream |
boolean | Stream the response as server-sent events. See Streaming. |
stream_options.include_usage |
boolean | Send a final chunk with usage, including cost_usd. |
tools |
array | Up to 128 function tools. See Tool calling. |
tool_choice |
string or object | none, auto, required, or {"type": "function", "function": {"name": "..."}} |
parallel_tool_calls |
boolean | |
response_format |
object | {"type": "text"}, {"type": "json_object"}, or {"type": "json_schema", "json_schema": {...}}. See Structured output. |
max_tokens |
integer | Positive. Lowered to the model's max_output_tokens if larger. |
max_completion_tokens |
integer | Same as max_tokens. |
temperature |
number | 0 to 2 |
top_p |
number | 0 to 1 |
stop |
string or array | Up to 4 sequences |
seed |
integer | |
n |
integer | 1 to 8 |
presence_penalty |
number | −2 to 2 |
frequency_penalty |
number | −2 to 2 |
logprobs |
boolean | Passed to the backend. Support varies by model. |
top_logprobs |
integer | 0 to 20 |
reasoning_effort |
string | none, minimal, low, medium, high. Dropped for models without reasoning support. See Reasoning. |
user |
string | Up to 256 characters. Passed to the backend. |
Message content is a string, null, or an array of parts. Text parts are {"type": "text", "text": "..."}. Image parts are {"type": "image_url", "image_url": {"url": "..."}}, for models that accept images.
The request body is limited to 8 MB.
Response
{
"id": "chatcmpl-req_vhX379RVYQlmrhnWrPHvHUfU",
"object": "chat.completion",
"created": 1795066905,
"model": "utmost/qwen3-30b-a3b",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "SameSite=Lax stops the browser from sending the cookie on most cross-site requests..." },
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 31,
"completion_tokens": 58,
"total_tokens": 89,
"prompt_tokens_details": { "cached_tokens": 0 },
"completion_tokens_details": { "reasoning_tokens": 0 },
"cost_usd": 0.000020
}
}idischatcmpl-followed by the request id.modelis the model that served the request, not the alias you sent.usage.prompt_tokensincludes cached tokens.usage.completion_tokensincludes reasoning tokens.usage.cost_usdis what the request cost, in USD.message.reasoning_contentis present on reasoning models that return their reasoning.finish_reasonisstop,length,tool_callsorcontent_filter, as reported by the backend.
Response headers
| Header | Meaning |
|---|---|
x-request-id |
The request id. Use it for feedback and support. |
x-utmost-model |
The model that served the request |
x-utmost-route |
Routing decision, for auto aliases only |
x-utmost-fallback |
The model tried first, present only after a fallback |
x-utmost-input-tokens |
Input tokens, including cached |
x-utmost-cached-tokens |
Input tokens served from the prefix cache |
x-utmost-output-tokens |
Output tokens, including reasoning |
x-utmost-cost-usd |
Cost in USD, six decimal places |
x-utmost-usage-estimated |
true when the backend reported no token counts and we estimated them |
x-ratelimit-limit-requests |
Your per-minute limit |
x-ratelimit-remaining-requests |
Requests left this minute |
x-ratelimit-reset-requests |
Time until the window resets, e.g. 15s |
Streamed responses send headers before any tokens are generated. They include x-request-id, x-utmost-model, x-utmost-route, x-utmost-fallback and the rate-limit headers, but not the token or cost headers. For a stream, read cost from the final usage chunk.
Estimated usage
If a backend returns no token counts, we estimate them at about 4 characters per token, bill the estimate, and set x-utmost-usage-estimated: true. The estimate can be off in either direction.
Streaming example
curl -N https://api.utmost.site/v1/chat/completions \
-H "Authorization: Bearer $UTMOST_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"stream": true,
"stream_options": {"include_usage": true},
"messages": [{"role": "user", "content": "Say hello"}]
}'data: {"id":"chatcmpl-req_R6xk...","object":"chat.completion.chunk","created":1795066905,"model":"utmost/qwen3-30b-a3b","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
data: {"id":"chatcmpl-req_R6xk...","object":"chat.completion.chunk","created":1795066905,"model":"utmost/qwen3-30b-a3b","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
data: {"id":"chatcmpl-req_R6xk...","object":"chat.completion.chunk","created":1795066905,"model":"utmost/qwen3-30b-a3b","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: {"id":"chatcmpl-req_R6xk...","object":"chat.completion.chunk","created":1795066905,"model":"utmost/qwen3-30b-a3b","choices":[],"usage":{"prompt_tokens":5,"completion_tokens":22,"total_tokens":27,"prompt_tokens_details":{"cached_tokens":0},"completion_tokens_details":{"reasoning_tokens":0},"cost_usd":0.000007}}
data: [DONE]TypeScript:
import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.UTMOST_API_KEY, baseURL: "https://api.utmost.site/v1" });
const stream = await client.chat.completions.create({
model: "auto",
stream: true,
stream_options: { include_usage: true },
messages: [{ role: "user", content: "Say hello" }],
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
if (chunk.usage) console.log("\ncost:", (chunk.usage as { cost_usd?: number }).cost_usd);
}Python:
import os
from openai import OpenAI
client = OpenAI(api_key=os.environ["UTMOST_API_KEY"], base_url="https://api.utmost.site/v1")
stream = client.chat.completions.create(
model="auto",
stream=True,
stream_options={"include_usage": True},
messages=[{"role": "user", "content": "Say hello"}],
)
for chunk in stream:
if chunk.choices:
print(chunk.choices[0].delta.content or "", end="")
if chunk.usage:
print("\ncost:", getattr(chunk.usage, "cost_usd", None))What runs, in order
- Authenticate the key and check its IP allowlist.
- Count the request against the key's per-minute limit.
- Check credit and the key's and project's spend caps.
- Plan the route: pinned model, or tier and variant for an alias.
- Check the input against the hard limits.
- Call the backend, with fallback before the first byte.
- Non-streaming only: retry a refusal on the abliterated variant, then check abliterated output against the hard limits.
- Record usage and cost, and debit your balance.
A non-streaming request that ends in an error is not billed. A stream that fails or is closed part-way is billed for the tokens generated up to that point.
Errors
Errors use the OpenAI envelope. See Errors for every code.
{
"error": {
"message": "`messages`: Too small: expected array to have >=1 items",
"type": "invalid_request_error",
"code": "invalid_request",
"param": "messages",
"request_id": "req_RzE3FrFnAoh3Kc9gpMp0bsZI"
}
}