Migrate to Tokun

Already calling OpenAI or Anthropic? Migrating to Tokun changes exactly two things — the base URL and the API key. For the supported text surfaces (Chat Completions, Responses, and Anthropic Messages), the request and response shapes are byte-compatible with the official APIs, so your client code, streaming, and tool-use logic stay the same. Point your app at Tokun, pass a Tokun lab/model id, and you're billed at Tokun pricing with Tokun's routing.

What changes

Tokun speaks the OpenAI and Anthropic wire protocols natively, so a migration is a repoint, not a rewrite. For a standard text request, three values change and the rest stays identical:

Base URL — https://api.tokun.sh/v1 for OpenAI clients, https://api.tokun.sh (no /v1) for Anthropic clients.
API key — your Tokun sk- key, not your OpenAI / Anthropic key.
model — a Tokun lab/model id, e.g. openai/gpt-5.5.

Get a Tokun key in the console and add a balance under Billing before you cut over — requests against an empty balance return 402.

Tokun serves the text Chat Completions, Responses (stateless), and Anthropic Messages surfaces. Features the gateway doesn't serve yet — embeddings, image generation, the Responses store / previous_response_id state, and server-side tools — are not a drop-in; check the API Reference before migrating an app that relies on them.

From OpenAI

Keep the official OpenAI SDK. Override the base URL and key — either in the client constructor or via the OPENAI_BASE_URL / OPENAI_API_KEY environment variables — and pass a Tokun model id. The OpenAI base URL keeps its /v1 suffix.

python

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

Prefer environment variables (no code change)? The OpenAI SDK reads both:

bash

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

The Responses API works the same way — same base URL and key. It is stateless on Tokun (no store / previous_response_id); use the Anthropic Messages API if you need signed thinking blocks to round-trip across turns.

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 — the SDK appends the path itself.

bash

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

Adding /v1 to ANTHROPIC_BASE_URL is the most common migration mistake — it yields a 404. Use https://api.tokun.sh exactly. See the dedicated Claude Code guide for the full setup.

Model ids

Tokun model ids follow a lab/model convention. Swap your provider's model string for the corresponding 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).

Tokun never silently substitutes a model — an unknown id returns an error rather than quietly routing to a different model, so a mistyped id fails loudly instead of billing you for the wrong thing.

What stays the same

For supported text requests, the request and response shapes are byte-compatible with the official APIs — your parsing code is untouched.
Streaming ("stream": true / SSE) and tool / function calling work exactly as before.
The Anthropic event protocol round-trips signed thinking blocks on multi-turn tool use.
Your SDK, retry, and timeout logic stay as-is — only the endpoint and key differ.

Billing is reserve-then-settle: a hold for the estimated max cost is placed at request time and settled from upstream-reported usage. A request that fails before forwarding is released without charge.

Verify & troubleshoot

Confirm the cutover with one request, then watch it land in the console's usage view:

bash

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

Symptom	Cause	Fix
`401`	Still sending the provider key	Send your Tokun sk- key.
`402`	Empty Tokun balance	Top up under Billing.
`404 (Anthropic)`	A /v1 was added to the Anthropic base	Use https://api.tokun.sh with no /v1.
`400 — unknown model`	Provider model string, not a Tokun id	Use a lab/model id from the Models page.