API reference

Messages (Anthropic-compatible)

POST /v1/messages
POST /v1/messages/count_tokens

This 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-key

Authorization: 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-fast

Pin 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 }
}
  • content can hold thinking blocks (reasoning models), text blocks and tool_use blocks.
  • stop_reason is end_turn, max_tokens, tool_use or refusal.
  • usage.input_tokens excludes cached tokens; cache_read_input_tokens holds them. cache_creation_input_tokens is always 0.
  • The cost is in the x-utmost-cost-usd header. 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.
  • thinking blocks come back with an empty signature. Sending them back in later turns is allowed; they are ignored.
  • Prompt caching is automatic. cache_control has 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 document blocks, and no batches on this endpoint. Use /v1/batches for batch work.
  • count_tokens is an estimate.
  • The anthropic-version and anthropic-beta headers 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.