SDKs

SDKs

You have two options:

  • Official OpenAI or Anthropic SDKs. Change the base URL and key. Best when you already use them, or need their helpers.
  • Utmost SDKs for TypeScript and Python. Small, with no dependencies. They return the served model, route and cost with every response, and cover the Utmost-only endpoints: batches, workflows, bring your own model, credits and feedback.

Utmost TypeScript SDK

npm install @utmost/sdk

Node 18+, Deno, Bun or a modern browser. No runtime dependencies.

import { Utmost, UtmostError } from "@utmost/sdk";

const client = new Utmost({
  // apiKey: defaults to process.env.UTMOST_API_KEY
  // baseURL: defaults to process.env.UTMOST_BASE_URL, then https://api.utmost.site/v1
  timeoutMs: 120_000, // per attempt; default 10 minutes
  maxRetries: 3,      // default 2
});

const { data, meta } = await client.chat.completions.create({
  model: "auto",
  messages: [{ role: "user", content: "List three OWASP Top 10 categories." }],
});
console.log(data.choices[0].message.content);
console.log(meta.requestId, meta.model, meta.route, meta.fallback, meta.costUsd);

Streaming

const stream = await client.chat.completions.create({
  model: "auto",
  stream: true,
  messages: [{ role: "user", content: "Write a haiku about latency." }],
});
for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta.content ?? "");
console.log("\n", stream.meta.model, stream.meta.costUsd, stream.usage);

The SDK sets stream_options.include_usage for chat completions, so stream.usage and stream.meta.costUsd are filled in when the loop ends. responses.create({ stream: true }) and messages.create({ stream: true }) work the same way and yield their own event types.

Other resources

await client.responses.create({ model: "auto", input: "Hello", store: false });
await client.messages.create({ model: "auto", max_tokens: 256, messages: [{ role: "user", content: "Hello" }] });
await client.models.list();                         // no key needed
await client.models.retrieve("utmost/qwen3-30b-a3b");
await client.credits.retrieve();
await client.feedback.create({ request_id: meta.requestId!, rating: "bad", reason: "refused" });

const batch = await client.batches.create({
  requests: [{ custom_id: "a", body: { model: "auto", messages: [{ role: "user", content: "one" }] } }],
});
for await (const row of client.batches.results(batch.id)) console.log(row.custom_id, row.error ?? row.response?.body.choices[0].message.content);

await client.workflows.securityReview({ template: "code-review", input: source });
await client.byo.create({ source: { type: "huggingface", repo: "Qwen/Qwen3-8B" }, name: "qwen3-8b-redteam" });

Pass per-request options as the second argument: { headers, signal, timeoutMs, maxRetries, variant }. variant sends x-utmost-variant.

Utmost Python SDK

pip install utmost

Python 3.8+, standard library only.

from utmost import Utmost, UtmostError

client = Utmost(timeout=120, max_retries=3)  # api_key from UTMOST_API_KEY

r = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "List three OWASP Top 10 categories."}],
)
print(r.data["choices"][0]["message"]["content"])
print(r.meta.request_id, r.meta.model, r.meta.route, r.meta.cost_usd)

stream = client.chat.completions.create(model="auto", stream=True, messages=[{"role": "user", "content": "Hi"}])
for chunk in stream:
    if chunk["choices"]:
        print(chunk["choices"][0]["delta"].get("content") or "", end="")
print("\n", stream.meta.cost_usd)

for row in client.batches.results("batch_..."):
    print(row["custom_id"], row["error"] or row["response"]["body"]["choices"][0]["message"]["content"])

The method names are the snake_case versions of the TypeScript ones: messages.count_tokens, workflows.security_review, and so on. Responses are plain dicts. Per-request options are keyword arguments: extra_headers, timeout, max_retries, variant.

Errors and retries in the Utmost SDKs

Every failure raises UtmostError with status, code, type, request_id/requestId, param and headers. Network errors and errors sent mid-stream have status 0.

Situation Retried?
429 Yes, after retry-after (capped at 60 seconds)
500, 502, 503, 504 Yes, exponential backoff with jitter: about 0.5 s, 1 s, 2 s, up to 8 s
Timeouts and connection errors Yes, with the same backoff
402 and every other 4xx Never
A stream that has started Never. Only the initial request is retried.
try {
  await client.chat.completions.create({ model: "utmost/kimi-k3.1-pro-abl", messages });
} catch (e) {
  if (e instanceof UtmostError && e.code === "tier_required") {
    // apply for verification
  } else throw e;
}

Official OpenAI SDKs

import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.UTMOST_API_KEY, baseURL: "https://api.utmost.site/v1" });
from openai import OpenAI
client = OpenAI(api_key=os.environ["UTMOST_API_KEY"], base_url="https://api.utmost.site/v1")

Chat completions, Responses (including streaming and function tools) and the models list work. Reading Utmost extras:

  • Cost in the body: completion.usage.cost_usd. It is not in the SDK's types; in TypeScript cast it, and in Python use getattr(completion.usage, "cost_usd", None).
  • Headers: use .withResponse() (TypeScript) or .with_raw_response (Python):
const { data, response } = await client.chat.completions
  .create({ model: "auto", messages })
  .withResponse();
console.log(response.headers.get("x-utmost-model"), response.headers.get("x-utmost-cost-usd"));
raw = client.chat.completions.with_raw_response.create(model="auto", messages=messages)
print(raw.headers.get("x-utmost-model"), raw.headers.get("x-utmost-cost-usd"))
completion = raw.parse()
  • Variant override: pass extra_headers={"x-utmost-variant": "abliterated"} (Python) or { headers: { "x-utmost-variant": "abliterated" } } as request options (TypeScript).
  • Batches: use /v1/batches with the Utmost SDKs or plain HTTP. The OpenAI SDK's batch helpers expect the OpenAI Files API, which Utmost does not have.

Official Anthropic SDKs

The base URL has no /v1; the SDK adds it.

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({ apiKey: process.env.UTMOST_API_KEY, baseURL: "https://api.utmost.site" });
import anthropic
client = anthropic.Anthropic(api_key=os.environ["UTMOST_API_KEY"], base_url="https://api.utmost.site")

Use Utmost model ids or aliases. messages.create, messages.stream and messages.count_tokens work. See Messages for the differences from the Anthropic API.

OpenAPI

The OpenAPI 3.1 document describes every public endpoint, its schemas, response headers and error codes. Use it to generate a client in another language.