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/sdkNode 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 utmostPython 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 usegetattr(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/batcheswith 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.