Tokun Docs

Sign in to the Tokun console, open API Keys, and click Create key. The full secret (sk-…) is shown exactly once — copy it immediately; only a short prefix is stored and displayed afterward. Keys are billed against your prepaid balance, so treat them like passwords.

Add a balance first under Billing (top-ups run $5–$1,000 via Stripe). A request with no balance returns 402 Payment Required.

curl:

curl https://api.tokun.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4-8",
    "messages": [{"role": "user", "content": "Say hello in one word."}]
  }'

OpenAI SDK (Python):

from openai import OpenAI

client = OpenAI(
    base_url="https://api.tokun.sh/v1",
    api_key="sk-...",  # your Tokun key
)

resp = client.chat.completions.create(
    model="anthropic/claude-opus-4-8",  # or "openai/gpt-5.5"
    messages=[{"role": "user", "content": "Say hello in one word."}],
)
print(resp.choices[0].message.content)

OpenAI SDK (Node):

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.tokun.sh/v1",
  apiKey: process.env.TOKUN_API_KEY, // your sk-... key
});

const resp = await client.chat.completions.create({
  model: "anthropic/claude-opus-4-8", // or "openai/gpt-5.5"
  messages: [{ role: "user", content: "Say hello in one word." }],
});
console.log(resp.choices[0].message.content);

Pass a Tokun model id in the model field. Ids follow the lab/model convention — the lab that made the model, then the model name. Tokun resolves the id to an upstream and routes the request; you never pass the upstream id directly.

Model ids are accepted flexibly so Claude Code and Codex work out of the box: you can send the lab/model id above or the bare model name on its own (claude-haiku-4-5, gpt-5.4-mini) — both resolve to the same offering. A trailing context-window selector ([1m]), a provider/region prefix (anthropic/, us.anthropic.), and a trailing date stamp are all tolerated and ignored. anthropic/claude-fable-5 is listed but not yet enabled (coming soon). An id that does not match a served model is rejected with unknown model — Tokun never silently substitutes a different model, so unsupported ids like gpt-5.5-codex or gpt-5.2 return an error rather than billing you for the wrong model.

Any agent runner that exposes an OpenAI base URL works. Set OPENAI_BASE_URL to the Tokun gateway and OPENAI_API_KEY to your sk-… key.

Codex — set the OpenAI env vars and choose a Tokun model:

export OPENAI_BASE_URL="https://api.tokun.sh/v1"
export OPENAI_API_KEY="sk-..."
# Then point Codex at a Tokun model id:
codex --model openai/gpt-5.5   # or: anthropic/claude-opus-4-8

OpenCLAW — point its OpenAI provider at the gateway (env or config):

OPENAI_BASE_URL=https://api.tokun.sh/v1
OPENAI_API_KEY=sk-...
OPENAI_MODEL=openai/gpt-5.5

Hermes — same OpenAI-compatible base URL + key; set the model to openai/gpt-5.5 or anthropic/claude-opus-4-8:

OPENAI_BASE_URL=https://api.tokun.sh/v1
OPENAI_API_KEY=sk-...
# model: anthropic/claude-opus-4-8

A single OpenAI-compatible endpoint that meters your usage and routes the model you asked for to an eligible upstream — across three kinds of providers, so the same model can be served more cheaply over time.

Every model can be served from one of three channel types. They serve the same model; they differ in who you are ultimately buying capacity from.

• Direct / official — the model owner or a first-party cloud. For anthropic/claude-opus-4-8 that is Anthropic directly; for cloud-hosted models it is a first-party cloud such as Google Vertex, Azure OpenAI, or AWS Bedrock. This is the canonical source.
• Resellers — aggregators that resell official capacity, e.g. OpenRouter or GMI. They sit between you and the official provider and typically price at or slightly above official.
• Discount providers — independent hosts that serve the same model below reseller/official pricing. These are the cheapest channel and are how Tokun lowers your bill.

Today (V0) both anthropic/claude-opus-4-8 and openai/gpt-5.5 route to their direct/official providers (Anthropic and OpenAI). Reseller and discount channels are part of the routing design and roll in over time; your usage records show who actually served each request.

Yes. A Tokun model id maps to one logical model (e.g. anthropic/claude-opus-4-8 → Claude Opus 4.8). Whichever channel serves it, the weights are the same model — the difference is the billing surface and price, not the model.

Prepaid and per-token. You top up a balance (USD, $5–$1,000 per top-up via Stripe), and each request draws down that balance by metered consumption: input tokens × the model's input rate + output tokens × the model's output rate, times any account multiplier. Prices are listed per 1M tokens (see the Models table).

Mechanically, Tokun places a balance hold for the request's estimated maximum cost before forwarding, then settles the exact charge from the upstream's reported token usage. If a request fails before the upstream responds, the hold is released and you are not charged.

Your prompts and completions pass through Tokun in transit to whichever upstream provider fulfills the request, and are processed transiently to operate and meter the Service. Tokun logs request metadata (timestamps, model, token counts, latency, status, which key) for billing and security — not the prompt/completion bodies as a product feature. The upstream provider that serves a request handles that content under its own terms and privacy policy. See the Privacy Policy.

Because Tokun can route the same model to a lower-cost channel (a discount provider or reseller) instead of always paying official list price, while still settling your bill at the Tokun list price for that model. You get one endpoint and one balance instead of negotiating with each provider yourself.

There is no fixed requests-per-second quota in the beta. The effective limits are economic: your prepaid balance and any per-key budget cap. A request is rejected with 402 when your balance is insufficient, or 403 when a key's budget is exhausted. Upstream providers may apply their own limits, surfaced as 429. This is a beta service with no uptime SLA.

It is the upstream provider that actually served a given request — the authoritative value reported by the routing layer (e.g. anthropic or openai). Tokun records it as the served_vendor usage dimension so you can see which channel/provider fulfilled each call. When a fanned-out request's upstream can't be determined, it is recorded as unattributed rather than left blank.

You pick the model (anthropic/claude-opus-4-8 / openai/gpt-5.5); Tokun picks the channel that serves it. In V0 that is the direct/official provider; as reseller and discount channels roll in, Tokun picks among them to lower cost. There is no per-request channel selector in the OpenAI request body today. The served_vendor on your usage records shows which channel was used after the fact. Explicit channel preference/filtering is a routing-policy feature, not a request parameter.

Yes. The gateway serves the Anthropic Messages API at POST /v1/messages (plus POST /v1/messages/count_tokens), so Anthropic SDK clients and Claude Code work: set ANTHROPIC_BASE_URL=https://api.tokun.sh and ANTHROPIC_API_KEY=sk-…, and pin a Tokun model id. See the Anthropic SDK / Claude Code section for the supported feature set (extended thinking is supported, with signed thinking blocks round-tripping on multi-turn tool use; image blocks are rejected).

POST /v1/chat/completions (buffered or streaming), POST /v1/responses (OpenAI Responses API, stateless), and POST /v1/messages (Anthropic Messages API) are the inference endpoints — all three run the same metering pipeline. POST /v1/messages/count_tokens returns a free token estimate. GET /v1/models lists the available model ids in the OpenAI format (same Authorization: Bearer key; listing is free). There is no /v1/embeddings surface today. The gateway also exposes /healthz and /readyz for liveness only.