Docs

What is Tokun?

One API, compatible with OpenAI and Anthropic clients, that meters your usage and routes each request to an eligible provider for the model you chose. Tokun routes across three kinds of providers, so the same model can be served at a lower cost.

Is it really the same model?

An individual model ID maps to one model (for example, anthropic/claude-opus-4-8 is Claude Opus 4.8). Whichever provider serves it, you get the same model at the same published rate. An official pool ID selects a member using that pool's routing rules. When you select a member explicitly, only that member can execute.

Set up with an AI assistant

Paste this prompt into your coding agent, such as Claude Code, Codex, or Cursor. It reads the setup guide at /llms.txt and configures Tokun for you. You only need to provide your API key.

Read https://tokun.sh/llms.txt and integrate Tokun into this project.

Set up manually

Change two settings: the base URL and the API key.

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."}]
  }'

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)

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);

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

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

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

What changes

Tokun supports the OpenAI and Anthropic API formats, so you only need to update your connection settings. For a standard text request, change these three values and keep the rest:

• Base URL: https://api.tokun.sh/v1 for OpenAI clients, or https://api.tokun.sh (no /v1) for Anthropic clients.
• API key: your Tokun sk- key, not your OpenAI or Anthropic key.
• Model: a Tokun model ID in lab/model format, such as openai/gpt-5.5.

From OpenAI

Keep the official OpenAI SDK. Set the base URL and key in the client constructor or with the OPENAI_BASE_URL / OPENAI_API_KEY environment variables, then pass a Tokun model ID. The OpenAI base URL keeps its /v1 suffix.

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="openai/gpt-5.5",       # a Tokun lab/model id
    messages=[{"role": "user", "content": "Say hello in one word."}],
)

To avoid a code change, use environment variables. The OpenAI SDK reads both:

export OPENAI_BASE_URL="https://api.tokun.sh/v1"
export OPENAI_API_KEY="sk-..."

From Anthropic / Claude Code

Keep the Anthropic SDK or Claude Code. Set ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY (a Tokun key), and pass a Tokun model ID. The Anthropic base URL has no /v1 suffix because the SDK adds the path itself.

export ANTHROPIC_BASE_URL="https://api.tokun.sh"   # no /v1
export ANTHROPIC_API_KEY="sk-..."            # your Tokun key

# Claude Code, pinned to a Tokun model:
claude --model anthropic/claude-opus-4-8

Model IDs

Tokun model IDs use a lab/model format. Replace your provider's model name with the matching Tokun ID. The Models page lists every ID and its price.

