Migrate to Tokun

Already using the OpenAI or Anthropic API? Update your connection settings: the base URL, the API key, and a Tokun lab/model ID. For supported text APIs (Chat Completions, Responses, and Anthropic Messages), request and response formats are byte-compatible with the official APIs, so your client code, streaming, and tool-use logic stay the same.

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.

Before you switch, create a key on the API keys page and add funds on the Billing page. Requests return 402 when your balance is empty.

Tokun supports text requests on Chat Completions, Responses (stateless), and Anthropic Messages. Features Tokun doesn't support yet (embeddings, image generation, Responses store / previous_response_id state, and server-side tools) don't work as a drop-in replacement. If your app relies on them, check the API reference before you migrate.

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.

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

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

bash

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

The Responses API uses the same base URL and key. On Tokun it is stateless (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 because the SDK adds 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

A common mistake is adding /v1 to ANTHROPIC_BASE_URL, which returns a 404. Use https://api.tokun.sh exactly. For full setup steps, see the Claude Code guide.

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

Tokun never substitutes a different model. An unknown or mistyped ID returns an error instead of quietly routing to another model and billing you for it.

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.

Billing is reserve-then-settle. When a request arrives, Tokun places a hold for its estimated maximum cost, then charges the usage the provider reports. If a request fails before it is forwarded, the hold is released and you are not charged.

Test your setup

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

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

Troubleshooting

Symptom	Cause	Fix
`401`	Still sending your OpenAI or Anthropic key	Send your Tokun sk- key.
`402`	Empty Tokun balance	Top up on the Billing page.
`404 (Anthropic)`	/v1 added to the Anthropic base URL	Use https://api.tokun.sh with no /v1.
`400 — unknown model`	Provider's model name, not a Tokun ID	Use a lab/model ID from the Models page.