API reference
Messages (Anthropic-compatible)
POST /v1/messages
POST /v1/messages/count_tokensThis endpoint accepts Anthropic Messages API requests and returns Anthropic-shaped responses, so Anthropic SDKs and tools built on them can call Utmost models. It runs through the same gateway as chat completions: routing, refusal retry, fallback, the hard-limit checks and metering all apply, and it returns the same response headers.
Pointing a client at Utmost
Anthropic clients add /v1/messages to the base URL themselves, so the base URL has no /v1:
export ANTHROPIC_BASE_URL=https://api.utmost.site
export ANTHROPIC_API_KEY=$UTMOST_API_KEY # sent as x-api-keyAuthorization: Bearer also works, so clients that send ANTHROPIC_AUTH_TOKEN as a bearer token work too.
Model names must be Utmost ids or aliases. Anthropic model names such as claude-sonnet-... are not mapped and return model_not_found. For Claude Code, set the model variables as well:
export ANTHROPIC_BASE_URL=https://api.utmost.site
export ANTHROPIC_API_KEY=$UTMOST_API_KEY
export ANTHROPIC_MODEL=auto-best
export ANTHROPIC_DEFAULT_OPUS_MODEL=auto-best
export ANTHROPIC_DEFAULT_SONNET_MODEL=auto
export ANTHROPIC_DEFAULT_HAIKU_MODEL=auto-fastPin a specific model, for example utmost/kimi-k3.1-pro, if you want every request on the same model. Coding agents send long contexts and many tool calls; the router sends those to larger tiers.
SDKs
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({ apiKey: process.env.UTMOST_API_KEY, baseURL: "https://api.utmost.site" });
const msg = await client.messages.create({
model: "auto",
max_tokens: 512,
messages: [{ role: "user", content: "Explain CSRF tokens briefly." }],
});
console.log(msg.content);import os
import anthropic
client = anthropic.Anthropic(api_key=os.environ["UTMOST_API_KEY"], base_url="https://api.utmost.site")
msg = client.messages.create(
model="auto",
max_tokens=512,
messages=[{"role": "user", "content": "Explain CSRF tokens briefly."}],
)
print(msg.content[0].text)Request
| Parameter | Notes |
|---|---|
model |
Required. Utmost model id or alias. |
max_tokens |
Required, positive. Lowered to the model's limit if larger. |
messages |
Required. user and assistant turns, with string content or blocks. |
system |
String or text blocks |
stop_sequences |
Up to 4 |
stream |
See Streaming |
temperature |
0 to 1 |
top_p |
|
top_k |
Accepted and ignored |
tools |
name, description, input_schema |
tool_choice |
auto, any (sent as required), tool with name, none |
thinking |
{"type": "enabled"} sets reasoning effort to high on models that support reasoning. budget_tokens is ignored. |
metadata |
Accepted and ignored |
Content blocks handled: text, image (with a base64 or url source), tool_use (assistant turns) and tool_result (user turns). Other block types, such as document, are dropped without an error. cache_control markers are ignored; caching is automatic.
Response
{
"id": "msg_8qIf9veeB5ibUPaz9j1zrcKR",
"type": "message",
"role": "assistant",
"model": "utmost/qwen3-30b-a3b",
"content": [{ "type": "text", "text": "A CSRF token is..." }],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": { "input_tokens": 12, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0, "output_tokens": 48 }
}contentcan holdthinkingblocks (reasoning models),textblocks andtool_useblocks.stop_reasonisend_turn,max_tokens,tool_useorrefusal.usage.input_tokensexcludes cached tokens;cache_read_input_tokensholds them.cache_creation_input_tokensis always 0.- The cost is in the
x-utmost-cost-usdheader. The body has no cost field.
Count tokens
curl https://api.utmost.site/v1/messages/count_tokens \
-H "x-api-key: $UTMOST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "auto", "messages": [{"role": "user", "content": "hello there"}]}'{ "input_tokens": 5 }The count is an estimate of about 4 characters per token, plus about 750 tokens per image, because backend tokenizers differ by model. It does not call a model, is not billed, and does not count against your rate limit. max_tokens is optional here.
Differences from the Anthropic API
- Model names are Utmost ids and aliases only.
thinkingblocks come back with an emptysignature. Sending them back in later turns is allowed; they are ignored.- Prompt caching is automatic.
cache_controlhas no effect and cache writes are not reported. - No server tools. A server tool definition (web search, code execution) is passed to the model as an ordinary function tool, and nothing executes it. No Files API, no
documentblocks, and no batches on this endpoint. Use/v1/batchesfor batch work. count_tokensis an estimate.- The
anthropic-versionandanthropic-betaheaders are accepted and ignored.
Errors
Errors use the Anthropic envelope, with our code added:
{
"type": "error",
"error": { "type": "not_found_error", "message": "No model named `claude-sonnet-4-5`. See GET /v1/models.", "code": "model_not_found" },
"request_id": "req_GnYON0D6sz5T6Fg9a26dIsMK"
}See Errors for every code.