API reference

Chat completions

POST /v1/chat/completions

OpenAI-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
  }
}
  • id is chatcmpl- followed by the request id.
  • model is the model that served the request, not the alias you sent.
  • usage.prompt_tokens includes cached tokens. usage.completion_tokens includes reasoning tokens.
  • usage.cost_usd is what the request cost, in USD.
  • message.reasoning_content is present on reasoning models that return their reasoning.
  • finish_reason is stop, length, tool_calls or content_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

  1. Authenticate the key and check its IP allowlist.
  2. Count the request against the key's per-minute limit.
  3. Check credit and the key's and project's spend caps.
  4. Plan the route: pinned model, or tier and variant for an alias.
  5. Check the input against the hard limits.
  6. Call the backend, with fallback before the first byte.
  7. Non-streaming only: retry a refusal on the abliterated variant, then check abliterated output against the hard limits.
  8. 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"
  }
}