# Tokun

> Tokun is a metered, multi-protocol LLM gateway. Point any OpenAI client at `https://api.tokun.sh/v1` (`Authorization: Bearer sk-...`), or any Anthropic SDK client — including Claude Code — at `ANTHROPIC_BASE_URL=https://api.tokun.sh` (`x-api-key: sk-...`), and call model ids like `anthropic/claude-opus-4-8` or `openai/gpt-5.5` (lab/model convention; protocol and model are independent). Tokun meters usage per token against a prepaid balance and routes each request to an eligible upstream.

## Integrate with one line

- Hand this single prompt to your coding agent (Claude Code, Codex, Cursor, …) and it will read the full guide and wire Tokun up: `Read https://tokun.sh/llms.txt and integrate Tokun into this project.`

## Quick Start

- [Get an API key](https://tokun.sh/api-keys): Create an `sk-...` key in the console (shown once); add a prepaid balance under Billing.
- [Base URL & auth](https://tokun.sh/docs#quick-start): Base URL `https://api.tokun.sh/v1`; header `Authorization: Bearer sk-...`; OpenAI Chat Completions format.
- [First call](https://tokun.sh/docs#quick-start): Copy-paste curl, Python, and Node (OpenAI SDK) examples hitting a real model id.
- [Anthropic SDK / Claude Code](https://tokun.sh/docs/integrations/claude-code): `ANTHROPIC_BASE_URL=https://api.tokun.sh` (no `/v1` suffix — the SDK adds the path) + `ANTHROPIC_API_KEY=sk-...`; the model can be a Tokun `lab/model` id (`anthropic/claude-opus-4-8`) or the bare Anthropic-native id (`claude-opus-4-8`, `claude-haiku-4-5`) — Tokun normalizes both.

## API Reference

- [Endpoints](https://tokun.sh/docs#faq): `POST /v1/chat/completions` — OpenAI Chat Completions (buffered or streaming); `POST /v1/responses` — OpenAI Responses API (stateless); `POST /v1/messages` — Anthropic Messages API (buffered or streaming); `POST /v1/messages/count_tokens` — Free conservative token estimate; `GET /v1/models` — List available model ids (OpenAI list format, free). All three inference endpoints run the same metering pipeline. No `/v1/embeddings`.
- [Auth](https://tokun.sh/docs#quick-start): Bearer key in the `Authorization` header; the same secret may also be embedded as a URL path segment (`/v1/{token}/chat/completions`). The Anthropic surface (`/v1/messages*`) also accepts the native `x-api-key` header.

## Capabilities

- Extended thinking: Extended thinking is supported and forwarded verbatim on ALL channels — automatic, official, reseller, and discount, INCLUDING a credential explicitly pinned to the discount channel; nothing is stripped at runtime (TXE-670 reversed the earlier pinned-discount degrade). Enable via thinking: {"type":"enabled","budget_tokens":N} (budget ≥ 1024 and < max_tokens) or the output_config.effort dial; signed thinking blocks round-trip on multi-turn tool use (streaming thinking_delta / signature_delta).
- Reasoning (OpenAI surfaces): On /v1/chat/completions, reasoning_effort and reasoning: {effort, max_tokens} forward untouched and reasoning / reasoning_details relay verbatim; /v1/responses supports reasoning.effort (none/minimal/low/medium/high/xhigh) with reasoning_summary_* summary events (stateless — replayed reasoning items are dropped).
- Client tools: Client tools (tools / tool_use / tool_result) and tool_choice are supported on both the OpenAI and Anthropic surfaces.
- Image / document input: Image and document content blocks are rejected with invalid_request_error (never silently dropped).
- Server tools: Code-execution-class server tools and mcp_servers are rejected with invalid_request_error. Anthropic web search is the exception — it is natively supported and billed per search on Anthropic-dialect routes. Structured outputs (output_config.format) are supported natively (TXE-744); only the deprecated top-level output_format is rejected.
- Prompt caching: cache_control is honored and billed at cache rates on native Anthropic-dialect routes (cache-read 0.1×, cache-write 1.25×/2.0× by TTL); on OpenAI chat-bridge routes it is accepted and ignored.
- Token counting: POST /v1/messages/count_tokens returns a free conservative token estimate ({"input_tokens": N}); no hold, no charge.
- Model listing: GET /v1/models is free and dual-dialect: an Anthropic-native caller (x-api-key / anthropic-version) gets the Anthropic list shape, every other caller the OpenAI list format, both with per-model context windows.
- served_vendor attribution: Every usage record carries served_vendor — the authoritative upstream that served the request — or "unattributed" when a fan-out upstream can't be determined (never blank).

## Models

- [anthropic/claude-opus-4-8](https://tokun.sh/docs#quick-start): Anthropic Claude Opus 4.8. $5.00 input / $25.00 output per 1M tokens.
- [anthropic/claude-opus-4-7](https://tokun.sh/docs#quick-start): Anthropic Claude Opus 4.7. $5.00 input / $25.00 output per 1M tokens.
- [anthropic/claude-sonnet-5](https://tokun.sh/docs#quick-start): Anthropic Claude Sonnet 5. $2.00 input / $10.00 output per 1M tokens.
- [anthropic/claude-sonnet-4-6](https://tokun.sh/docs#quick-start): Anthropic Claude Sonnet 4.6. $3.00 input / $15.00 output per 1M tokens.
- [anthropic/claude-haiku-4-5](https://tokun.sh/docs#quick-start): Anthropic Claude Haiku 4.5. $1.00 input / $5.00 output per 1M tokens.
- [anthropic/claude-fable-5](https://tokun.sh/docs#quick-start): Anthropic Claude Fable 5. $10.00 input / $50.00 output per 1M tokens.
- [openai/gpt-5.5](https://tokun.sh/docs#quick-start): OpenAI GPT-5.5. $5.00 input / $30.00 output per 1M tokens.
- [openai/gpt-5.4](https://tokun.sh/docs#quick-start): OpenAI GPT-5.4. $2.50 input / $15.00 output per 1M tokens.
- [openai/gpt-5.4-mini](https://tokun.sh/docs#quick-start): OpenAI GPT-5.4 mini. $0.75 input / $4.50 output per 1M tokens.
- [openai/gpt-5.4-nano](https://tokun.sh/docs#quick-start): OpenAI GPT-5.4 nano. $0.20 input / $1.25 output per 1M tokens.
- [openai/gpt-5.3-codex](https://tokun.sh/docs#quick-start): OpenAI GPT-5.3 Codex. $1.75 input / $14.00 output per 1M tokens.
- [gemini/gemini-3.1-pro-preview](https://tokun.sh/docs#quick-start): Google Gemini 3.1 Pro (preview). $2.00 input / $12.00 output per 1M tokens.
- [gemini/gemini-3.1-flash-lite-preview](https://tokun.sh/docs#quick-start): Google Gemini 3.1 Flash Lite (preview). $0.25 input / $1.50 output per 1M tokens.
- [xai/grok-4.5](https://tokun.sh/docs#quick-start): xAI Grok 4.5. $2.00 input / $6.00 output per 1M tokens.
- [xai/grok-4.3](https://tokun.sh/docs#quick-start): xAI Grok 4.3. $1.25 input / $2.50 output per 1M tokens.
- [deepseek/deepseek-v4-pro](https://tokun.sh/docs#quick-start): DeepSeek V4 Pro. $0.435 input / $0.87 output per 1M tokens.
- [deepseek/deepseek-v4-flash](https://tokun.sh/docs#quick-start): DeepSeek V4 Flash. $0.14 input / $0.28 output per 1M tokens.
- [moonshot/kimi-k2.7-code](https://tokun.sh/docs#quick-start): Moonshot Kimi K2.7 Code. $0.95 input / $4.00 output per 1M tokens.
- [moonshot/kimi-k2.6](https://tokun.sh/docs#quick-start): Moonshot Kimi K2.6. $0.60 input / $3.00 output per 1M tokens.
- [glm/glm-5.2](https://tokun.sh/docs#quick-start): Z.ai GLM-5.2. $1.40 input / $4.40 output per 1M tokens.
- [glm/glm-4.6](https://tokun.sh/docs#quick-start): Z.ai GLM-4.6. $0.60 input / $2.20 output per 1M tokens.
- [minimax/MiniMax-M3](https://tokun.sh/docs#quick-start): MiniMax M3. $0.30 input / $1.20 output per 1M tokens.
- [qwen/qwen3-max](https://tokun.sh/docs#quick-start): Qwen3 Max. $1.20 input / $6.00 output per 1M tokens.
- [qwen/qwen3.7-plus](https://tokun.sh/docs#quick-start): Qwen3.7 Plus. $0.40 input / $1.60 output per 1M tokens.
- Accepted id forms: send the `lab/model` id or the bare model name (`claude-haiku-4-5`, `gpt-5.4-mini`) — Claude Code and Codex send bare ids, both resolve to the same offering. A trailing `[1m]`, a provider/region prefix (`anthropic/`, `us.anthropic.`), and a date stamp are tolerated. Unsupported ids (`gpt-5.5-codex`, `gpt-5.2`) return `unknown model`; Tokun never substitutes a different model.

## FAQ

- [Three channels](https://tokun.sh/docs#faq): Tokun routes the same model across direct/official providers, resellers (OpenRouter, GMI), and cheaper discount providers.
- [Billing](https://tokun.sh/docs#faq): Prepaid, per-token; top up in USD ($5–$1,000 via Stripe). A hold is placed then settled from upstream-reported usage.
- [Privacy](https://tokun.sh/docs#faq): Prompts pass through in transit to the serving upstream; metadata is logged for billing/security.
- [served_vendor](https://tokun.sh/docs#faq): The authoritative upstream that served a request; `unattributed` when a fan-out upstream can't be determined.

## Full Guide

- [llms-full.txt](https://tokun.sh/llms-full.txt): The complete integration guide inlined as markdown — base URL, auth, working examples, model ids, capabilities, the three-channel model, and the key FAQ answers.