• OpenAI GPT models → openai/gpt-5.5 (and the other openai/* IDs).
• Anthropic Claude models → anthropic/claude-opus-4-8 (and the other anthropic/* IDs).

What stays the same

• For supported text requests, request and response formats are byte-compatible with the official APIs, so your parsing code doesn't change.
• Streaming ("stream": true / SSE) and tool or function calling work exactly as before.
• The Anthropic event protocol round-trips signed thinking blocks in multi-turn tool use.
• Your SDK, retry, and timeout logic stay as they are.

Test your setup

Send one request, then check that it appears in your usage in the console:

curl https://api.tokun.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.5",
    "messages": [{"role": "user", "content": "Say hello in one word."}]
  }'

Troubleshooting

Official model pools

Official model pools appear in the model catalog and use a pool ID such as flash-pool. Choose an available pool from the live catalog; pool names and members are configured by Tokun administrators.

When the pool enables member selection, use pool-id/member-name, replacing the model's lab prefix with the pool ID. The selected member is the only model that can execute; the pool's pricing mode still applies. When selection is disabled, this form returns 400.

# Set TOKUN_API_KEY and TOKUN_POOL_ID from your account and the live catalog.
curl "${TOKUN_BASE_URL:-https://api.tokun.sh/v1}/chat/completions" \
  -H "Authorization: Bearer $TOKUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$TOKUN_POOL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}],\"max_tokens\":64}"

# The pool must enable member selection. TOKUN_MEMBER is the member name without its lab prefix.
curl "${TOKUN_BASE_URL:-https://api.tokun.sh/v1}/chat/completions" \
  -H "Authorization: Bearer $TOKUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$TOKUN_POOL_ID/$TOKUN_MEMBER\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}],\"max_tokens\":64}"

Every pool response echoes the model ID you sent: the pool ID for an automatic request, and pool-id/member-name when you selected a member. The canonical ID of the member that served the request travels in the tokun-resolved-model header, and in executed_public_model on the usage record. Your bill follows the configured pool pricing mode.

A pool stays listed when every member is unavailable. Calling it returns 503; requests never leave the pool to find another model.

Pool api_surfaces is the union of its members' supported APIs. Each request uses a member that supports its API format. Context and output limits are the minimum curated values across members; unknown limits are omitted. Pool count_tokens uses the first supported Anthropic member in routing order and returns its tokenizer count without a charge.

Lists the available model IDs and each model's context window. The response format follows the request: a caller that sends x-api-key or anthropic-version (as Anthropic clients do) gets Anthropic's list format; every other caller gets OpenAI's list format. Listing is free (no charge, no hold).

What does "served by" / served_vendor mean?

It is the provider that actually served a request, as reported by Tokun's routing layer (for example, anthropic or openai). Tokun records it as the served_vendor field on your usage, so you can see which provider handled each call. If the provider for a fanned-out request can't be determined, it is recorded as unattributed rather than left blank.

Can I use the Anthropic API format / Claude Code?

Yes. Tokun serves the Anthropic Messages API at POST /v1/messages (plus POST /v1/messages/count_tokens). To use an Anthropic SDK client or Claude Code, set ANTHROPIC_BASE_URL=https://api.tokun.sh and ANTHROPIC_API_KEY=sk-…, and set a Tokun model ID. Extended thinking is supported, with signed thinking blocks round-tripping in multi-turn tool use; image blocks are rejected. For setup steps, see Use Tokun with Claude Code.

Tokun also serves the Anthropic Messages API (POST /v1/messages). To use an Anthropic SDK client, including Claude Code, change the base URL and API key. Authenticate with the x-api-key header (Authorization: Bearer also works) and your sk-… key. The base URL has no /v1 suffix because the Anthropic SDK adds the path itself.

Claude Code: point it at Tokun and set a Tokun model ID:

export ANTHROPIC_BASE_URL="https://api.tokun.sh"
export ANTHROPIC_API_KEY="sk-..."
export ANTHROPIC_MODEL="anthropic/claude-opus-4-8"
claude

Anthropic SDK (Python):

import anthropic

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

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

Use Tokun model IDs (anthropic/claude-opus-4-8, openai/gpt-5.5). The API format and the model are independent, so the Anthropic SDK can call GPT models through this API too. Bare Anthropic model IDs (claude-opus-4-8, claude-haiku-4-5) resolve to the same model, so Claude Code's default model and /model picker work without a Tokun ID. An ID with no served match returns invalid_request_error; Tokun never substitutes a different model.

• Supported: text conversations (buffered and streaming), system prompts (string or text blocks), client tools (tools / tool_use / tool_result), tool_choice, stop_sequences, temperature / top_p, POST /v1/messages/count_tokens (free, returns a conservative estimate). Prompt caching (cache_control) is honored and billed at cache rates on routes served in Anthropic's native format, and accepted but ignored on routes bridged to OpenAI Chat Completions.
• Extended thinking is supported. Enable it with thinking: {type:"enabled", budget_tokens} (validated like the official API: budget ≥ 1024 and < max_tokens) or the output_config.effort setting. Responses include signed thinking blocks before the text (streaming emits thinking_delta / signature_delta events), and replayed thinking blocks round-trip upstream in multi-turn tool use. Extended thinking is forwarded unchanged whichever provider serves the request; nothing is stripped at runtime.
• Not supported (rejected with invalid_request_error): image / document blocks, server tools other than Anthropic web search (e.g. code execution), mcp_servers, structured outputs via the deprecated top-level output_format (use output_config.format, which is supported). Anthropic web search is the exception: it is supported and billed on routes served in Anthropic's native format. max_tokens is required, as in the official API.
• Errors use Anthropic's error format (authentication_error, invalid_request_error, billing_error on 402, …) with the same HTTP statuses as the OpenAI-compatible API.

Integration guides

• Claude Code
• Codex CLI
• Cursor
• Cline
• Roo Code
• Kilo Code
• Continue
• Zed
• OpenCode
• Aider

Who actually serves my request?

A model can be served by several kinds of provider. The model is the same on each; what differs is who provides the capacity.

• First-party: the model's developer or a first-party cloud. For anthropic/claude-opus-4-8 that is Anthropic; for cloud-hosted models it is a first-party cloud such as Google Vertex, Azure OpenAI, or AWS Bedrock.
• Resellers: aggregators that resell official capacity, such as OpenRouter or GMI.
• Independent providers: hosts that serve the same model at their own cost.

For an individual model, which provider serves your request does not change what you pay: the model has one published rate, the same on every API key. Model pools are priced by their own pricing mode. Your usage records show which provider served each request.

How can Tokun cost less?

Tokun can source the same model from a lower-cost provider instead of always paying the official list price, and publishes one price for that model regardless of who serves it. You get one API and one balance instead of arranging access with each provider yourself.

Can I choose which provider serves my request?

No. You choose the model (anthropic/claude-opus-4-8 or openai/gpt-5.5), and Tokun selects an eligible provider for it. There is no per-request provider selector, and a key you create carries no routing-channel setting. For an individual model, which provider served the request does not change what you pay. The served_vendor field on your usage records shows which provider was used.

How do pricing and billing work?

Billing uses a prepaid USD balance ($5–$1,000 per top-up, through Stripe). Individual models use their token rates. Model pools use one of three modes: fixed pool token rates for every member, the serving member's frozen token rates, or a fixed price per request. Token prices are quoted in USD per 1M tokens; per-request prices are quoted in USD per request.

Before forwarding, Tokun places a balance hold for the estimated maximum cost. Token-priced requests settle from the serving model's reported usage: an individual model at its published token rates, a model pool according to its pricing mode. Fixed per-request pools charge once after an upstream success response begins, even if usage is missing, the response is partial or the client disconnects. Failures before success release the hold; unsuccessful retries add no per-request charge.

Are there rate limits?

There is no fixed requests-per-second quota during the beta. Your limits are your prepaid balance and any per-key budget cap. A request is rejected with 402 when your balance cannot cover it, or 403 when the key is over its own budget cap. Providers may apply their own limits, which surface as 429. Tokun is a beta service with no uptime SLA.

Base URL and authentication

Authenticate every request with a Tokun API key (starts with sk-) from the API keys page. The base URL depends on the API format you call:

If your client can't set an Authorization header, you can put the key in the URL path instead: POST /v1/{sk-key}/chat/completions.

POST /v1/chat/completions

The OpenAI Chat Completions API. Send a standard OpenAI request body with a Tokun model ID. Set "stream": true to stream tokens over SSE. Responses are byte-compatible with the official OpenAI format.

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."}]
  }'

POST /v1/responses

The OpenAI Responses API, with the same authentication and model IDs as Chat Completions. Use it if your SDK targets the Responses API. It is stateless: store is always false, previous_response_id is rejected, and GET /v1/responses/{id} returns 404. Use the Anthropic Messages API if you need signed thinking blocks to round-trip across turns.

POST /v1/messages/count_tokens

Returns a conservative token estimate for a Messages request. It is free: no charge and no balance hold.

The Anthropic Messages API, used by the Anthropic SDKs and Claude Code. Buffered or streaming with the official Anthropic event protocol; signed thinking blocks round-trip in multi-turn tool use. Authenticate with x-api-key: sk-… or Authorization: Bearer.

curl https://api.tokun.sh/v1/messages \
  -H "x-api-key: $TOKUN_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-4-8",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Say hello in one word."}]
  }'