# TokenJoy > TokenJoy 是大模型 API 中转站，同时兼容 OpenAI 和 Anthropic 的接口格式：把 base_url 设为 https://api.tokenjoy.org/v1（OpenAI 格式）或 https://api.tokenjoy.org（Anthropic 格式），api_key 设为在 https://tokenjoy.org/console/keys 创建的 Key，就能用两家的 SDK 和兼容它们的 Agent 工具调用 Claude、GPT 等模型。 - 下面每一页都是 Markdown，网页版去掉末尾的 `.md` 即可打开。 - 全部文档合在一个文件里：https://tokenjoy.org/llms-full.txt - 示例里的 `TOKENJOY_API_KEY` 是存放 API Key 的环境变量，`<你的 API Key>`、`sk-…` 等是 Key 的占位符。 # 首次调用 API > 网页版：https://tokenjoy.org/docs/first-call TokenJoy 的 API 同时兼容 OpenAI 和 Anthropic 的接口格式。修改 base_url 和 api_key 后，就可以用这两家的 SDK，或任何兼容它们的软件访问本站的全部模型。 | 参数 | 值 | | --- | --- | | base_url（OpenAI） | `https://api.tokenjoy.org/v1` | | base_url（Anthropic） | `https://api.tokenjoy.org` | | api_key | [注册](https://tokenjoy.org/register)后在控制台的 [API Keys](https://tokenjoy.org/console/keys) 页创建 | | model | `claude-sonnet-5-5`、`gpt-6.1-terra` 等，见[模型列表](https://tokenjoy.org/docs/models.md) | 完整的 Key 只显示一次，请立即复制并妥善保存。遗失后可以在控制台重置，生成新的 Key。 ## 接入 Agent 工具 不用写代码，把本站设为下面这些 Agent 工具的模型提供方，就能直接开始使用： - [Hermes](https://tokenjoy.org/docs/agents/hermes.md) - [Claude Code](https://tokenjoy.org/docs/agents/claude-code.md) - [Codex](https://tokenjoy.org/docs/agents/codex.md) - [DeepSeek Harness](https://tokenjoy.org/docs/agents/dsh.md) 其他工具（OpenCode、OpenClaw、Cursor、Cline 等）详见 [Agent 工具接入指南](https://tokenjoy.org/docs/agents/claude-code.md)。 ## 调用对话 API 创建 API Key 后，可以用下面的样例脚本调用模型。样例为非流式输出，把 stream 设为 true 即可流式输出。两种格式可以调用同一个模型，本站会自动转换。 先把 Key 设置为环境变量 `TOKENJOY_API_KEY`，例如 `export TOKENJOY_API_KEY="<你的 API Key>"`。 **OpenAI 格式** **curl** ``` curl https://api.tokenjoy.org/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${TOKENJOY_API_KEY}" \ -d '{ "model": "gpt-6.1-terra", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ], "stream": false }' ``` **python** ``` # pip3 install openai import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("TOKENJOY_API_KEY"), base_url="https://api.tokenjoy.org/v1", ) response = client.chat.completions.create( model="gpt-6.1-terra", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"}, ], stream=False, ) print(response.choices[0].message.content) ``` **nodejs** ``` // npm install openai import OpenAI from "openai"; const openai = new OpenAI({ baseURL: "https://api.tokenjoy.org/v1", apiKey: process.env.TOKENJOY_API_KEY, }); async function main() { const completion = await openai.chat.completions.create({ model: "gpt-6.1-terra", messages: [ { role: "system", content: "You are a helpful assistant." }, { role: "user", content: "Hello!" }, ], stream: false, }); console.log(completion.choices[0].message.content); } main(); ``` **Anthropic 格式** **curl** ``` curl https://api.tokenjoy.org/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: ${TOKENJOY_API_KEY}" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-sonnet-5-5", "max_tokens": 1024, "system": "You are a helpful assistant.", "messages": [ {"role": "user", "content": "Hello!"} ], "stream": false }' ``` **python** ``` # pip3 install anthropic import os import anthropic client = anthropic.Anthropic( api_key=os.environ.get("TOKENJOY_API_KEY"), base_url="https://api.tokenjoy.org", ) message = client.messages.create( model="claude-sonnet-5-5", max_tokens=1024, system="You are a helpful assistant.", messages=[ {"role": "user", "content": "Hello!"}, ], ) print(message.content[0].text) ``` **nodejs** ``` // npm install @anthropic-ai/sdk import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic({ baseURL: "https://api.tokenjoy.org", apiKey: process.env.TOKENJOY_API_KEY, }); async function main() { const message = await anthropic.messages.create({ model: "claude-sonnet-5-5", max_tokens: 1024, system: "You are a helpful assistant.", messages: [{ role: "user", content: "Hello!" }], }); console.log(message.content[0].text); } main(); ``` 更多用法见 API 指南：[使用 OpenAI API](https://tokenjoy.org/docs/guides/openai.md)、[使用 Anthropic API](https://tokenjoy.org/docs/guides/anthropic.md)。 用 AI 编程助手接入时，可以把本站给 AI 读的文档交给它，见[让 AI 读文档](https://tokenjoy.org/docs/for-ai.md)。 --- # 模型 & 价格 > 网页版：https://tokenjoy.org/docs/models 下面是当前可以调用的模型，请求时把模型名填进 `model` 参数。对话模型都能用 OpenAI 和 Anthropic 两种格式调用，本站会自动转换。用你的 Key 请求 [GET /v1/models](https://tokenjoy.org/docs/api/models.md) 也能拿到这份列表。 价格见[模型价格页](https://tokenjoy.org/models)。 Gemini 3.8 Flash 统一使用 `gemini-3.8-flash`。低、中、高是同一模型的思考强度，通过 Chat Completions 的 `reasoning_effort` 或 Responses 的 `reasoning.effort` 选择；图片生成模型单独列出。 ### Anthropic - `claude-sonnet-5-5` - `claude-sonnet-5` - `claude-sonnet-4-6` - `claude-sonnet-4-5` - `claude-opus-5-5` - `claude-opus-5` - `claude-opus-4-8` - `claude-opus-4-7` - `claude-opus-4-6` - `claude-opus-4-5-20251101` - `claude-haiku-5-5` - `claude-haiku-4-5-20251001` - `claude-fable-5-2` - `claude-fable-5-1` - `claude-fable-5` ### DeepSeek - `passthrough/deepseek-flash-1017` - `deepseek-flash` ### GLM - `GLM5.3-Flash` - `GLM5.2` ### Google - `gemini-3.8-flash-tiered` - `gemini-3.8-flash-medium` - `gemini-3.8-flash-low` - `gemini-3.8-flash-high` - `gemini-3.5-flash-lite` - `gemini-3.1-flash-lite` - `gemini-3.1-flash-image` - `gemini-3-pro-image-preview` - `gemini-3-flash` - `gemini-2.5-pro` - `gemini-2.5-flash-lite` - `gemini-2.5-flash` ### Grok - `grok-4.7` ### Kimi - `kimi-k3` ### OpenAI - `gpt-reserve` - `gpt-realtime-mini` - `gpt-realtime` - `gpt-image-2.5-sunburst-2026-09-08` - `gpt-image-2.5-sunburst` - `gpt-image-2.5-flare-2026-09-08` - `gpt-image-2.5-flare` - `gpt-image-2` - `gpt-6.1-terra` - `gpt-6.1-sol` - `gpt-6-sol` - `gpt-6-luna` - `gpt-6-astra` - `gpt-5.6-terra` - `gpt-5.6-sol` - `gpt-5.6-luna` --- # Token 用量计算 > 网页版：https://tokenjoy.org/docs/token-usage Token 是模型表示文本的基本单位，也是计费的依据，可以近似理解为「字」或「词」。 ## 大致换算 不同厂商的模型分词方式不同，换算比例也不一样，以下只作粗略估算： - 1 个英文单词约 1～1.5 个 token - 1 个中文字约 1～2 个 token - 代码、数字和符号通常比普通文本消耗更多 token 实际数量以接口返回的 `usage` 字段为准：OpenAI 格式是 `prompt_tokens` / `completion_tokens`，Anthropic 格式是 `input_tokens` / `output_tokens`。发送请求前想知道输入有多少 token，可以调用 [计算 Token 数](https://tokenjoy.org/docs/api/count-tokens.md) 接口。 ## 按 token 计费 - 按上游记录的实际 token 数从余额中扣费，余额以美元（USD $）计；输入、输出、缓存读取、缓存写入分别计价。每个模型的价格见[模型价格页](https://tokenjoy.org/models)。 - 大约每 30 秒结算一次，控制台的余额会稍晚于请求更新。 - 多轮对话中，之前的消息会作为输入再次计费。开启了提示词缓存的模型，重复的前缀按更便宜的缓存读取价计费。 - 控制台「概览」页的「用量明细」按模型、按 Key 列出请求数、token 数和花费，「API Keys」页可以查看每把 Key 每天的用量，余额卡上的「流水」能看到每一笔变动。控制台可以切换为人民币（CNY ¥）显示，按站点公布的汇率折算，仅供参考。 --- # 限速与隔离 > 网页版：https://tokenjoy.org/docs/rate-limit ## 限速 本站不对单把 Key 设置固定的请求数或并发上限。遇到上游限流或瞬时过载时，接口会返回 HTTP 429，请稍等后重试，建议使用指数退避（例如 1 秒、2 秒、4 秒……）。 大部分 SDK 和 Agent 工具自带重试，不需要额外处理。自己写代码时，不要在收到 429 后立即无间隔地重试。 ## Key 之间的隔离 同一个账号可以创建多把 Key，建议按设备或项目分开（例如「公司电脑」「家里电脑」「某个脚本」），便于区分用量和单独停用。 - **额度**：账户余额会平均分给所有启用中的 Key，作为每把 Key 的可用额度，并随余额自动调整。一把 Key 用得多，不会让其他 Key 立即失效。 - **用量**：每把 Key 的请求数、token 数和花费分开统计，在控制台「概览」页和「API Keys」页查看。 - **停用与重置**：停用或重置一把 Key 只影响它自己。Key 泄露时请立即在控制台重置。 - **余额用完**：所有 Key 暂停，兑换卡密充值后自动恢复，不需要重新创建 Key。 ## 请求保活 流式请求在等待模型输出期间保持连接。长任务建议使用流式输出（`stream: true`），既能更早看到结果，也能避免中间网络设备因长时间无数据而断开连接。 --- # 错误码 > 网页版：https://tokenjoy.org/docs/error-codes 调用 API 时可能遇到的错误，以及原因和解决方法： | 错误码 | 描述 | 原因 | 解决方法 | | --- | --- | --- | --- | | 400 | 格式错误 | 请求体格式有误，或模型名不存在 | 按错误信息修改请求体；模型名请对照模型列表 | | 401 | 认证失败 | Key 不正确、已被停用，或因余额不足暂停 | 检查 Key 是否填对、有没有多余空格；到控制台确认 Key 的状态 | | 402 | 额度用完 | Key 的额度已用完（`budget_exhausted`），通常是账户余额不足 | 兑换卡密充值，到账后自动恢复 | | 404 | 接口不存在 | 请求地址有误 | OpenAI 格式的地址要带 /v1，Anthropic SDK 的 base_url 不带 /v1 | | 429 | 请求过于频繁 | 上游限流或瞬时过载 | 稍等后重试，见限速与隔离 | | 500 | 服务器故障 | 本站或上游内部错误 | 稍等后重试；持续出现请联系我们 | | 502 / 503 | 上游不可用 | 上游服务繁忙或故障 | 稍后重试，并查看[服务状态](https://tokenjoy.org/status)确认是否为官方故障 | --- # 服务状态 > 网页版：https://tokenjoy.org/docs/status TokenJoy 和各上游官方服务的实时状态，每分钟探测一次。调用出错时，可以先在这里确认是不是服务本身的问题。 正在读取状态… --- # 让 AI 读文档 > 网页版：https://tokenjoy.org/docs/for-ai 本站的文档另有一份给 AI 读的 Markdown 版本，遵循 [llms.txt](https://llmstxt.org) 约定。把地址交给 AI 编程助手或聊天 AI，它就能按文档里的真实地址和模型名帮你接入、写代码、排查错误，不会照着过时的记忆乱写。 | 地址 | 内容 | | --- | --- | | [`https://tokenjoy.org/llms.txt`](https://tokenjoy.org/llms.txt) | 索引：本站简介和全部文档页的链接，AI 按需打开相关页面 | | [`https://tokenjoy.org/llms-full.txt`](https://tokenjoy.org/llms-full.txt) | 全部文档合在一个文件里，适合直接贴给 AI 或加进知识库 | | `https://tokenjoy.org/docs/<页面>.md` | 单个页面：在文档网址后面加 `.md`，例如 [`https://tokenjoy.org/docs/agents/claude-code.md`](https://tokenjoy.org/docs/agents/claude-code.md) | Markdown 版和网页文档内容一致，所有代码示例、OpenAI 和 Anthropic 两种格式都展开写出，macOS / Linux 与 Windows 不同的地方两种写法都列出。模型列表是实时的。 ## 让编程助手帮你接入 Claude Code、Codex、Cursor、Cline 等能联网读网页的工具，直接把地址写进你的要求里，例如： ``` 读一下 https://tokenjoy.org/llms.txt ， 帮我把这个项目里的 OpenAI 调用改成走 TokenJoy，Key 从环境变量 TOKENJOY_API_KEY 读。 ``` ``` 按 https://tokenjoy.org/docs/agents/codex.md 帮我配置 Codex。 ``` AI 会先读索引，再打开需要的页面，比如 [使用 OpenAI API](https://tokenjoy.org/docs/guides/openai.md)、[对话补全](https://tokenjoy.org/docs/api/chat-completions.md)，然后照着改代码。 ## 贴给不能联网的聊天 AI 如果聊天 AI 打不开链接，就在浏览器里打开 [`https://tokenjoy.org/llms-full.txt`](https://tokenjoy.org/llms-full.txt)，全选复制粘贴进对话，或保存成文件上传，然后再提问，例如「用 Python 写一个流式输出的例子」「调用时返回 429 是什么原因」。 问题很明确时，只给对应的那一页更省上下文： | 想做的事 | 给 AI 的地址 | | --- | --- | | 配置 Claude Code | `https://tokenjoy.org/docs/agents/claude-code.md` | | 写 Tool Calls | `https://tokenjoy.org/docs/guides/tool-calls.md` | | 查错误码 | `https://tokenjoy.org/docs/error-codes.md` | | 看当前有哪些模型 | `https://tokenjoy.org/docs/models.md` | ## 加进知识库 Cursor 的 `@Docs`、Cherry Studio 的知识库等功能可以添加文档源。把 [`https://tokenjoy.org/llms-full.txt`](https://tokenjoy.org/llms-full.txt) 加进去，之后在对话里引用即可，不用每次都贴链接。 ## 写进项目的 AI 说明文件 在项目的 `CLAUDE.md`、`AGENTS.md` 或 `.cursorrules` 里加一行，AI 在这个项目里写调用模型的代码时会自己去查： ``` 调用大模型 API 时使用 TokenJoy，文档见 https://tokenjoy.org/llms.txt ``` ## 注意保护 Key 不要把真实的 API Key 发给 AI。让 AI 按文档的写法从环境变量 `TOKENJOY_API_KEY` 读取 Key，Key 自己在本机设置，见[首次调用 API](https://tokenjoy.org/docs/first-call.md)。 --- # 接入 Claude Code > 网页版：https://tokenjoy.org/docs/agents/claude-code Claude Code 是 Anthropic 推出的终端 AI 编程助手，使用 Anthropic 格式的接口，本站原生支持。 ## 从现有安装中迁移 如果你已经安装了 Claude Code，运行下面这行命令，把 Key 换成你自己的，会自动写好配置（原配置会先备份）。API Key 在控制台的 [API Keys](https://tokenjoy.org/console/keys) 页创建。 **macOS / Linux：** 在终端中执行： ``` curl -fsSL https://tokenjoy.org/setup.sh | TOKENJOY_BASE_URL=https://api.tokenjoy.org sh -s -- <你的 API Key> ``` **Windows：** 在 PowerShell 中执行： ``` $env:TOKENJOY_BASE_URL="https://api.tokenjoy.org"; $env:TOKENJOY_API_KEY="<你的 API Key>"; $env:TOKENJOY_AGENT="claude-code"; irm https://tokenjoy.org/scripts/setup.ps1 | iex ``` 创建 Key 时弹出的窗口里可以选择 Claude Code，命令中已经带上了你的 Key，直接复制即可。 ## 从零安装 Claude Code ### 1. 安装 Claude Code 安装 Node.js 18 或更高版本。Windows 用户还需要安装 Git for Windows。然后执行： ``` npm install -g @anthropic-ai/claude-code ``` 安装结束后，执行下面的命令，显示版本号即安装成功： ``` claude --version ``` ### 2. 配置环境变量 可以用上面的一键命令，也可以手动配置。 **macOS / Linux：** 加到 `~/.zshrc`（macOS 默认）或 `~/.bashrc` 末尾，然后执行 `source ~/.zshrc`： ``` export ANTHROPIC_BASE_URL="https://api.tokenjoy.org" export ANTHROPIC_AUTH_TOKEN="<你的 API Key>" export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 ``` **Windows：** 在 PowerShell 中执行，然后关掉并重新打开 PowerShell： ``` setx ANTHROPIC_BASE_URL "https://api.tokenjoy.org" setx ANTHROPIC_AUTH_TOKEN "<你的 API Key>" setx CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY 1 ``` 也可以只对 Claude Code 生效，写进 `~/.claude/settings.json`： ~/.claude/settings.json： ``` { "env": { "ANTHROPIC_BASE_URL": "https://api.tokenjoy.org", "ANTHROPIC_AUTH_TOKEN": "<你的 API Key>", "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1" } } ``` ### 3. 开始使用 进入项目目录，执行 `claude`： ``` cd /path/to/my-project claude ``` 进去后输入 `/status`，Base URL 显示为 https://api.tokenjoy.org 即配置成功。输入 `/model` 可以切换本站的全部模型：`CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` 让 Claude Code 从本站读取模型列表，GPT、DeepSeek 等非 Claude 模型显示为 `anthropic-compat/` 开头的名字，选中后实际调用的就是对应模型。 --- # 接入 Pi > 网页版：https://tokenjoy.org/docs/agents/pi Pi 是 Mario Zechner 开源的终端 AI 编程助手，界面简洁，可以通过配置文件接入任意模型服务。本站以 Anthropic 格式接入。 ## 一键配置 已经安装 Pi 时，运行下面这行命令，把 Key 换成你自己的，会自动写好配置（原配置会先备份）。API Key 在控制台的 [API Keys](https://tokenjoy.org/console/keys) 页创建。 **macOS / Linux：** 在终端中执行： ``` curl -fsSL https://tokenjoy.org/setup.sh | TOKENJOY_BASE_URL=https://api.tokenjoy.org sh -s -- <你的 API Key> pi claude-sonnet-5-5 ``` **Windows：** 在 PowerShell 中执行： ``` $env:TOKENJOY_BASE_URL="https://api.tokenjoy.org"; $env:TOKENJOY_API_KEY="<你的 API Key>"; $env:TOKENJOY_AGENT="pi"; $env:TOKENJOY_MODEL="claude-sonnet-5-5"; irm https://tokenjoy.org/scripts/setup.ps1 | iex ``` 创建 Key 时弹出的窗口里可以选择 Pi，命令中已经带上了你的 Key，直接复制即可。默认模型为 `claude-sonnet-5-5`，之后可以随时切换。 ## 手动配置 ### 1. 安装 Pi **macOS / Linux：** 安装 Node.js 20.6 或更高版本。然后执行： **Windows：** 安装 Node.js 20.6 或更高版本，Windows 还需要安装 Git for Windows（Pi 通过它提供的 bash 执行命令）。然后执行： ``` npm install -g @mariozechner/pi-coding-agent ``` ### 2. 添加模型提供方 **macOS / Linux：** 编辑 `~/.pi/agent/models.json`（没有就新建），加入本站。已有其他提供方时，只在 `providers` 里加入 `tokenjoy` 这一项： ~/.pi/agent/models.json： **Windows：** 编辑 `%USERPROFILE%\.pi\agent/models.json`（没有就新建），加入本站。已有其他提供方时，只在 `providers` 里加入 `tokenjoy` 这一项： %USERPROFILE%\.pi\agent/models.json： ``` { "providers": { "tokenjoy": { "baseUrl": "https://api.tokenjoy.org", "api": "anthropic-messages", "apiKey": "TOKENJOY_API_KEY", "models": [ { "id": "claude-sonnet-5-5", "reasoning": true, "input": [ "text", "image" ], "contextWindow": 200000, "maxTokens": 32000 } ] } } } ``` - `baseUrl` 填 `https://api.tokenjoy.org`，不带 `/v1`：Pi 会自己加上 `/v1/messages`。 - `apiKey` 写环境变量名时，Pi 会读取这个环境变量；也可以直接写 Key。 - `models` 里可以加入 [模型列表](https://tokenjoy.org/docs/models.md)中的其他 Claude 模型，只有 `id` 是必填项。 - 想用 GPT 模型，再加一个提供方，`api` 填 `openai-responses`，`baseUrl` 填 `https://api.tokenjoy.org/v1`。 然后设置 Key：API Key 在控制台的 [API Keys](https://tokenjoy.org/console/keys) 页创建。 **macOS / Linux：** 加到 ~/.zshrc 或 ~/.bashrc 末尾： ``` export TOKENJOY_API_KEY="<你的 API Key>" ``` 再在 `~/.pi/agent/settings.json` 中把本站设为默认： ~/.pi/agent/settings.json： **Windows：** PowerShell，执行后重新打开： ``` setx TOKENJOY_API_KEY "<你的 API Key>" ``` 再在 `%USERPROFILE%\.pi\agent/settings.json` 中把本站设为默认： %USERPROFILE%\.pi\agent/settings.json： ``` { "defaultProvider": "tokenjoy", "defaultModel": "claude-sonnet-5-5" } ``` ### 3. 开始使用 ``` cd /path/to/my-project pi ``` 进去后输入 `/model` 可以切换模型，TokenJoy 下列出的就是刚才添加的模型。 --- # 接入 Codex > 网页版：https://tokenjoy.org/docs/agents/codex Codex 是 OpenAI 推出的 AI 编程助手，通过 Responses API 与模型交互，本站原生支持该格式。Codex CLI、ChatGPT 桌面端和 VS Code 的 Codex 插件共用同一份配置文件，配置一次即可在所有形态中使用。 ## 一键配置 运行下面这行命令，把 Key 换成你自己的，会在 `~/.codex/config.toml` 中写好本站的配置，原有的 MCP 服务器、项目信任等设置保持不变（原文件会先备份）。Key 写在本站的提供方配置里，不会改动 ChatGPT 的登录状态。API Key 在控制台的 [API Keys](https://tokenjoy.org/console/keys) 页创建。 **macOS / Linux：** 在终端中执行： ``` curl -fsSL https://tokenjoy.org/setup.sh | TOKENJOY_BASE_URL=https://api.tokenjoy.org sh -s -- <你的 API Key> codex gpt-6.1-terra ``` **Windows：** 在 PowerShell 中执行： ``` $env:TOKENJOY_BASE_URL="https://api.tokenjoy.org"; $env:TOKENJOY_API_KEY="<你的 API Key>"; $env:TOKENJOY_AGENT="codex"; $env:TOKENJOY_MODEL="gpt-6.1-terra"; irm https://tokenjoy.org/scripts/setup.ps1 | iex ``` 创建 Key 时弹出的窗口里可以选择 Codex，命令中已经带上了你的 Key，直接复制即可。默认模型为 `gpt-6.1-terra`，之后可以随时切换。 写好的配置带有 `model_catalog_url`，Codex 会从本站读取模型列表，`/model` 里能看到并切换本站的全部模型（GPT、Claude、Gemini、DeepSeek 等）。之前配置过的，重新运行一次上面的命令即可更新。 ## 手动配置 ### 1. 安装 Codex 安装 Node.js 18 或更高版本，然后执行： ``` npm install -g @openai/codex ``` ### 2. 配置模型提供方 **macOS / Linux：** 编辑 `~/.codex/config.toml`（没有就新建），加入下面的内容。原有的 MCP 服务器、项目信任等配置可以保留。 **Windows：** 编辑 `%USERPROFILE%\.codex\config.toml`（没有就新建），加入下面的内容。原有的 MCP 服务器、项目信任等配置可以保留。 ~/.codex/config.toml： ``` model = "gpt-6.1-terra" model_provider = "tokenjoy" [model_providers.tokenjoy] name = "TokenJoy" base_url = "https://api.tokenjoy.org/v1" model_catalog_url = "https://api.tokenjoy.org/v1/models" env_key = "TOKENJOY_API_KEY" wire_api = "responses" ``` - `model_catalog_url` 让 Codex 从本站读取模型列表，`/model` 里会列出本站的全部模型。不写这一行的话，Codex 只列出它内置的 GPT 模型。 - `model` 是默认模型，可以换成 [模型列表](https://tokenjoy.org/docs/models.md)里的任意模型，之后在 `/model` 里随时切换。 然后把 Key 设置为环境变量。API Key 在控制台的 [API Keys](https://tokenjoy.org/console/keys) 页创建。 **macOS / Linux：** 加到 ~/.zshrc 或 ~/.bashrc 末尾： ``` export TOKENJOY_API_KEY="<你的 API Key>" ``` **Windows：** PowerShell，执行后重新打开： ``` setx TOKENJOY_API_KEY "<你的 API Key>" ``` ### 3. 开始使用 ``` cd /path/to/my-project codex ``` 进去后输入 `/model` 可以切换本站的全部模型。如果列表里只有 GPT 模型，检查配置里有没有 `model_catalog_url`，并执行 `npm install -g @openai/codex` 把 Codex 升级到最新版本。 --- # 接入 Hermes > 网页版：https://tokenjoy.org/docs/agents/hermes Hermes 是 Nous Research 打造的开源 AI Agent，支持 macOS、Linux 和 Windows。本站以 Anthropic 格式接入。 ## 一键配置 已经安装 Hermes 时，运行下面这行命令，把 Key 换成你自己的，会通过 `hermes config set` 写好配置（原配置会先备份）。API Key 在控制台的 [API Keys](https://tokenjoy.org/console/keys) 页创建。 **macOS / Linux：** 在终端中执行： ``` curl -fsSL https://tokenjoy.org/setup.sh | TOKENJOY_BASE_URL=https://api.tokenjoy.org sh -s -- <你的 API Key> hermes claude-sonnet-5-5 ``` **Windows：** 在 PowerShell 中执行： ``` $env:TOKENJOY_BASE_URL="https://api.tokenjoy.org"; $env:TOKENJOY_API_KEY="<你的 API Key>"; $env:TOKENJOY_AGENT="hermes"; $env:TOKENJOY_MODEL="claude-sonnet-5-5"; irm https://tokenjoy.org/scripts/setup.ps1 | iex ``` 创建 Key 时弹出的窗口里可以选择 Hermes，命令中已经带上了你的 Key，直接复制即可。默认模型为 `claude-sonnet-5-5`，之后可以随时切换。 ## 手动配置 ### 1. 安装 Hermes **macOS / Linux：** ``` curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash ``` **Windows：** ``` iex (irm https://hermes-agent.nousresearch.com/install.ps1) ``` 安装后重新打开终端。首次安装会进入配置向导，模型提供方可以先跳过，按下一步添加。 ### 2. 配置模型提供方 在终端中依次执行（不要在 Hermes 会话里执行）。第一条把 Key 写进 Hermes 的 `.env`，其余写进 `config.yaml`： ``` hermes config set TOKENJOY_API_KEY <你的 API Key> hermes config set providers.tokenjoy.api https://api.tokenjoy.org hermes config set providers.tokenjoy.key_env TOKENJOY_API_KEY hermes config set providers.tokenjoy.transport anthropic_messages hermes config set model.provider custom:tokenjoy hermes config set model.default claude-sonnet-5-5 ``` **macOS / Linux：** 也可以直接编辑 `~/.hermes/config.yaml`，效果相同： ~/.hermes/config.yaml： **Windows：** 也可以直接编辑 `%LOCALAPPDATA%\hermes/config.yaml`，效果相同： %LOCALAPPDATA%\hermes/config.yaml： ``` providers: tokenjoy: api: https://api.tokenjoy.org key_env: TOKENJOY_API_KEY transport: anthropic_messages model: default: claude-sonnet-5-5 provider: custom:tokenjoy ``` **macOS / Linux：** 这种写法还要把 Key 写进 `~/.hermes/.env`： ~/.hermes/.env： **Windows：** 这种写法还要把 Key 写进 `%LOCALAPPDATA%\hermes/.env`： %LOCALAPPDATA%\hermes/.env： ``` TOKENJOY_API_KEY=<你的 API Key> ``` `model.default` 可以换成 [模型列表](https://tokenjoy.org/docs/models.md)里的其他 Claude 模型。想用 GPT 模型时，执行 `hermes model`，选择 **Custom endpoint**，API base URL 填写 `https://api.tokenjoy.org/v1`。 ### 3. 开始使用 ``` hermes ``` 执行 `hermes config get model --json` 可以确认当前使用的提供方和模型。 --- # 接入 CC Switch > 网页版：https://tokenjoy.org/docs/agents/cc-switch [CC Switch](https://github.com/farion1231/cc-switch) 是一款开源的桌面应用，支持 Windows、macOS 和 Linux，可以集中管理 Claude Code、Codex、OpenCode、OpenClaw、Hermes、Pi 等工具的模型提供方，点一下就能在不同提供方之间切换，不用手动改配置文件。本站支持从控制台一键导入到 CC Switch。 ## 1. 安装 CC Switch 从 [CC Switch 官网](https://ccswitch.io/download)或 [GitHub Releases](https://github.com/farion1231/cc-switch/releases) 下载对应系统的安装包。CC Switch 是免费软件，不要从其他渠道下载。 | 系统 | 安装方式 | | --- | --- | | Windows 10 及以上 | 下载 `.msi` 安装包并运行；也可以下载 `Portable.zip` 绿色版，解压后运行 `CC-Switch.exe` | | macOS 12 及以上 | 执行 `brew install --cask cc-switch`，或下载 `.dmg` 后拖进「应用程序」 | | Linux | Debian / Ubuntu 用 `.deb`，Fedora 用 `.rpm`，Arch 执行 `paru -S cc-switch-bin`，其他发行版用 `.AppImage` | CC Switch 只负责管理配置，Claude Code、Codex 等工具本身还需要安装。可以在 CC Switch 侧栏底部的 **应用** 页一键安装，也可以按各工具的接入指南安装，例如[Claude Code](https://tokenjoy.org/docs/agents/claude-code.md)、[Codex](https://tokenjoy.org/docs/agents/codex.md)。 ## 2. 一键导入本站（推荐） 一键导入需要 CC Switch v4.0.10 或更高版本。 1. 在控制台的 [API Keys](https://tokenjoy.org/console/keys) 页创建 Key。创建成功的弹窗里，在 **一键配置** 中选择 **CC Switch**。 2. 点击要使用的工具，例如 **导入到 Claude Code**。浏览器询问是否打开 CC Switch 时，选择允许。 3. CC Switch 会弹出导入确认框，显示地址、打码后的 Key 和模型。核对无误后点 **导入**。 4. Claude Code 和 Codex 同一时间只能用一个提供方：在确认框里打开 **导入后立即切换**，或导入后在供应商列表里点 TokenJoy 卡片上的 **切换**。OpenCode、OpenClaw、Hermes、Pi 可以同时使用多个提供方，导入后直接写入这些工具的配置。 完整的 Key 只在创建时显示一次。弹窗已经关掉的话，可以在 API Keys 页重置 Key，用新弹窗导入；也可以按下一节手动添加。每个工具单独导入一次，同一个按钮点两次会导入两份，删掉多余的即可。 各工具导入的内容如下，与本文档中各工具接入指南的手动配置一致： | 工具 | 接口格式 | 地址 | 默认模型 | | --- | --- | --- | --- | | Claude Code | Anthropic | `https://api.tokenjoy.org` | 不指定，`/model` 中可以选择本站全部模型 | | Codex | OpenAI Responses | `https://api.tokenjoy.org/v1` | `gpt-6.1-terra` | | OpenCode | Anthropic | `https://api.tokenjoy.org/v1` | `claude-sonnet-5-5` | | OpenClaw | OpenAI Chat Completions | `https://api.tokenjoy.org/v1` | `claude-sonnet-5-5` | | Hermes | Anthropic | `https://api.tokenjoy.org` | `claude-sonnet-5-5` | | Pi | Anthropic | `https://api.tokenjoy.org` | `claude-sonnet-5-5` | ## 3. 手动添加 在 CC Switch 侧栏选中要配置的工具，点页头右侧的 **添加供应商**，在预设列表中选择 **自定义配置**，名称填写 `TokenJoy`，然后按工具填写下面的配置。API Key 在控制台的 [API Keys](https://tokenjoy.org/console/keys) 页创建。 ### Claude Code 配置编辑框中填写： Claude Code 配置： ``` { "env": { "ANTHROPIC_BASE_URL": "https://api.tokenjoy.org", "ANTHROPIC_AUTH_TOKEN": "<你的 API Key>", "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1" } } ``` `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` 让 Claude Code 从本站读取模型列表，`/model` 中能看到 GPT、DeepSeek 等全部模型。 ### Codex Codex 的编辑框分为两部分。`auth.json` 部分填写 Key： auth.json： ``` { "OPENAI_API_KEY": "<你的 API Key>" } ``` `config.toml` 部分填写： config.toml： ``` model_provider = "custom" model = "gpt-6.1-terra" [model_providers.custom] name = "TokenJoy" base_url = "https://api.tokenjoy.org/v1" wire_api = "responses" model_catalog_url = "https://api.tokenjoy.org/v1/models" ``` `model_catalog_url` 让 Codex 从本站读取模型列表，`/model` 中能看到全部模型。 ### OpenCode、OpenClaw、Hermes、Pi 按上一节表格中的接口格式、地址和模型填写，API Key 填写本站的 Key。也可以点模型输入框旁的 **获取模型列表**，从本站读取可用模型后勾选。 ## 4. 切换与生效 - 在 CC Switch 中点 TokenJoy 卡片上的 **切换**，卡片显示 **使用中** 即已切换。也可以右键系统托盘中的 CC Switch 图标，在对应工具的子菜单里切换。 - Claude Code 切换后立即生效，不需要重启。进去后输入 `/status`，Base URL 显示为 https://api.tokenjoy.org 即配置成功。 - Codex 切换后需要重启：命令行退出后重新运行 `codex`，桌面版彻底退出后再打开。 - CC Switch 切换时只改地址、Key、模型等关键字段，插件、MCP、权限等其他设置保持不变。 ## 常见问题 | 现象 | 原因和解决办法 | | --- | --- | | 点导入按钮没有反应 | 电脑上没有安装 CC Switch，或版本低于 v4.0.10。安装或升级后重新点击；浏览器拦截了打开应用的请求时，在地址栏右侧允许 | | 切换后请求仍然发往官方或其他服务 | 终端里设置的 `ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`OPENAI_BASE_URL` 等环境变量会和 CC Switch 写入的配置冲突。从 `~/.zshrc`、`~/.bashrc` 或系统环境变量中删掉后，重新打开终端 | | 401 认证失败 | Key 不完整或已被删除、重置。在 CC Switch 中编辑 TokenJoy 卡片，换成当前有效的 Key | | Codex 的 `/model` 里只有 GPT 模型 | 配置里缺少 `model_catalog_url`，按上面的 `config.toml` 补上，或重新一键导入 | 其他报错见[错误码](https://tokenjoy.org/docs/error-codes.md)和[其他 Agent](https://tokenjoy.org/docs/agents/other.md)中的排查步骤。 --- # 接入 DeepSeek Harness > 网页版：https://tokenjoy.org/docs/agents/dsh DeepSeek Harness（`dsh`）是 DeepSeek 开源的 Agent 框架，目前处于开发者预览阶段，提供 Web UI。它支持「自定义模型 API」，可以直接接入本站。 ### 1. 安装并启动 安装 Node.js，然后执行： ``` npx @deepseek-ai/dsh web ``` 默认在 `http://127.0.0.1:3080` 启动 Web UI，并用浏览器打开。 ### 2. 添加本站为模型提供方 1. 打开 **设置 → 模型**，选择 **添加模型提供商**，切换到 **自定义模型 API** 2. Provider ID 填写 `tokenjoy`（创建后不能改名） 3. API 地址填写 `https://api.tokenjoy.org` 4. API 协议选择 **Anthropic Messages** 5. API 密钥填写你的 API Key。API Key 在控制台的 [API Keys](https://tokenjoy.org/console/keys) 页创建。 6. 在 **模型目录** 中点 **获取可用模型**，勾选要用的模型；也可以手动添加模型 ID，例如 `claude-sonnet-5-5` 一个提供方只用一种协议。想用 GPT 模型的 Responses 格式，再添加一个提供方，API 协议选 **OpenAI Responses**，API 地址填写 `https://api.tokenjoy.org/v1`。 也可以直接编辑 `$DSH_HOME/profiles/web/cordis.patch.yml`，与在模型页填写的效果相同： cordis.patch.yml： ``` - id: llm-pi-ai config: providers: tokenjoy: apiKeyEnv: TOKENJOY_API_KEY api: anthropic-messages baseURL: https://api.tokenjoy.org models: - id: claude-sonnet-5-5 ``` 这种写法从环境变量 `TOKENJOY_API_KEY` 读取 Key，先设置它，再从同一个终端启动 `dsh`：API Key 在控制台的 [API Keys](https://tokenjoy.org/console/keys) 页创建。 **macOS / Linux：** ``` export TOKENJOY_API_KEY="<你的 API Key>" ``` **Windows：** ``` setx TOKENJOY_API_KEY "<你的 API Key>" ``` ### 3. 开始使用 在模型选择器中选择刚添加的模型，选中一个工作区后即可开始会话。模型改动在下一次请求时生效，不需要重启。 --- # 接入 OpenCode > 网页版：https://tokenjoy.org/docs/agents/opencode OpenCode 是一个开源 AI 编程助手，提供终端、桌面端等运行形式。 ### 1. 安装 OpenCode **macOS / Linux：** ``` curl -fsSL https://opencode.ai/install | bash ``` **Windows：** ``` npm install -g opencode-ai ``` ### 2. 配置模型提供方 编辑 `~/.config/opencode/opencode.json`（没有就新建）： ~/.config/opencode/opencode.json： ``` { "$schema": "https://opencode.ai/config.json", "provider": { "tokenjoy": { "npm": "@ai-sdk/anthropic", "name": "TokenJoy", "options": { "baseURL": "https://api.tokenjoy.org/v1", "apiKey": "{env:TOKENJOY_API_KEY}" }, "models": { "claude-sonnet-5-5": { "name": "claude-sonnet-5-5" } } } } } ``` `models` 里可以加入 [模型列表](https://tokenjoy.org/docs/models.md)中的其他模型。然后设置 Key：API Key 在控制台的 [API Keys](https://tokenjoy.org/console/keys) 页创建。 **macOS / Linux：** ``` export TOKENJOY_API_KEY="<你的 API Key>" ``` **Windows：** ``` setx TOKENJOY_API_KEY "<你的 API Key>" ``` ### 3. 开始使用 执行 `opencode`，输入 `/models`，选择 TokenJoy 下的模型。 ``` cd /path/to/my-project opencode ``` --- # 接入 OpenClaw > 网页版：https://tokenjoy.org/docs/agents/openclaw OpenClaw 是一个开源的个人 AI 助手，可以接入飞书、微信等常用聊天工具，并通过 Skill 扩展能力。 ### 1. 安装 OpenClaw **macOS / Linux：** ``` curl -fsSL https://openclaw.ai/install.sh | bash ``` **Windows：** ``` iwr -useb https://openclaw.ai/install.ps1 | iex ``` 首次安装后会自动进入配置向导，模型提供方可以先跳过，按下一步手动添加。 ### 2. 配置模型提供方 编辑 `~/.openclaw/openclaw.json`，在 `models.providers` 中加入本站，并设为默认模型： ~/.openclaw/openclaw.json： ``` { "agents": { "defaults": { "model": { "primary": "tokenjoy/claude-sonnet-5-5" } } }, "models": { "mode": "merge", "providers": { "tokenjoy": { "baseUrl": "https://api.tokenjoy.org/v1", "apiKey": "${TOKENJOY_API_KEY}", "api": "openai-completions", "models": [ { "id": "claude-sonnet-5-5", "name": "claude-sonnet-5-5" } ] } } } } ``` 然后把 Key 写进 OpenClaw 的环境文件。网关作为后台服务运行，读不到终端里 `export` 的变量，所以要写在这里：API Key 在控制台的 [API Keys](https://tokenjoy.org/console/keys) 页创建。 **macOS / Linux：** ~/.openclaw/.env： **Windows：** %USERPROFILE%\.openclaw\.env： ``` TOKENJOY_API_KEY=<你的 API Key> ``` ### 3. 开始使用 重启 OpenClaw 后，可以在 Web UI 或终端中对话： ``` openclaw gateway restart openclaw dashboard # 打开 Web UI openclaw tui # 在终端中打开 ``` --- # 接入 Cursor > 网页版：https://tokenjoy.org/docs/agents/cursor Cursor 是基于 VS Code 的 AI 编辑器，支持自定义 OpenAI 兼容的接口地址。 ### 1. 配置接口 打开 **Settings → Models**，在 API Keys 中： Settings → Models： ``` OpenAI API Key <你的 API Key> Override Base URL https://api.tokenjoy.org/v1 ``` ### 2. 添加模型 在模型列表中点 **Add model**，手动添加要用的模型名，例如 `claude-sonnet-5-5`，并取消勾选不使用的内置模型。 ### 3. 开始使用 在对话框的模型选择器中选择刚添加的模型。 --- # 接入 Cline > 网页版：https://tokenjoy.org/docs/agents/cline Cline 是 VS Code 中的开源 AI 编程助手。 ### 1. 安装 Cline 在 VS Code 扩展市场中搜索 Cline 并安装。 ### 2. 配置接口 打开 Cline 面板的设置，选择 API Provider： Cline → Settings： ``` API Provider Anthropic API Key <你的 API Key> Use custom base URL https://api.tokenjoy.org Model claude-sonnet-5-5 ``` 想用其他厂商的模型，把 API Provider 换成 **OpenAI Compatible**，Base URL 填写 `https://api.tokenjoy.org/v1`，Model ID 填写 [模型列表](https://tokenjoy.org/docs/models.md)中的模型名。 ### 3. 开始使用 保存后即可在 Cline 面板中对话。 --- # 接入 WorkBuddy/CodeBuddy > 网页版：https://tokenjoy.org/docs/agents/codebuddy WorkBuddy/CodeBuddy 是腾讯推出的 AI Agent 与编程助手，支持通过本地配置文件添加 OpenAI 兼容的自定义模型。 ### 1. 安装 WorkBuddy/CodeBuddy 安装并登录后，至少打开一次项目目录，让应用创建本地配置目录。 ### 2. 配置本地模型 创建或编辑用户级配置文件 `~/.codebuddy/models.json`（Windows 为 `C:\Users\<用户名>\.codebuddy\models.json`）。只想对某个项目生效时，放在项目的 `.codebuddy/models.json`。 .codebuddy/models.json： ``` { "models": [ { "id": "claude-sonnet-5-5", "name": "claude-sonnet-5-5", "vendor": "TokenJoy", "url": "https://api.tokenjoy.org/v1/chat/completions", "apiKey": "${TOKENJOY_API_KEY}", "supportsToolCall": true, "supportsImages": true } ], "availableModels": [ "claude-sonnet-5-5" ] } ``` 文件请保存为 UTF-8 无 BOM。然后设置 Key：API Key 在控制台的 [API Keys](https://tokenjoy.org/console/keys) 页创建。 **macOS / Linux：** ``` export TOKENJOY_API_KEY="<你的 API Key>" ``` **Windows：** ``` setx TOKENJOY_API_KEY "<你的 API Key>" ``` ### 3. 重启并选择模型 完全退出后重新打开，在模型选择器中选择刚添加的模型。如果界面里直接显示了 `${TOKENJOY_API_KEY}`，请从已设置该变量的终端启动应用，或把 `apiKey` 改成真实的 Key。 --- # 接入 Cherry Studio > 网页版：https://tokenjoy.org/docs/agents/cherry Cherry Studio 是一款支持多家模型服务的桌面 AI 客户端。 ### 1. 添加提供商 打开 **设置 → 模型服务**，点 **添加**： 设置 → 模型服务： ``` 提供商名称 TokenJoy 提供商类型 OpenAI API 密钥 <你的 API Key> API 地址 https://api.tokenjoy.org ``` ### 2. 添加模型 点 **管理** 拉取模型列表，添加要用的模型。 ### 3. 开始使用 在对话页顶部选择 TokenJoy 下的模型。 --- # 接入其他 Agent > 网页版：https://tokenjoy.org/docs/agents/other 本文档没有单独介绍的 Agent 工具、编辑器插件和聊天客户端，只要支持自定义 API 地址，都可以接入本站。不同工具的设置界面各不相同，但要填的东西只有四样：**接口格式**、**API 地址**、**API Key** 和**模型名**。按下面的步骤逐项确认即可。 ## 1. 确认工具支持的接口格式 本站同时提供三种接口格式。打开工具的模型设置，看它的「提供商类型」「Provider」「API 类型」之类的选项里有哪一种，对照下表选择，并填写对应的 API 地址： | 接口格式 | 设置里常见的叫法 | API 地址 | 适合的模型 | | --- | --- | --- | --- | | Anthropic Messages | Anthropic、Claude、`anthropic-messages` | `https://api.tokenjoy.org` | Claude 系列，推荐 | | OpenAI Chat Completions | OpenAI、OpenAI 兼容、OpenAI Compatible、`openai-completions` | `https://api.tokenjoy.org/v1` | 全部模型，兼容性最好 | | OpenAI Responses | OpenAI Responses、`responses` | `https://api.tokenjoy.org/v1` | GPT 系列，推荐 | 几条选择建议： - 工具同时支持多种格式时，用 Claude 模型选 Anthropic 格式，用 GPT 模型选 Responses 格式，思考过程、工具调用和缓存计费都最完整。 - 只有「OpenAI 兼容」一种选项时也没问题：Chat Completions 格式可以调用本站的全部模型，包括 Claude。 - 一个提供商通常只能选一种格式。想同时用 Claude 和 GPT 的原生格式，就添加两个提供商，分别填写。 ## 2. 填对 API 地址 最常见的问题是地址里的 `/v1` 多了或少了。判断方法是看工具最终把请求发到哪里，正确的完整地址是： | 接口格式 | 完整的请求地址 | | --- | --- | | Anthropic Messages | `https://api.tokenjoy.org/v1/messages` | | OpenAI Chat Completions | `https://api.tokenjoy.org/v1/chat/completions` | | OpenAI Responses | `https://api.tokenjoy.org/v1/responses` | - 大多数 OpenAI 格式的工具会在你填的地址后面加 `/chat/completions`，所以填 `https://api.tokenjoy.org/v1`。 - Anthropic 官方 SDK 以及基于它的工具会自己加 `/v1/messages`，所以填 `https://api.tokenjoy.org`，不带 `/v1`。 - 少数工具要求填写完整的请求地址（输入框提示里带有 `/chat/completions`），这时直接填上表中的完整地址。 - 拿不准时先按上表填，测试时如果返回 404，再加上或去掉 `/v1` 试一次。 ## 3. 填写 API Key 和模型名 API Key 填写本站的 Key，不要填 OpenAI 或 Anthropic 官方的 Key。API Key 在控制台的 [API Keys](https://tokenjoy.org/console/keys) 页创建。 本站同时接受 `Authorization: Bearer` 和 `x-api-key` 两种请求头，工具用哪一种都可以。 模型名必须与[模型列表](https://tokenjoy.org/docs/models.md)中的名字完全一致，例如 `claude-sonnet-5-5`、`gpt-6.1-terra`。很多工具有「获取模型列表」或「拉取模型」按钮，会从 `https://api.tokenjoy.org/v1/models` 自动读取，可以直接勾选；没有这个按钮就手动输入。 如果工具要求填写上下文长度、最大输出 token 等参数，参照模型列表中的数值填写；不确定时保持默认。 ## 4. 先用命令行确认 Key 和地址可用 在工具里排查问题比较费时，建议先在终端里确认 Key 和地址都没问题。先把 Key 设置为环境变量： **macOS / Linux：** 终端： ``` export TOKENJOY_API_KEY="<你的 API Key>" ``` **Windows：** PowerShell，执行后重新打开： ``` setx TOKENJOY_API_KEY "<你的 API Key>" ``` 列出可用模型，能看到模型名就说明 Key 和地址都正确： 获取模型列表： **macOS / Linux：** ``` curl https://api.tokenjoy.org/v1/models \ -H "Authorization: Bearer $TOKENJOY_API_KEY" ``` **Windows：** ``` Invoke-RestMethod https://api.tokenjoy.org/v1/models ` -Headers @{ Authorization = "Bearer $env:TOKENJOY_API_KEY" } ``` 再按工具要用的格式发一条最简单的请求，能收到回复就说明这种格式可用： Anthropic 格式： **macOS / Linux：** ``` curl https://api.tokenjoy.org/v1/messages \ -H "x-api-key: $TOKENJOY_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model": "claude-sonnet-5-5", "max_tokens": 64, "messages": [{"role": "user", "content": "Hi"}]}' ``` **Windows：** ``` Invoke-RestMethod https://api.tokenjoy.org/v1/messages -Method Post ` -Headers @{ "x-api-key" = $env:TOKENJOY_API_KEY; "anthropic-version" = "2023-06-01" } ` -ContentType "application/json" ` -Body '{"model": "claude-sonnet-5-5", "max_tokens": 64, "messages": [{"role": "user", "content": "Hi"}]}' ``` OpenAI 格式： **macOS / Linux：** ``` curl https://api.tokenjoy.org/v1/chat/completions \ -H "Authorization: Bearer $TOKENJOY_API_KEY" \ -H "content-type: application/json" \ -d '{"model": "gpt-6.1-terra", "messages": [{"role": "user", "content": "Hi"}]}' ``` **Windows：** ``` Invoke-RestMethod https://api.tokenjoy.org/v1/chat/completions -Method Post ` -Headers @{ Authorization = "Bearer $env:TOKENJOY_API_KEY" } ` -ContentType "application/json" ` -Body '{"model": "gpt-6.1-terra", "messages": [{"role": "user", "content": "Hi"}]}' ``` ## 5. 在工具中测试 保存设置后，在工具里选中刚添加的模型，发一条简单的消息。很多工具的设置页有「检查」「测试连接」按钮，也可以先点一下。然后到控制台的[概览](https://tokenjoy.org/console)页，在「请求记录」里确认出现了这次调用。 ## 常见问题 | 现象 | 原因和解决办法 | | --- | --- | | 401 认证失败 | 检查 Key 是否完整、有没有多余的空格或换行；确认 Key 在控制台中处于启用状态，账户余额充足 | | 404 接口不存在 | API 地址的 `/v1` 多了或少了，对照第 2 步检查；也可能把 Anthropic 格式的地址填进了 OpenAI 格式的提供商 | | 400 模型不存在 | 模型名与[模型列表](https://tokenjoy.org/docs/models.md)不一致，注意大小写和版本号 | | 请求仍然发往官方 | 系统或终端里设置的 `OPENAI_BASE_URL`、`ANTHROPIC_BASE_URL`、`OPENAI_API_KEY` 等环境变量覆盖了工具里的设置，删除后重启工具 | | 后台运行的工具读不到 Key | 通过系统服务或桌面图标启动的程序读不到终端里 `export` 的环境变量，把 Key 直接填进工具设置，或写进它自己的配置文件 | | Codex 的 `/model` 里只有 GPT 模型 | 配置里缺少 `model_catalog_url`，重新运行[接入 Codex](https://tokenjoy.org/docs/agents/codex.md)里的一键命令，或手动加上这一行；仍然没有时升级 Codex | | 工具调用或思考过程异常 | 换成该模型的原生格式：Claude 用 Anthropic 格式，GPT 用 Responses 格式 | 其他错误码的含义见[错误码](https://tokenjoy.org/docs/error-codes.md)。仍然无法接入时，请把工具名称、版本和报错截图发给我们。 --- # 多轮对话 > 网页版：https://tokenjoy.org/docs/guides/multi-round 对话接口是无状态的，服务端不会记住之前的请求。每一轮都需要把完整的对话历史放进 `messages` 一起发送。 下面的例子中，第一轮的 messages 是： `[{"role": "user", "content": "世界上最高的山是哪座？"}]` 第二轮把模型的回复和新问题追加进去，messages 变为：用户提问、模型回答、用户追问三条。 **OpenAI 格式** ``` from openai import OpenAI client = OpenAI(api_key="<你的 API Key>", base_url="https://api.tokenjoy.org/v1") # 第一轮 messages = [{"role": "user", "content": "世界上最高的山是哪座？"}] response = client.chat.completions.create(model="gpt-6.1-terra", messages=messages) messages.append(response.choices[0].message) print(messages[-1].content) # 第二轮：把上一轮的回复带上，再追加新问题 messages.append({"role": "user", "content": "第二高的呢？"}) response = client.chat.completions.create(model="gpt-6.1-terra", messages=messages) print(response.choices[0].message.content) ``` **Anthropic 格式** ``` import anthropic client = anthropic.Anthropic(api_key="<你的 API Key>", base_url="https://api.tokenjoy.org") # 第一轮 messages = [{"role": "user", "content": "世界上最高的山是哪座？"}] response = client.messages.create(model="claude-sonnet-5-5", max_tokens=1024, messages=messages) messages.append({"role": "assistant", "content": response.content}) print(response.content[0].text) # 第二轮：把上一轮的回复带上，再追加新问题 messages.append({"role": "user", "content": "第二高的呢？"}) response = client.messages.create(model="claude-sonnet-5-5", max_tokens=1024, messages=messages) print(response.content[0].text) ``` 历史消息每一轮都会作为输入重新计费。对话很长时，可以只保留最近若干轮，或用摘要替代早期内容，见 [Token 用量计算](https://tokenjoy.org/docs/token-usage.md)。 --- # 流式输出 > 网页版：https://tokenjoy.org/docs/guides/streaming 把 `stream` 设为 `true`，模型会边生成边返回，以 SSE（Server-Sent Events）的形式逐段推送。长回复、长任务建议使用流式输出，能更早看到结果，也不容易因为长时间没有数据而被中间网络断开。 **OpenAI 格式** ``` from openai import OpenAI client = OpenAI(api_key="<你的 API Key>", base_url="https://api.tokenjoy.org/v1") stream = client.chat.completions.create( model="gpt-6.1-terra", messages=[{"role": "user", "content": "写一首关于秋天的短诗"}], stream=True, ) for chunk in stream: if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True) ``` **Anthropic 格式** ``` import anthropic client = anthropic.Anthropic(api_key="<你的 API Key>", base_url="https://api.tokenjoy.org") with client.messages.stream( model="claude-sonnet-5-5", max_tokens=1024, messages=[{"role": "user", "content": "写一首关于秋天的短诗"}], ) as stream: for text in stream.text_stream: print(text, end="", flush=True) ``` 流式输出结束时，最后的数据块里带有本次请求的 token 用量。OpenAI 格式需要在请求中加上 `stream_options: {"include_usage": true}` 才会返回。 --- # Tool Calls > 网页版：https://tokenjoy.org/docs/guides/tool-calls Tool Calls 让模型可以调用外部工具。你在请求中描述可用的工具，模型决定是否调用、用什么参数；你的代码执行工具后把结果交回，模型再据此回答。工具由你的代码执行，模型本身不会访问外部系统。 **OpenAI 格式** ``` import json from openai import OpenAI client = OpenAI(api_key="<你的 API Key>", base_url="https://api.tokenjoy.org/v1") tools = [{ "type": "function", "function": { "name": "get_weather", "description": "查询某个城市的天气", "parameters": { "type": "object", "properties": {"city": {"type": "string", "description": "城市名"}}, "required": ["city"], }, }, }] messages = [{"role": "user", "content": "杭州今天天气怎么样？"}] response = client.chat.completions.create(model="gpt-6.1-terra", messages=messages, tools=tools) message = response.choices[0].message messages.append(message) # 模型请求调用工具：执行后把结果交回给模型 for call in message.tool_calls or []: args = json.loads(call.function.arguments) result = f"{args['city']}：晴，24°C" # 这里换成你自己的实现 messages.append({"role": "tool", "tool_call_id": call.id, "content": result}) response = client.chat.completions.create(model="gpt-6.1-terra", messages=messages, tools=tools) print(response.choices[0].message.content) ``` **Anthropic 格式** ``` import anthropic client = anthropic.Anthropic(api_key="<你的 API Key>", base_url="https://api.tokenjoy.org") tools = [{ "name": "get_weather", "description": "查询某个城市的天气", "input_schema": { "type": "object", "properties": {"city": {"type": "string", "description": "城市名"}}, "required": ["city"], }, }] messages = [{"role": "user", "content": "杭州今天天气怎么样？"}] response = client.messages.create(model="claude-sonnet-5-5", max_tokens=1024, messages=messages, tools=tools) messages.append({"role": "assistant", "content": response.content}) # 模型请求调用工具：执行后把结果交回给模型 results = [] for block in response.content: if block.type == "tool_use": result = f"{block.input['city']}：晴，24°C" # 这里换成你自己的实现 results.append({"type": "tool_result", "tool_use_id": block.id, "content": result}) messages.append({"role": "user", "content": results}) response = client.messages.create(model="claude-sonnet-5-5", max_tokens=1024, messages=messages, tools=tools) print(response.content[0].text) ``` Agent 工具（Claude Code、Codex 等）正是基于这一机制读写文件、执行命令的。 --- # 使用 OpenAI API > 网页版：https://tokenjoy.org/docs/guides/openai 本站兼容 OpenAI 的 Chat Completions 接口。使用 OpenAI SDK 或兼容软件时，把 base_url 设为 `https://api.tokenjoy.org/v1`，api_key 设为你的 Key 即可。Claude、Gemini 等其他厂商的模型也可以用这个格式调用。 | 参数 | 值 | | --- | --- | | base_url | `https://api.tokenjoy.org/v1` | | api_key | 你的 API Key | | 接口 | `POST /v1/chat/completions`，见 [API 文档](https://tokenjoy.org/docs/api/chat-completions.md) | ## 示例 **curl** ``` curl https://api.tokenjoy.org/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${TOKENJOY_API_KEY}" \ -d '{ "model": "gpt-6.1-terra", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"} ], "stream": false }' ``` **python** ``` # pip3 install openai import os from openai import OpenAI client = OpenAI( api_key=os.environ.get("TOKENJOY_API_KEY"), base_url="https://api.tokenjoy.org/v1", ) response = client.chat.completions.create( model="gpt-6.1-terra", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Hello!"}, ], stream=False, ) print(response.choices[0].message.content) ``` **nodejs** ``` // npm install openai import OpenAI from "openai"; const openai = new OpenAI({ baseURL: "https://api.tokenjoy.org/v1", apiKey: process.env.TOKENJOY_API_KEY, }); async function main() { const completion = await openai.chat.completions.create({ model: "gpt-6.1-terra", messages: [ { role: "system", content: "You are a helpful assistant." }, { role: "user", content: "Hello!" }, ], stream: false, }); console.log(completion.choices[0].message.content); } main(); ``` Codex 等使用 Responses 接口的工具，见[使用 Responses API](https://tokenjoy.org/docs/guides/responses.md)。 --- # 使用 Responses API > 网页版：https://tokenjoy.org/docs/guides/responses 本站兼容 OpenAI 的 Responses 接口（`POST /v1/responses`），Codex 用的就是这个接口。base_url 与 Chat Completions 相同：`https://api.tokenjoy.org/v1`。 ## 示例 **curl** ``` curl https://api.tokenjoy.org/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${TOKENJOY_API_KEY}" \ -d '{ "model": "gpt-6.1-terra", "instructions": "You are a helpful assistant.", "input": "Hello!" }' ``` **python** ``` import os from openai import OpenAI client = OpenAI(api_key=os.environ.get("TOKENJOY_API_KEY"), base_url="https://api.tokenjoy.org/v1") response = client.responses.create( model="gpt-6.1-terra", instructions="You are a helpful assistant.", input="Hello!", ) print(response.output_text) ``` **nodejs** ``` import OpenAI from "openai"; const openai = new OpenAI({ baseURL: "https://api.tokenjoy.org/v1", apiKey: process.env.TOKENJOY_API_KEY }); const response = await openai.responses.create({ model: "gpt-6.1-terra", instructions: "You are a helpful assistant.", input: "Hello!", }); console.log(response.output_text); ``` 在 Codex 中使用本站，见 [接入 Codex](https://tokenjoy.org/docs/agents/codex.md)。 --- # 使用 Anthropic API > 网页版：https://tokenjoy.org/docs/guides/anthropic 本站兼容 Anthropic 的 Messages 接口。使用 Anthropic SDK 或 Claude Code 等兼容软件时，把 base_url 设为 `https://api.tokenjoy.org`（不带 /v1，SDK 会自动拼上），api_key 设为你的 Key 即可。GPT 等其他厂商的模型也可以用这个格式调用。 | 参数 | 值 | | --- | --- | | base_url | `https://api.tokenjoy.org` | | api_key | 你的 API Key，放在 `x-api-key` 或 `Authorization: Bearer` 请求头中 | | 接口 | `POST /v1/messages`，见 [API 文档](https://tokenjoy.org/docs/api/messages.md) | ## 示例 **curl** ``` curl https://api.tokenjoy.org/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: ${TOKENJOY_API_KEY}" \ -H "anthropic-version: 2023-06-01" \ -d '{ "model": "claude-sonnet-5-5", "max_tokens": 1024, "system": "You are a helpful assistant.", "messages": [ {"role": "user", "content": "Hello!"} ], "stream": false }' ``` **python** ``` # pip3 install anthropic import os import anthropic client = anthropic.Anthropic( api_key=os.environ.get("TOKENJOY_API_KEY"), base_url="https://api.tokenjoy.org", ) message = client.messages.create( model="claude-sonnet-5-5", max_tokens=1024, system="You are a helpful assistant.", messages=[ {"role": "user", "content": "Hello!"}, ], ) print(message.content[0].text) ``` **nodejs** ``` // npm install @anthropic-ai/sdk import Anthropic from "@anthropic-ai/sdk"; const anthropic = new Anthropic({ baseURL: "https://api.tokenjoy.org", apiKey: process.env.TOKENJOY_API_KEY, }); async function main() { const message = await anthropic.messages.create({ model: "claude-sonnet-5-5", max_tokens: 1024, system: "You are a helpful assistant.", messages: [{ role: "user", content: "Hello!" }], }); console.log(message.content[0].text); } main(); ``` ## 环境变量 Anthropic SDK 和 Claude Code 都会读取这两个环境变量，设置后代码里可以不写 base_url 和 api_key： **macOS / Linux** ``` export ANTHROPIC_BASE_URL="https://api.tokenjoy.org" export ANTHROPIC_API_KEY="${TOKENJOY_API_KEY}" ``` **Windows** ``` setx ANTHROPIC_BASE_URL "https://api.tokenjoy.org" setx ANTHROPIC_API_KEY "<你的 API Key>" ``` --- # 实时语音 > 网页版：https://tokenjoy.org/docs/guides/realtime 实时语音模型直接听语音、说语音：你把用户说的话（音频）发过去，模型用语音回答，同时给出文字稿。整个对话走一条 WebSocket 连接，首段语音一般在 1～2 秒内开始返回，适合做语音助手、口语陪练、电话客服等。接口与 OpenAI Realtime API 兼容。想先听听效果，可以在控制台的 [Playground](https://tokenjoy.org/console/playground) 里点输入框旁的麦克风，直接和它语音对话。 | 参数 | 值 | | --- | --- | | 地址 | `https://api.tokenjoy.org/v1/realtime?model=gpt-realtime` | | 认证 | 请求头 `Authorization: Bearer <你的 API Key>` | | 音频格式 | 默认 24 kHz、16 位、单声道 PCM（小端），base64 编码后放进 JSON 事件 | | 接口说明 | [API 文档 · 实时语音](https://tokenjoy.org/docs/api/realtime.md) | ## 可用模型 | 模型 | 说明 | | --- | --- | | `gpt-realtime` | 效果最好，适合对话质量要求高的场景 | | `gpt-realtime-mini` | 价格约为前者的三分之一，速度相近，适合大量调用 | 实时语音模型不会出现在 [GET /v1/models](https://tokenjoy.org/docs/api/models.md) 的列表里，直接在地址的 `model` 参数中填写即可。 ## 第一次调用 连接后先用 `session.update` 设置回答方式和音色，再发一条文字消息，用 `response.create` 让模型回答。模型的语音以 `response.output_audio.delta` 分段返回，一轮回答以 `response.done` 结束，其中带有本轮的 token 用量。 **python** 需要 `pip install websockets`。把模型的回答保存为 `reply.wav`，同时打印文字稿。 ``` import asyncio, base64, json, os, wave import websockets URL = "https://api.tokenjoy.org/v1/realtime?model=gpt-realtime" async def main(): headers = {"Authorization": f"Bearer {os.environ['TOKENJOY_API_KEY']}"} async with websockets.connect(URL, additional_headers=headers, max_size=None) as ws: await ws.send(json.dumps({"type": "session.update", "session": { "type": "realtime", "output_modalities": ["audio"], "instructions": "你是一个友好的中文语音助手，回答简洁。", "audio": {"output": {"voice": "marin"}}, }})) await ws.send(json.dumps({"type": "conversation.item.create", "item": { "type": "message", "role": "user", "content": [{"type": "input_text", "text": "你好，用一句话介绍一下你自己。"}], }})) await ws.send(json.dumps({"type": "response.create"})) audio = bytearray() async for message in ws: event = json.loads(message) if event["type"] == "response.output_audio.delta": audio += base64.b64decode(event["delta"]) elif event["type"] == "response.output_audio_transcript.delta": print(event["delta"], end="", flush=True) elif event["type"] == "error": raise RuntimeError(event["error"]) elif event["type"] == "response.done": print("\nusage:", event["response"]["usage"]) break # 输出是 24 kHz、16 位、单声道 PCM，加上 WAV 头就能直接播放 with wave.open("reply.wav", "wb") as f: f.setnchannels(1) f.setsampwidth(2) f.setframerate(24000) f.writeframes(audio) asyncio.run(main()) ``` **nodejs** Node.js 22 及以上自带 WebSocket，不需要安装依赖。 ``` const ws = new WebSocket("https://api.tokenjoy.org/v1/realtime?model=gpt-realtime", { headers: { Authorization: `Bearer ${process.env.TOKENJOY_API_KEY}` }, }); ws.onopen = () => { ws.send(JSON.stringify({ type: "session.update", session: { type: "realtime", output_modalities: ["audio"], audio: { output: { voice: "marin" } } }, })); ws.send(JSON.stringify({ type: "conversation.item.create", item: { type: "message", role: "user", content: [{ type: "input_text", text: "你好，用一句话介绍一下你自己。" }] }, })); ws.send(JSON.stringify({ type: "response.create" })); }; const audio = []; ws.onmessage = (message) => { const event = JSON.parse(message.data); if (event.type === "response.output_audio.delta") audio.push(Buffer.from(event.delta, "base64")); if (event.type === "response.output_audio_transcript.delta") process.stdout.write(event.delta); if (event.type === "error") console.error(event.error); if (event.type === "response.done") { console.log("\nusage:", event.response.usage); // Buffer.concat(audio) 是 24 kHz、16 位、单声道 PCM ws.close(); } }; ``` **OpenAI SDK** 需要较新版本的 openai 包（`pip install -U openai`）。SDK 会把 base_url 自动换成 WebSocket 地址。这个例子只要文字回答。 ``` import asyncio, os from openai import AsyncOpenAI client = AsyncOpenAI(api_key=os.environ["TOKENJOY_API_KEY"], base_url="https://api.tokenjoy.org/v1") async def main(): async with client.realtime.connect(model="gpt-realtime") as conn: await conn.session.update(session={"type": "realtime", "output_modalities": ["text"]}) await conn.conversation.item.create(item={ "type": "message", "role": "user", "content": [{"type": "input_text", "text": "用一句话介绍杭州。"}], }) await conn.response.create() async for event in conn: if event.type == "response.output_text.delta": print(event.delta, end="", flush=True) elif event.type == "response.done": print("\nusage:", event.response.usage) break asyncio.run(main()) ``` ## 发送语音 用 `input_audio_buffer.append` 把音频分段发过去。默认开着服务端语音检测（`server_vad`）：检测到用户停顿就自动结束这句话并开始回答，适合接麦克风实时说话。处理录好的音频文件时，可以像下面这样关掉检测，发完后自己 `commit` 并请求回答： ``` import asyncio, base64, json, os, wave import websockets URL = "https://api.tokenjoy.org/v1/realtime?model=gpt-realtime" async def main(): with wave.open("question.wav") as f: # 24 kHz、16 位、单声道 pcm = f.readframes(f.getnframes()) headers = {"Authorization": f"Bearer {os.environ['TOKENJOY_API_KEY']}"} async with websockets.connect(URL, additional_headers=headers, max_size=None) as ws: # 关掉服务端语音检测，由我们自己决定一句话什么时候说完 await ws.send(json.dumps({"type": "session.update", "session": { "type": "realtime", "output_modalities": ["audio"], "audio": {"input": {"turn_detection": None}, "output": {"voice": "marin"}}, }})) for i in range(0, len(pcm), 48000): # 每次发 1 秒音频 chunk = base64.b64encode(pcm[i:i + 48000]).decode() await ws.send(json.dumps({"type": "input_audio_buffer.append", "audio": chunk})) await ws.send(json.dumps({"type": "input_audio_buffer.commit"})) await ws.send(json.dumps({"type": "response.create"})) audio = bytearray() async for message in ws: event = json.loads(message) if event["type"] == "response.output_audio.delta": audio += base64.b64decode(event["delta"]) elif event["type"] == "error": raise RuntimeError(event["error"]) elif event["type"] == "response.done": print("usage:", event["response"]["usage"]) break with wave.open("answer.wav", "wb") as f: f.setnchannels(1) f.setsampwidth(2) f.setframerate(24000) f.writeframes(audio) asyncio.run(main()) ``` 多轮对话在同一条连接里继续发送即可，服务端会记住这条连接里之前说过的内容，不需要重复发送历史。 ## 在网页里使用 浏览器自带的 WebSocket 不能设置 `Authorization` 请求头，而且 API Key 不能放进网页代码，否则任何访问者都能拿去使用。请在你自己的后端做一层转发：浏览器连你的后端，后端校验登录后带上 Key 连接 TokenJoy，再把消息原样双向转发。 ``` // 需要 npm install ws。浏览器连到这个服务，由它带上 Key 转发到 TokenJoy。 import { WebSocketServer } from "ws"; const UPSTREAM = "https://api.tokenjoy.org/v1/realtime?model=gpt-realtime"; const server = new WebSocketServer({ port: Number(process.env.PORT ?? 8080) }); server.on("connection", (browser, request) => { // 在这里校验你自己网站的登录状态，不通过就 browser.close(1008) const upstream = new WebSocket(UPSTREAM, { headers: { Authorization: `Bearer ${process.env.TOKENJOY_API_KEY}` } }); const pending = []; upstream.onopen = () => pending.splice(0).forEach((m) => upstream.send(m)); upstream.onmessage = (m) => browser.send(m.data); upstream.onclose = () => browser.close(); browser.on("message", (m) => { const text = m.toString(); if (upstream.readyState === WebSocket.OPEN) upstream.send(text); else pending.push(text); }); browser.on("close", () => upstream.close()); }); ``` ## 计费 ### 每分钟大约花多少 一来一回的正常对话（双方轮流说话），按通话时长估算每分钟的花费，单位美元： | 模型 | 本站价（约） | 官方价（约） | | --- | --- | --- | | `gpt-realtime` | — | $0.09–0.11 / 分钟 | | `gpt-realtime-mini` | — | $0.020–0.030 / 分钟 | 这是本站 2026-10 在线上实测的范围，用户和模型各说一半左右。实际按 token 扣费：模型说得多、对话越长，每分钟越贵；只用文字回答会便宜很多。 ### 按 token 的单价 与其他模型一样，按官方价计价、按实际 token 用量从余额扣费，本站折扣同样适用。每轮回答结束时按 `response.done` 中的用量结算，音频和文字分开计价（官方价，美元 / 百万 token）： | 模型 | 音频输入 | 音频输入（缓存） | 音频输出 | 文字输入 | 文字输入（缓存） | 文字输出 | | --- | --- | --- | --- | --- | --- | --- | | `gpt-realtime` | $32 | $0.40 | $64 | $4 | $0.40 | $16 | | `gpt-realtime-mini` | $10 | $0.30 | $20 | $0.60 | $0.06 | $2.40 | - 换算到时长：用户说 1 分钟约 600 个音频输入 token，模型说 1 分钟约 1,200 个音频输出 token。 - 同一条连接里，之前的对话会在每轮作为输入再计一次，所以对话越长每分钟越贵；重复的部分大多按便宜很多的缓存价计。内容无关的长对话可以断开重连，从头开始。 - 用量在控制台「概览」页的「用量明细」里按模型列出，大约每 30 秒结算一次。见 [Token 用量计算](https://tokenjoy.org/docs/token-usage.md)。 ## 限制 - 目前只支持 WebSocket 连接，不支持 WebRTC。 - 单条连接有时长上限（默认 60 分钟），到时服务端以关闭码 1001 结束连接，需要时重新连接即可。 - 余额用完时无法建立新连接；通话中途用完时，连接会在你发送下一条消息时以关闭码 1008 断开。 - 关闭码和错误的含义见 [API 文档 · 实时语音](https://tokenjoy.org/docs/api/realtime.md)。价格之外的其他模型见[模型价格页](https://tokenjoy.org/models)。 --- # 概览与认证 > 网页版：https://tokenjoy.org/docs/api TokenJoy API 兼容 OpenAI 和 Anthropic 的接口格式。所有接口都在同一个地址下： ``` https://api.tokenjoy.org ``` ## 认证 在请求头中携带 API Key，以下三种方式任选其一： | 请求头 | 常见用法 | | --- | --- | | `Authorization: Bearer ` | OpenAI SDK 及大部分工具 | | `x-api-key: ` | Anthropic SDK、Claude Code | | `x-goog-api-key: ` | Gemini 格式的客户端 | ## 接口列表 | 接口 | 说明 | | --- | --- | | [`POST /v1/chat/completions`](https://tokenjoy.org/docs/api/chat-completions.md) | OpenAI Chat Completions，支持流式 | | [`POST /v1/responses`](https://tokenjoy.org/docs/api/responses.md) | OpenAI Responses，Codex 使用 | | [`POST /v1/messages`](https://tokenjoy.org/docs/api/messages.md) | Anthropic Messages，支持流式 | | [`POST /v1/messages/count_tokens`](https://tokenjoy.org/docs/api/count-tokens.md) | 计算输入的 token 数 | | [`POST /v1/embeddings`](https://tokenjoy.org/docs/api/embeddings.md) | 文本向量 | | [`GET /v1/realtime`](https://tokenjoy.org/docs/api/realtime.md) | 实时语音（WebSocket），GPT Realtime 模型 | | [`GET /v1/models`](https://tokenjoy.org/docs/api/models.md) | 当前可用的模型列表 | 出错时返回对应的 HTTP 状态码和 JSON 格式的错误信息，见[错误码](https://tokenjoy.org/docs/error-codes.md)。 --- # 对话补全 > 网页版：https://tokenjoy.org/docs/api/chat-completions **POST** `https://api.tokenjoy.org/v1/chat/completions` 根据对话历史生成回复，与 OpenAI Chat Completions 接口兼容。 ## 请求参数 | 参数 | 类型 | 说明 | | --- | --- | --- | | `model` | string | 必填。模型名，见[模型列表](https://tokenjoy.org/docs/models.md) | | `messages` | array | 必填。对话历史，每条包含 `role`（system / user / assistant / tool）和 `content` | | `stream` | boolean | 是否以 SSE 流式返回，默认 false | | `max_tokens` | integer | 最多生成的 token 数 | | `temperature` | number | 采样温度，越高越随机 | | `reasoning_effort` | string | Gemini 3.8 Flash 的思考强度：`low`、`medium`、`high`；省略时由模型自动选择 | | `tools` | array | 可供模型调用的工具，见 [Tool Calls](https://tokenjoy.org/docs/guides/tool-calls.md) | | `response_format` | object | 例如 `{"type": "json_object"}` 要求输出 JSON | ## 示例 ``` curl https://api.tokenjoy.org/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${TOKENJOY_API_KEY}" \ -d '{"model": "gpt-6.1-terra", "messages": [{"role": "user", "content": "Hello!"}]}' ``` ## 响应 ``` { "id": "chatcmpl-...", "object": "chat.completion", "model": "gpt-6.1-terra", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! How can I help you today?" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 9, "completion_tokens": 10, "total_tokens": 19 } } ``` --- # Responses > 网页版：https://tokenjoy.org/docs/api/responses **POST** `https://api.tokenjoy.org/v1/responses` OpenAI 的新一代对话接口，与 OpenAI Responses API 兼容，Codex 使用的就是这个接口。 ## 请求参数 | 参数 | 类型 | 说明 | | --- | --- | --- | | `model` | string | 必填。模型名 | | `input` | string \| array | 必填。输入文本，或消息列表 | | `instructions` | string | 系统指令 | | `stream` | boolean | 是否流式返回 | | `max_output_tokens` | integer | 最多生成的 token 数 | | `tools` | array | 可供模型调用的工具 | | `reasoning` | object | 推理强度，例如 `{"effort": "medium"}` | ## 示例 ``` curl https://api.tokenjoy.org/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${TOKENJOY_API_KEY}" \ -d '{"model": "gpt-6.1-terra", "input": "Hello!"}' ``` 更多用法见[使用 Responses API](https://tokenjoy.org/docs/guides/responses.md)。 --- # 向量 > 网页版：https://tokenjoy.org/docs/api/embeddings **POST** `https://api.tokenjoy.org/v1/embeddings` 把文本转换成向量，用于检索、聚类等，与 OpenAI Embeddings 接口兼容。只有支持向量的模型可以使用这个接口。 | 参数 | 类型 | 说明 | | --- | --- | --- | | `model` | string | 必填。向量模型名 | | `input` | string \| array | 必填。要转换的文本，可以是数组 | ``` curl https://api.tokenjoy.org/v1/embeddings \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${TOKENJOY_API_KEY}" \ -d '{"model": "<向量模型名>", "input": "Hello!"}' ``` --- # 实时语音 > 网页版：https://tokenjoy.org/docs/api/realtime **GET** `https://api.tokenjoy.org/v1/realtime` 建立一条 WebSocket 连接进行实时语音对话，与 OpenAI Realtime API（GA 版）兼容。连接建立后，双方都发送 JSON 文本消息（事件），每条消息都有 `type` 字段。使用方法见 [API 指南 · 实时语音](https://tokenjoy.org/docs/guides/realtime.md)。 ## 连接参数 | 参数 | 位置 | 说明 | | --- | --- | --- | | `model` | 查询参数 | 必填。`gpt-realtime` 或 `gpt-realtime-mini` | | `Authorization` | 请求头 | `Bearer <你的 API Key>`。不支持把 Key 放在地址或 WebSocket 子协议里 | ## 客户端事件（你发送的） | 事件 | 说明 | | --- | --- | | `session.update` | 设置会话：`instructions`（系统提示）、`output_modalities`（`["audio"]` 或 `["text"]`）、`audio.output.voice`（音色，如 `marin`、`alloy`）、`audio.input.turn_detection`（语音检测，`null` 为关闭）、`tools`（函数调用）。`session.type` 固定为 `realtime` | | `input_audio_buffer.append` | 追加一段音频，`audio` 为 base64 编码的 PCM | | `input_audio_buffer.commit` | 把已追加的音频提交为一条用户消息（关闭语音检测时使用） | | `input_audio_buffer.clear` | 清空还没提交的音频 | | `conversation.item.create` | 添加一条消息，例如文字输入 `{"type": "message", "role": "user", "content": [{"type": "input_text", "text": "..."}]}`，或函数调用的结果 | | `response.create` | 请求模型回答 | | `response.cancel` | 打断正在进行的回答（例如用户插话） | ## 服务端事件（你收到的） | 事件 | 说明 | | --- | --- | | `session.created` | 连接建立后的第一条消息，带有会话的默认设置 | | `session.updated` | `session.update` 生效后返回 | | `input_audio_buffer.speech_started` | 语音检测开启时，检测到用户开始说话（可以借此停止播放、打断回答） | | `response.output_audio.delta` | 一段语音，`delta` 为 base64 编码的 PCM | | `response.output_audio_transcript.delta` | 语音回答对应的文字稿片段 | | `response.output_text.delta` | `output_modalities` 为 `["text"]` 时的文字片段 | | `response.function_call_arguments.done` | 模型要调用的函数及参数 | | `response.done` | 一轮回答结束，`response.usage` 是本轮用量，按它计费 | | `error` | 请求出错，`error.message` 说明原因；连接一般不会因此断开 | ## 用量 `response.done` 中的 `usage`：缓存部分包含在输入总数之内，文字和音频分开列出。 ``` "usage": { "total_tokens": 1500, "input_tokens": 1000, "output_tokens": 500, "input_token_details": { "text_tokens": 200, "audio_tokens": 800, "image_tokens": 0, "cached_tokens": 300, "cached_tokens_details": { "text_tokens": 100, "audio_tokens": 200, "image_tokens": 0 } }, "output_token_details": { "text_tokens": 100, "audio_tokens": 400 } } ``` ## 连接失败与关闭 | 情况 | 含义 | | --- | --- | | 握手返回 401 | Key 缺失或无效 | | 握手返回 402 / 429 | 余额用完，或上游暂时繁忙（429 时请稍后重试，见[限速与隔离](https://tokenjoy.org/docs/rate-limit.md)） | | 关闭码 1000 | 正常结束 | | 关闭码 1001，原因 `maximum call duration reached` | 连接达到时长上限（默认 60 分钟），重新连接即可 | | 关闭码 1008 | 余额用完或 Key 被停用、重置，充值或换用新 Key 后重新连接 | | 关闭码 1011 | 上游出错，可以重新连接 | 其他错误码见[错误码](https://tokenjoy.org/docs/error-codes.md)。 --- # 消息 > 网页版：https://tokenjoy.org/docs/api/messages **POST** `https://api.tokenjoy.org/v1/messages` 根据对话历史生成回复，与 Anthropic Messages 接口兼容。请求头需要带上 `anthropic-version: 2023-06-01`（SDK 会自动添加）。 ## 请求参数 | 参数 | 类型 | 说明 | | --- | --- | --- | | `model` | string | 必填。模型名，见[模型列表](https://tokenjoy.org/docs/models.md) | | `max_tokens` | integer | 必填。最多生成的 token 数 | | `messages` | array | 必填。对话历史，`role` 为 user 或 assistant | | `system` | string \| array | 系统提示词 | | `stream` | boolean | 是否以 SSE 流式返回，默认 false | | `temperature` | number | 采样温度 | | `tools` | array | 可供模型调用的工具，见 [Tool Calls](https://tokenjoy.org/docs/guides/tool-calls.md) | | `thinking` | object | 开启扩展思考，例如 `{"type": "enabled", "budget_tokens": 2048}` | ## 示例 ``` curl https://api.tokenjoy.org/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: ${TOKENJOY_API_KEY}" \ -H "anthropic-version: 2023-06-01" \ -d '{"model": "claude-sonnet-5-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello!"}]}' ``` ## 响应 ``` { "id": "msg_...", "type": "message", "role": "assistant", "model": "claude-sonnet-5-5", "content": [{ "type": "text", "text": "Hello! How can I help you today?" }], "stop_reason": "end_turn", "usage": { "input_tokens": 9, "output_tokens": 12 } } ``` --- # 计算 Token 数 > 网页版：https://tokenjoy.org/docs/api/count-tokens **POST** `https://api.tokenjoy.org/v1/messages/count_tokens` 计算一次请求的输入 token 数，不调用模型、不扣费。请求体与 [Messages](https://tokenjoy.org/docs/api/messages.md) 相同（不需要 `max_tokens`）。 ``` curl https://api.tokenjoy.org/v1/messages/count_tokens \ -H "Content-Type: application/json" \ -H "x-api-key: ${TOKENJOY_API_KEY}" \ -H "anthropic-version: 2023-06-01" \ -d '{"model": "claude-sonnet-5-5", "messages": [{"role": "user", "content": "Hello!"}]}' ``` ## 响应 ``` { "input_tokens": 9 } ``` 部分非 Claude 模型的计数是本站按通用分词器估算的，可能与实际计费略有出入。 --- # 模型列表 > 网页版：https://tokenjoy.org/docs/api/models **GET** `https://api.tokenjoy.org/v1/models` 列出你的 Key 当前可以调用的模型，返回 OpenAI 格式的列表。 **curl** ``` curl https://api.tokenjoy.org/v1/models \ -H "Authorization: Bearer ${TOKENJOY_API_KEY}" ``` **python** ``` import os from openai import OpenAI client = OpenAI(api_key=os.environ.get("TOKENJOY_API_KEY"), base_url="https://api.tokenjoy.org/v1") for m in client.models.list(): print(m.id) ``` ## 响应 ``` { "object": "list", "data": [ { "id": "claude-sonnet-4-6", "object": "model", "owned_by": "anthropic" }, ... ] } ``` --- # Claude API 成本怎么算：Token 计算与省钱方法 > 网页版：https://tokenjoy.org/docs/news/api-cost 2026-11-05 上线一个 AI 功能之前，最常被问的问题是：**这东西一个月要花多少钱？** Claude API 按 token 计费，只要弄清楚三件事——一次请求有多少 token、每类 token 多少钱、一天有多少次请求——成本就能算个八九不离十。 ## Token 是什么 Token 是模型读写文字的最小单位。模型不是按「字」或「词」收费，而是把文字切成 token，按 token 数计价。 - **英文**：一个 token 大约是 3～4 个字母，一个单词通常是 1～2 个 token； - **中文**：大致一个汉字一个 token 上下，常用词可能更省，生僻字和符号可能更多； - **代码**：缩进、括号、变量名都会占 token，同样长度的代码通常比自然语言更「费」token。 不同模型的分词方式不同，上面只是估算。要精确知道一段内容有多少 token，可以调用[计算 Token 数](https://tokenjoy.org/docs/api/count-tokens.md)接口，不产生费用；也可以看每次请求返回的 `usage` 字段，详见 [Token 用量计算](https://tokenjoy.org/docs/token-usage.md)。 ## 一次请求的四类 token Claude 的一次请求里，token 分四类，各有各的单价： | 类型 | 是什么 | 单价 | | --- | --- | --- | | 输入 | 你发给模型的内容：系统提示词、历史对话、本次问题、工具定义 | 基础价 | | 输出 | 模型生成的内容，包括思考过程 | 通常是输入的 5 倍 | | 缓存写入 | 第一次把一段前缀写进缓存 | 略高于输入价 | | 缓存读取 | 之后再次用到这段前缀 | 约为输入价的十分之一 | 有两点容易被忽略： 1. **多轮对话的输入会越来越长**。每一轮都要把之前的对话一起发过去，第 10 轮的输入里包含了前 9 轮的全部内容。 2. **输出比输入贵得多**。让模型「简要回答」、限制 `max_tokens`，往往比压缩输入更省钱。 ## 计算公式 ``` 单次费用 = 输入 token × 输入单价 + 输出 token × 输出单价 + 缓存写入 token × 缓存写入单价 + 缓存读取 token × 缓存读取单价 ``` 单价按「每百万 token 多少美元」标价。在 TokenJoy，每个单价都是官方价乘以该模型的价格倍率，[模型价格](https://tokenjoy.org/models)页逐条列出了每个模型的官方价和实付价，失败的请求不扣费。 ## 例子：估算一个客服机器人的月成本 假设用 `claude-haiku-4-5` 做客服机器人（官方价：输入每百万 token 1 美元，输出每百万 token 5 美元，以写作时的官方价为例，最新价格以[模型价格](https://tokenjoy.org/models)页为准）： - 每天 1,000 次对话； - 每次请求输入 2,000 token（其中 1,500 token 是固定的系统提示词和产品资料），输出 500 token。 **不用缓存：** ``` 输入：2,000 × 1 / 1,000,000 = $0.0020 输出： 500 × 5 / 1,000,000 = $0.0025 单次：$0.0045；每天 $4.5；每月（30 天）约 $135 ``` **把固定的 1,500 token 放进缓存：** ``` 未缓存输入： 500 × 1 / 1,000,000 = $0.00050 缓存读取： 1,500 × 0.1 / 1,000,000 = $0.00015 输出： 500 × 5 / 1,000,000 = $0.00250 单次：$0.00315；每天约 $3.15；每月约 $95 ``` 缓存写入只在缓存过期后的第一次请求发生，请求越密集占比越小，这里忽略不计。只是打开缓存，成本就降了约 30%；剩下的大头是输出，这也说明了控制输出长度的重要性。 以上是官方价。在 TokenJoy 实际扣多少，把结果乘以模型页标出的价格倍率即可；一次真实请求从 token 到扣费的完整算法，见[一次请求扣多少钱](https://tokenjoy.org/blog/credits)。 ## 省钱的几个方法 - **用好 prompt caching**：把不变的内容（系统提示词、文档、工具定义）放在前面，变化的内容放在后面，让前缀能被缓存命中。Claude Code 会自动使用缓存，所以长时间写代码的实际花费比看上去少得多。 - **按任务选模型**：分类、提取、改写这类简单任务用 Haiku，复杂推理和写代码再用 Sonnet 或 Opus。同一个应用里可以按请求类型分别调用。 - **控制输出长度**：设置合适的 `max_tokens`，在提示词里写明需要的格式和篇幅。 - **裁剪历史对话**：多轮对话只保留必要的上下文，或者定期把早先的对话总结成一小段。 - **先估算再上线**：用计算 Token 数接口量一量真实的提示词，再按上面的公式乘一乘。 ## 上线后怎么核对 在 TokenJoy 控制台，「概览」的请求记录里能看到每一次请求的输入、输出 token 和花费，用量页按天、按 Key、按模型汇总。按项目分开创建 Key，就能分别看到每个项目花了多少钱。 想开始试试，可以先看 [Claude API 中转](https://tokenjoy.org/claude-api) 的接入说明，或者直接从[首次调用 API](https://tokenjoy.org/docs/first-call.md) 开始。 --- # 更高的可用性：海外专用线路，不重试、不丢包、不封号 > 网页版：https://tokenjoy.org/docs/news/high-availability 2026-10-26 在国内直接调用海外的大模型，最让人头疼的往往不是价格，而是**不稳定**： - 跨境线路丢包，请求超时，只能靠客户端一遍遍重试； - 账号因为地区或网络环境被风控，说封就封； - 同样的模型，有时回答质量明显变差； - 本地网络连不上官方接口，还得额外维护一套代理。 TokenJoy 把这些都挡在后面。 ## 海外专用线路：不丢包，不用重试 普通的跨境线路要和大量流量挤在同一条公网骨干上，晚高峰时丢包明显，长一点的流式输出很容易中途断开，只能整段重来。 我们访问 Anthropic、OpenAI、Google 走的是**海外专用线路**： - 链路稳定，**不丢包**，请求一次就能到达官方接口； - **不用重试**，长对话、长输出不会中途断流； - 网关每分钟用真实请求探测一次线路，发现异常自动切换，探测结果在[服务状态](https://tokenjoy.org/status)页公开可查。 ## 不会封号 你不需要自己注册、维护海外账号，也就不会因为地区、支付方式或网络环境被风控封号。 账号的管理和风控由我们负责；后台采用多账号负载均衡，即使某个账号出了问题，请求也会转到其他账号上，你手里的 Key 照常可用。 ## 不降智 请求经由我们稳定的线路直达官方接口，调用的就是你指定的官方模型，不会因为你本地的网络环境而被区别对待。 ## 不需要 VPN 本站的 API 地址 `https://api.tokenjoy.org` 在国内可以直接访问。Claude Code、Codex、各种 SDK 改一下 Base URL 就能用，不用再开代理、配分流规则。 ## 可用性，由我们来保障 线路、账号、风控这些不稳定因素，都被网关挡在了后面。留给你的，是一个随时可用的地址和一把随时可用的 Key。 --- # 多家模型提供商，一个 API > 网页版：https://tokenjoy.org/docs/news/multi-provider 2026-10-26 想同时用 Claude、GPT 和 Gemini，通常意味着：注册三个平台、绑三张卡、管三套 Key、看三份账单，还要在代码里写三套接入方式。 TokenJoy 把它们收拢成**一个 API**。 ## 一个地址，一把 Key 所有模型共用同一个 Base URL： ``` https://api.tokenjoy.org ``` 和同一把 Key。目前接入的模型提供商有 Anthropic、OpenAI、Google，DeepSeek 也即将上线。 ## 兼容官方 SDK，代码不用改 接口格式和官方一致： - 用 **Anthropic SDK** 调 Claude，用 **OpenAI SDK** 调 GPT，写法和官方文档一样； - Claude Code、Codex 等工具，把 Base URL 改成 TokenJoy 就能用； - 已有的项目只需要换掉 Base URL 和 Key，业务代码一行不动。 ## 换模型，只改模型名 不同提供商的模型都在同一个入口后面。想从 Claude 换到 GPT，或者对比几家模型的效果，改一下请求里的模型名就行，客户端配置和 Key 都不用动。 新的提供商接入后（比如即将上线的 DeepSeek），你手里的 Key 直接就能调用，不用重新申请。 ## 账单和用量，都在一处 - 所有模型统一从美元余额扣费，一次充值，所有模型通用； - 控制台按天、按模型列出每个模型的请求数、token 数和花费； - 不用再在几个平台之间来回对账。 ## 一个 API 背后 一个入口的背后，是我们替你对接了每一家提供商：各自的接口差异、账号、线路和风控，都由网关处理。你面对的始终只有一个地址、一把 Key。 --- # 更好的性能：更高的并发，更低的延迟 > 网页版：https://tokenjoy.org/docs/news/performance 2026-10-26 性能看两件事：**同时能跑多少请求**，以及**每个请求多快回来**。TokenJoy 在这两点上都比直接用单个官方账号更好。 ## 更高的并发 ### 并发限速是按账号算的 以 DeepSeek 为例，它在文档里公开了并发规则： | | deepseek-flash | deepseek-v4-pro | | --- | --- | --- | | 每个账号的并发上限 | 2500 | 500 | - 一个请求从发出到模型响应完成，算作一个并发； - **并发上限按账号计算，与 API Key 无关**——同一个账号多建几把 Key，上限也不会变多； - 超过上限的请求会收到 HTTP 429。 一个账号的上限是固定的，想要更高的并发，办法只有一个：更多的账号。 ### 多账号负载均衡：并发按账号叠加 每家模型提供商背后，我们都准备了多个账号，请求由网关分摊到不同账号上。能承受的并发是： ``` 单个账号的并发上限 × 账号数量 ``` 举个例子，如果有 10 个账号，`deepseek-v4-pro` 能同时处理的请求就是 500 × 10 = 5000 个，是单个账号的 10 倍。 ### 没有 5 小时限额 官方的部分套餐会按 5 小时的滚动窗口计算用量，用满了就得等窗口重置。这个限制是官方用来**均衡整体负载**的：把每个账号的用量切成小段，峰值就被摊平了。 多账号负载均衡天然起到了同样的作用：负载分摊在所有账号上，某个账号的窗口快满时，后面的请求交给其他账号。所以你不会撞上 5 小时限额，按实际用量扣积分就行。 ## 更低的延迟 ### 访问海外：高速专线 Anthropic、OpenAI、Google 的服务器在海外。我们访问它们走的是 **CN2 高速链路**：路由更短、拥塞更少，晚高峰的延迟也不会明显上升。对你来说，就是首字更快出来，流式输出不卡顿。 ### 访问国内：模型在哪，我们就在哪 像 DeepSeek 这样的国内提供商，请求不需要出境绕一圈。我们在**模型提供商所在地的国内机器**上接入，请求就近到达，路径最短。 ### 自动的网络拓扑 用哪条线路、走哪台机器，不需要你操心。网关维护着一张自动的网络拓扑：按目标提供商自动选择线路，海外走高速专线，国内走就近的机器。 ## 对你意味着什么 - 同时开多个 Claude Code、Codex 或 Agent，不用担心互相抢额度； - 批量跑评测、批量处理数据时，可以把并发开高，整体更快跑完； - 不管调用海外还是国内的模型，请求都走最短、最快的路径。 ## 仍然存在的边界 - 账号的总容量是有限的，极端的瞬时洪峰仍可能收到 429，稍等重试即可； - 余额用完时 Key 会自动暂停，兑换卡密充值后自动恢复。 --- # 透明计费：透明标价，透明使用 > 网页版：https://tokenjoy.org/docs/news/transparent-pricing 2026-10-26 用 API 最怕的不是贵，而是**算不清**：单价藏在角落里，倍率说不明白，月底余额少了一截，却不知道花在了哪里。 TokenJoy 的计费只做两件事：**价格摆在明处，用量记在明处。** ## 透明标价：每个模型的价格都公开 打开[模型页](https://tokenjoy.org/models)，每个模型的卡片上都写着两组价格： - **官方价**：每百万输入 token、每百万输出 token 多少美元，和厂商官网公布的一致； - **实付价**：在官方价基础上乘以本站的价格倍率，就是你实际要付的钱。 倍率公开写在模型页和[套餐页](https://tokenjoy.org/pricing)上，没有藏在条款里的附加费。计价方式只有一种： ``` 扣费 = 实际 token 数 × 官方单价 × 价格倍率 ``` 除此之外： - **1 元人民币买 1 美元额度**，余额以美元计，对所有模型通用； - **失败的请求不扣费**； - **没有月费，也没有最低消费**，用多少扣多少。 ## 透明使用：每一次请求都查得到 钱花在哪里，控制台里一条一条都能看到： - **概览 → 请求记录**：近 30 天的每一次请求，时间、模型、成功与否、用时、输入和输出 token、这次花了多少钱，都列在一行里。点开自己的请求还能看到完整的请求轨迹。开启隐私模式后，网关不保存请求内容，这里只显示请求是否成功。 - **用量**：按天、按 Key、按模型汇总请求数、输入 token、输出 token、缓存读写和花费，适合看一段时间的总账。 - **兑换 → 流水**：每一次余额变动，充值、赠送、扣费，连同变动后的余额，都有记录。 单次请求的花费、某天的总账、余额的每一次进出，三个地方的数字能对得上。 ## 自己算一遍 想知道一次请求到底扣了多少，可以看[一次请求扣多少钱](https://tokenjoy.org/blog/credits)：拿一次真实的 Haiku 请求，从 token 数一路算到扣费金额，你也可以照着用控制台里的数字自己核对。 价格公开，用量可查，每一分钱都算得明白。这就是我们说的透明计费。 --- # 一次请求扣多少钱 > 网页版：https://tokenjoy.org/docs/news/credits 2026-10-24 用一次真实请求说明。下面是调用 `claude-haiku-4-5` 说一句「Say hi in 3 words」的用量： - 输入 30 个 token - 输出 8 个 token Haiku 的官方价是每百万输入 token 1 美元、每百万输出 token 5 美元，所以这次请求的上游成本是： ``` 30 × 1 / 1,000,000 + 8 × 5 / 1,000,000 = $0.00007 ``` TokenJoy 的余额以美元计，按官方价乘以价格倍率扣费（当前倍率以套餐页公布的为准）。以倍率 0.8（八折）为例，这次请求扣： ``` $0.00007 × 0.8 = $0.000056 ``` 控制台可以切换成人民币显示，按站点公布的汇率折算，仅供参考；实际扣的始终是美元余额。 ## 缓存怎么算 开了 prompt caching 之后，命中缓存的输入按缓存读取价计费，通常只有原价的十分之一；写入缓存按缓存写入价计费。Claude Code 会自动使用缓存，所以长对话实际花的钱比看上去少得多。 ## 去哪里核对 控制台「概览」页按模型、按 Key 列出请求数、各类 token 数和花费；余额卡上的「流水」列出每一次扣费，大约 30 秒结算一次。 --- # Claude Code 接入 TokenJoy 的三种写法 > 网页版：https://tokenjoy.org/docs/news/claude-code 2026-10-22 Claude Code 只认两个变量：`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN`。把它们放在哪里，决定了它们对谁生效。 ## 写进 shell 配置 最省事，对这台电脑上所有终端生效： ``` export ANTHROPIC_BASE_URL="https://api.tokenjoy.org" export ANTHROPIC_AUTH_TOKEN="<你的 API Key>" ``` 缺点是别的读这两个变量的工具也会跟着走 TokenJoy。 ## 写进 ~/.claude/settings.json 只对 Claude Code 生效，不影响别的程序： ``` { "env": { "ANTHROPIC_BASE_URL": "https://api.tokenjoy.org", "ANTHROPIC_AUTH_TOKEN": "<你的 API Key>" } } ``` ## 只对一个项目生效 在项目目录下建 `.claude/settings.local.json`，内容同上。这个文件默认不会进 git，适合公司项目用公司的 Key、个人项目用个人的 Key。 > 每台电脑、每个用途建一把单独的 Key。哪把 Key 花了多少，控制台里一目了然，泄露了也只需要重置那一把。 配好之后运行 `claude`，输入 `/status` 确认 Base URL 已经是 `https://api.tokenjoy.org`。 --- # TokenJoy 上线了 > 网页版：https://tokenjoy.org/docs/news/hello 2026-10-20 TokenJoy 开放注册了。 它做的事情很简单：你拿到一把 Key，把客户端的 Base URL 改成 `https://api.tokenjoy.org`，就能用官方的 Anthropic SDK、OpenAI SDK、Claude Code、Codex 去调 Claude 和 GPT。接口格式和官方一样，代码不用改。 ## 请求怎么走 你的请求直接到我们的网关，网关验 Key、按你的余额检查额度、挑一条健康的上游线路，然后把请求发出去。网站本身不经手你的请求内容，它只做两件事：给你发 Key，以及按网关记下的用量从余额里扣费。 ## 钱怎么算 余额以美元（USD $）计。每个模型按官方美元价乘以价格倍率扣费，输入、输出、缓存读写分别计价。失败的请求不扣钱。每一笔扣费都能在控制台的「余额」页看到来源；也可以切换成人民币显示。 ## 余额用完会怎样 每把 Key 的可用额度会自动跟着账户余额走。余额用完时 Key 会自动暂停；兑换卡密充值后自动恢复，客户端不用重新配置。 --- # 更新日志 > 网页版：https://tokenjoy.org/docs/updates 2026-10-31 ## 新增 GPT 实时语音 - 支持 gpt-realtime 和 gpt-realtime-mini 实时语音模型：通过 WebSocket 发送语音、实时收到语音回答和文字稿，接口与 OpenAI Realtime API 兼容。 - 文档新增「API 指南 · 实时语音」和「API 文档 · 实时语音」，提供 Python、Node.js、OpenAI SDK 示例和网页接入的转发示例。 2026-10-31 ## 支持一键导入 CC Switch - 创建 Key 后的一键配置新增 CC Switch：点一下即可把本站导入 CC Switch 中的 Claude Code、Codex、OpenCode、OpenClaw、Hermes 或 Pi。 - 文档新增 CC Switch 使用教程，包括安装、一键导入、手动添加和切换方法。 2026-10-27 ## 余额改为美元计价 - 余额、套餐和扣费改为以美元（USD $）计，不再使用积分。 - 控制台和套餐页可以切换为人民币（CNY ¥）显示，按站点公布的汇率折算。 2026-10-27 ## 文档改版，API 使用独立域名 - 文档分为快速开始、API 指南、API 文档、新闻和更新日志，新增 Agent 工具接入指南：Claude Code、Codex、Hermes、DeepSeek Harness、OpenCode、OpenClaw 等。 - 「首次调用 API」提供 OpenAI 和 Anthropic 两种格式的 curl、Python、Node.js 样例。 - API 与网站分开为两个域名，API 地址以控制台和文档中显示的为准。 2026-10-26 ## Claude Code 一键配置、博客上线 - 创建 Key 后可以复制一行命令，自动写好 Claude Code 的配置，支持 macOS、Linux 和 Windows。 - 新首页实时展示可用模型和用量趋势；上线博客。 2026-10-25 ## 卡密兑换与服务状态 - 支持用卡密兑换积分，以及按周期自动发放积分的套餐。 - 服务状态页展示官方状态和 90 天可用率。 - 忘记密码可以通过邮件验证码重置。 2026-10-24 ## TokenJoy 上线 - 兼容 OpenAI 和 Anthropic 接口，一个 Key 调用多家模型。 - 按实际 token 用量扣积分，控制台可以查看每把 Key 的用量。