# 1折AI · 完整文档 # Claude 与 GPT API 接入文档 Source: https://1zheai.com/docs/ Markdown: https://1zheai.com/docs/index.md --- title: Claude 与 GPT API 接入文档 description: 用 1折AI 的 API 密钥调用 Claude 与 GPT：接口地址、各工具的接入方法、计费规则和排错。 --- 1折AI 提供 Claude 和 OpenAI / GPT API，支持 Anthropic Messages、OpenAI Responses 和 Chat Completions。常用接口包括：Anthropic 原生的 `/v1/messages`，以及 OpenAI 兼容的 `/v1/chat/completions`。你手上的代码和工具，一般只要改两处：Base URL 和 API 密钥（API key）。 ```text Anthropic Base URL https://1zheai.com OpenAI Base URL https://1zheai.com/v1 API Key sk-...（在控制台创建） ``` 价格是官方美元标价乘一个折扣（当前折扣见[价格页](https://1zheai.com/pricing/)），缓存读写也按同一个折扣算。 Claude 与 OpenAI / GPT 文本模型已上线，完整列表见[支持的模型](/docs/models/)。 ## 你想做什么 Claude Code、Codex CLI、Cursor、Cline、Cherry Studio 和 CC Switch。先看支持范围，再按步骤配置。 从 Anthropic SDK、OpenAI SDK 或 curl 开始，继续了解流式输出。 机器可读文档、页面清单和可复制的 AI 接入任务说明。 注册、创建 API 密钥，完成第一条请求。 ## 查阅与支持 查找端点、协议、示例和兼容范围。 查看费用、调用记录与排错路径。 ## 用之前最常问的 检查返回字段和用量；这些检查不能单独证明模型来源。 缓存怎么开、怎么看命中、命中后便宜多少。 401、404、429、5xx 分别是什么情况。 支付方式、7 天退款、发票规则。 --- # 快速开始 Source: https://1zheai.com/docs/quickstart/ Markdown: https://1zheai.com/docs/quickstart.md --- title: 快速开始 description: 注册 1折AI、创建 API 密钥、用一条 curl 调通 Claude，再接到 Claude Code 等工具里。 --- 目标：5 分钟内拿到一个 API 密钥（API key），并亲眼看到 Claude 的回包。 打开 [1zheai.com/register](https://1zheai.com/register) 注册。调用是按量扣余额的，所以要先充值，最低 ¥100，支持微信、支付宝、Stripe（银行卡）和 USDT。7 天内没用完的额度可以原路退回，规则见[充值、退款与发票](/docs/billing/)。 进入[控制台](https://1zheai.com/console)，左侧菜单点「API 密钥」，再点右上角「创建 API 密钥」，填个名字后保存。API 密钥以 `sk-` 开头，在列表里点复制图标复制下来存好。细节见[获取与管理 API 密钥](/docs/api-keys/)。 把 API 密钥放进环境变量，再用 curl 调一次 Anthropic 原生接口： ```bash title="macOS / Linux" export ONEZHE_API_KEY="sk-你的Key" curl https://1zheai.com/v1/messages \ -H "x-api-key: $ONEZHE_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5-5", "max_tokens": 128, "messages": [{"role": "user", "content": "用一句话解释什么是 HTTP"}] }' ``` ```powershell title="Windows PowerShell" $env:ONEZHE_API_KEY = "sk-你的Key" $body = @{ model = "claude-sonnet-5-5" max_tokens = 128 messages = @(@{ role = "user"; content = "用一句话解释什么是 HTTP" }) } | ConvertTo-Json -Depth 5 Invoke-RestMethod -Uri "https://1zheai.com/v1/messages" -Method Post ` -Headers @{ "x-api-key" = $env:ONEZHE_API_KEY; "anthropic-version" = "2023-06-01" } ` -ContentType "application/json; charset=utf-8" ` -Body ([System.Text.Encoding]::UTF8.GetBytes($body)) ``` `ONEZHE_API_KEY` 只是示例变量名，用什么名字都行。 成功时返回 HTTP 200，结构和官方一致。重点看两处：`model` 是不是你请求的模型，`usage` 里的 token 数。下面是 2026-10-15 实测的回包： ```json { "model": "claude-sonnet-5-5", "id": "msg_011Cg3G8HQmyTrnqSBX6o6Pw", "type": "message", "role": "assistant", "content": [ { "type": "text", "text": "HTTP(超文本传输协议)是一种基于请求-响应模式的应用层协议,用于在客户端(如浏览器)和服务器之间传输网页、图片、API 数据等内容。" } ], "container": null, "stop_reason": "end_turn", "stop_sequence": null, "stop_details": null, "usage": { "input_tokens": 530, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "cache_creation": { "ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0 }, "output_tokens": 69, "output_tokens_details": {"thinking_tokens": 0}, "service_tier": "standard", "inference_geo": "global" }, "input_transformations": [], "diagnostics": null, "context_management": {"applied_edits": []} } ``` `input_tokens` 比这句提问本身多出几百，是这类客户端（curl、SDK、第三方工具）每次请求附带的系统提示，按输入计费，Claude Code 不附带，见[系统提示的计费](/docs/pricing-explained/#系统提示的计费)。 再去控制台左侧的「使用日志」，能看到刚才这一笔：时间、所用 API 密钥（「令牌」列）、模型、输入 / 输出 token、缓存读写和费用。 ## 下一步 接到你常用的工具里： 两个环境变量就够。 不想手改配置文件就用它。 自定义 Base URL 的写法和限制。 已有 OpenAI 代码，只改 base_url。 请求失败的话，先看[错误码与排错](/docs/troubleshooting/)。想核对返回的字段和用量，看[核对模型和用量](/docs/verify-model/)。 --- # 获取与管理 API 密钥 Source: https://1zheai.com/docs/api-keys/ Markdown: https://1zheai.com/docs/api-keys.md --- title: 获取与管理 API 密钥 description: 在 1折AI 控制台创建 sk- 开头的 API 密钥，以及怎么存放、轮换、在泄露时止损。 --- 一个 API 密钥（API key）对应一份调用权限，扣的是你账户的余额。这页讲怎么建、怎么放、出事了怎么办。 ## 创建 API 密钥 打开 [1zheai.com/console](https://1zheai.com/console)。 左侧菜单点「API 密钥」，再点右上角「创建 API 密钥」。名称填一个能看出用途的名字，比如 `claude-code-macbook`、`ci-staging`，其它项不改也能用，点「保存更改」。 表单里可以设置的项： | 表单项 | 默认 | 说明 | |---|---|---| | 名称 | 空 | 调用日志里按这个名字区分 API 密钥 | | 过期时间 | 永不过期 | 可选 1 小时、1 天、1 个月，或指定具体日期和时间 | | 数量 | 1 | 一次建多个，名称会自动加随机后缀 | | 「无限配额」开关 | 打开 | 关掉后出现「额度 (USD)」，这个 API 密钥最多只能花这么多美元 | | 模型限制（在「高级设置」里） | 空，表示所有模型都能用 | 选了模型后，这个 API 密钥只能调这些模型 | | IP 白名单（在「高级设置」里） | 空，表示不限 | 只允许列出的 IP 或 CIDR 网段调用 | API 密钥以 `sk-` 开头。复制后放进密码管理器或环境变量，不要贴进聊天、截图或代码仓库。 ## 一个工具一个 API 密钥 建议每个工具、每台机器各建一个 API 密钥。好处有三个： - 调用日志按 API 密钥区分，哪个工具花了多少钱一眼能看出来。 - 某个 API 密钥泄露了，只删那一个，其它工具不受影响。 - 团队里谁的 API 密钥谁负责，离职或换机器时删除对应的 API 密钥。 ## 放在哪里 ```bash title="Shell 配置（macOS / Linux）" # 写进 ~/.zshrc 或 ~/.bashrc，只在本机生效 export ONEZHE_API_KEY="sk-你的Key" ``` ```powershell title="Windows（当前用户，持久）" [Environment]::SetEnvironmentVariable("ONEZHE_API_KEY", "sk-你的Key", "User") # 重新打开终端后生效 ``` ```bash title=".env（项目本地）" # .env 要写进 .gitignore ONEZHE_API_KEY=sk-你的Key ``` Claude Code 的项目级 `.claude/settings.json` 通常会提交进仓库，Claude Code 官方文档也明确建议不要把凭据写在这里。API 密钥放用户级的 `~/.claude/settings.json`，或者项目里不提交的 `.claude/settings.local.json`。 ## 泄露了怎么办 1. 在「API 密钥」列表里找到它，点「操作」列的「禁用」图标，或者在「⋯」菜单里选「删除」。禁用后立刻失效，再用它调用会返回 401 `Invalid token`。 2. 新建一个 API 密钥，换到用到它的地方。 3. 打开调用日志（控制台菜单「使用日志」），点「展开」，在「令牌名称」里填这个 API 密钥的名字筛选，看最近的调用里有没有不是你发起的。 ## 常见问题 能，API 密钥不绑定工具。只是混用以后日志里分不清是谁花的，所以还是建议分开建。 多数是。常见原因：复制时带了空格或换行、API 密钥已删除、填进了工具里错误的字段。逐项排查见[错误码与排错](/docs/troubleshooting/)。 默认永不过期。创建或编辑时可以在「过期时间」里设一个时间，过期后再调用返回 401 `Invalid token`，和 API 密钥写错时的回包一样。列表的「过期」列显示每个 API 密钥的过期时间。 --- # 支持的模型 Source: https://1zheai.com/docs/models/ Markdown: https://1zheai.com/docs/models.md --- title: 支持的模型 description: 1折AI 的 Claude 与 OpenAI / GPT 文本模型，以及通过 API 查询最新可用模型的方法。 --- Claude 与 OpenAI / GPT 文本模型已上线。下方列出模型 ID，最新可用范围以接口返回为准。 查看[公开模型与价格](https://1zheai.com/pricing/)了解报价；已登录用户可前往[控制台 · 模型](https://1zheai.com/model-catalog)查询模型并查看接入方式。 ## 模型列表 请求里的 `model` 必须和下表的 ID 完全一致，包括日期后缀。 | 模型 ID | 系列 | 说明 | |---|---|---| | `claude-fable-5-1` | Fable 5.1 | | | `claude-fable-5` | Fable 5 | | | `claude-opus-5-5` | Opus 5.5 | | | `claude-opus-5` | Opus 5 | | | `claude-opus-4-8` | Opus 4.8 | | | `claude-opus-4-7` | Opus 4.7 | | | `claude-opus-4-6` | Opus 4.6 | | | `claude-opus-4-5-20251101` | Opus 4.5 | 带日期的固定版本 ID | | `claude-sonnet-5-5` | Sonnet 5.5 | | | `claude-sonnet-5` | Sonnet 5 | | | `claude-sonnet-4-6` | Sonnet 4.6 | | | `claude-sonnet-4-5-20250929` | Sonnet 4.5 | 带日期的固定版本 ID | | `claude-haiku-5-5` | Haiku 5.5 | | | `claude-haiku-4-5-20251001` | Haiku 4.5 | 带日期的固定版本 ID | 每个模型的单价（输入、输出、缓存读、缓存写）见[价格页](https://1zheai.com/pricing/)。模型的能力、上下文长度和发布说明以 [Anthropic 官方模型文档](https://platform.claude.com/docs/en/about-claude/models/overview) 为准。 ## 两种接口都能调 上表的模型都可以通过 Anthropic 原生 `/v1/messages` 和 OpenAI 兼容 `/v1/chat/completions` 调用，模型 ID 写法相同。需要缓存、thinking、工具调用等 Claude 特有参数时，用原生接口，见 [Base URL 与鉴权](/docs/base-url/)。 ## OpenAI / GPT 模型 - `gpt-5.6-luna` - `gpt-5.6-sol` - `gpt-5.6-terra` - `gpt-6-astra` GPT 可用于 [OpenAI SDK](/docs/quickstart-openai-sdk/) 和 [Codex CLI](/docs/quickstart-codex/)。不同模型的接口和计费方式以[控制台模型目录](https://1zheai.com/model-catalog)为准。 ## 用接口查最新列表 模型会随官方发布增减，以接口返回为准： ```bash title="用你的 Key 查" curl https://1zheai.com/v1/models \ -H "Authorization: Bearer sk-你的Key" ``` ```bash title="公开价格接口（不需要 Key）" curl -s https://1zheai.com/api/pricing | jq -r '.data[].model_name' ``` ## 怎么选 不知道选哪个时，可以这样起步： | 场景 | 建议 | |---|---| | 日常写代码、Claude Code 主力 | `claude-sonnet-5-5` | | 复杂重构、难排查的问题 | `claude-opus-5-5` | | 子任务、摘要、分类等轻活 | `claude-haiku-5-5` | 在 Claude Code 里怎么把 opus / sonnet / haiku 三档映射到具体模型，见 [Claude Code 接入](/docs/quickstart-claude-code/)。 ## 常见问题 先核对 ID 拼写和日期后缀，再用上面的 `/v1/models` 确认你的 API 密钥（API key）能看到这个模型。其他服务商的自定义模型名（比如加了前缀、后缀的）在这里用不了。 模型不存在或当前不可用时，网关返回 HTTP 404。Anthropic 原生响应的 `error.type` 为 `not_found_error`；OpenAI 兼容响应的 `error.code` 为 `model_not_found`。 先核对 ID 和密钥可用模型列表，不要反复重试同一个错误 ID。模型存在但暂时没有健康的上游服务时才可能返回 503，见[错误码与排错](/docs/troubleshooting/)。 正常情况下回包 `model` 就是你请求的 ID。如果对不上，把请求时间和回包发到 support@1zheai.com，也可以照[核对模型和用量](/docs/verify-model/)做一遍检查。 --- # Claude 与 GPT 工具接入教程 Source: https://1zheai.com/docs/integrations/ Markdown: https://1zheai.com/docs/integrations.md --- title: Claude 与 GPT 工具接入教程 description: Claude Code、Codex CLI、OpenCode、OpenClaw、WorkBuddy、Hermes Agent、Cursor、Cline、Cherry Studio 和 CC Switch 的 API 配置教程与支持范围。 --- 按你正在使用的工具进入教程。下面的状态整理自现有接入文档，不代表所有工具版本均已通过端到端验证。工具升级后，请重新完成页面中的调用验证。 ## 编程工具 Anthropic 原生接入。环境变量、配置文件和常见问题。 通过 Responses 接口调用 OpenAI / GPT 模型。 区分 v1 与 v2 配置，自定义 OpenAI 兼容供应商。 OpenAI 兼容接入。先查看自定义密钥的适用范围与界面差异。 优先使用 Anthropic 模式，也提供 OpenAI Compatible 配置。 ## 桌面助手 在聊天客户端中添加自定义供应商。 通过模型设置添加自定义地址，注意完整 URL 与协议开关。 ## Agent 平台 配置自定义 Anthropic 提供商与默认 Agent 模型。 通过模型向导或命名 provider 配置 Chat Completions。 OpenCode、OpenClaw、WorkBuddy 和 Hermes Agent 教程已核对官方配置，本站端到端验证尚未完成。请按教程核对实际版本并验证调用。 ## 配置管理 管理 Claude Code 的供应商配置，减少手工切换。 ## 其他支持自定义 API 的工具 先检查工具是否能设置 API 地址、密钥和模型 ID，再根据协议选择配置： | 工具支持的协议 | 本站接口 | 下一步 | | --- | --- | --- | | Anthropic Messages | `/v1/messages` | 核对客户端是否自动追加 `/v1`，参考[地址说明](/docs/base-url/) | | OpenAI Chat Completions | `/v1/chat/completions` | 通常 Base URL 填 `https://1zheai.com/v1`；完整端点字段除外 | | OpenAI Responses | `/v1/responses` | Base URL 填 `https://1zheai.com/v1`，参考 [Codex CLI](/docs/quickstart-codex/) | | 仅支持官方账号登录 | 不使用本站 API 密钥 | 核对工具是否另有自定义供应商设置 | ## 怎么确认配置成功 1. 按教程选择协议和 Base URL；各工具是否需要 `/v1`，见[地址对照表](/docs/base-url/)。 2. 从[支持的模型](/docs/models/)中选择当前可用模型。 3. 发起一次简短请求，检查工具是否正常返回。 4. 在[调用日志](/docs/usage-logs/)中核对对应调用；不要只凭回复内容判断请求经过了哪个供应商。 遇到问题先看[错误码与排错](/docs/troubleshooting/)。自己写程序时进入[开发指南](/docs/guides/)。 --- # Claude Code 接入 Source: https://1zheai.com/docs/quickstart-claude-code/ Markdown: https://1zheai.com/docs/quickstart-claude-code.md --- title: Claude Code 接入 description: 把 Claude Code 接到 1折AI：用 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN（环境变量或 settings.json），附 Windows 写法、模型映射、VS Code 插件和常见报错。 --- Claude Code 只需要两个变量：`ANTHROPIC_BASE_URL` 指向我们，`ANTHROPIC_AUTH_TOKEN` 填你的 API 密钥（API key）。不需要登录 Anthropic 账号。 ## 最短路径 已经装好 Claude Code、手里有 API 密钥的话，把下面两行写进 `~/.claude/settings.json`，然后运行 `claude`： ```json title="~/.claude/settings.json" { "env": { "ANTHROPIC_BASE_URL": "https://1zheai.com", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key" } } ``` 文件已经存在的话，把这两项合并进已有的 `env`，不要覆盖其它配置。 ## 完整步骤 已经装过可以跳过。以下命令来自 [Claude Code 官方安装文档](https://code.claude.com/docs/en/setup)： ```bash title="macOS / Linux" curl -fsSL https://claude.ai/install.sh | bash ``` ```powershell title="Windows PowerShell" irm https://claude.ai/install.ps1 | iex ``` ```bash title="Homebrew" brew install --cask claude-code ``` ```bash title="npm（需要 Node.js 22+）" npm install -g @anthropic-ai/claude-code ``` 用 npm 装时不要加 `sudo`。 在[控制台](https://1zheai.com/console)新建一个 API 密钥，建议专门给这台机器的 Claude Code 用。见[获取与管理 API 密钥](/docs/api-keys/)。 settings.json 的位置：macOS / Linux 是 `~/.claude/settings.json`，Windows 是 `%USERPROFILE%\.claude\settings.json`。 ```json title="settings.json（推荐）" { "env": { "ANTHROPIC_BASE_URL": "https://1zheai.com", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key" } } ``` ```bash title="macOS / Linux 环境变量" # 写进 ~/.zshrc 或 ~/.bashrc，然后重开终端 export ANTHROPIC_BASE_URL="https://1zheai.com" export ANTHROPIC_AUTH_TOKEN="sk-你的Key" ``` ```powershell title="Windows PowerShell" # 持久写入当前用户，重开终端后生效 [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://1zheai.com", "User") [Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-你的Key", "User") # 只在当前窗口生效 $env:ANTHROPIC_BASE_URL = "https://1zheai.com" $env:ANTHROPIC_AUTH_TOKEN = "sk-你的Key" ``` ```bat title="Windows CMD" setx ANTHROPIC_BASE_URL "https://1zheai.com" setx ANTHROPIC_AUTH_TOKEN "sk-你的Key" ``` `ANTHROPIC_BASE_URL` 填根地址，不要加 `/v1`，Claude Code 会自己拼 `/v1/messages`。 在项目目录运行 `claude`，进去后输入 `/status`。看两行： - base URL 一行显示 `https://1zheai.com` - 凭据一行显示来源是 `ANTHROPIC_AUTH_TOKEN` 然后问一句话，再去[调用日志](/docs/usage-logs/)看有没有新的记录。有，就接通了。 不想进交互界面的话，也可以用非交互模式试一次（2026-10-15 实测返回 `ok`）： ```bash claude -p "say ok" --model claude-sonnet-4-6 ``` ## 为什么用 ANTHROPIC_AUTH_TOKEN Claude Code 有两个变量都能放 API 密钥，区别如下（[官方说明](https://code.claude.com/docs/en/authentication)）： | 变量 | 发送方式 | 行为 | |---|---|---| | `ANTHROPIC_AUTH_TOKEN` | `Authorization: Bearer <值>` | 设置后立即生效，不弹确认 | | `ANTHROPIC_API_KEY` | `x-api-key: <值>` | 交互模式下首次会弹窗问你是否使用这个 API 密钥 | 两种我们都支持，推荐 `ANTHROPIC_AUTH_TOKEN`。**两个只设一个**：如果系统里还留着以前官方的 `ANTHROPIC_API_KEY`，删掉它，免得混用出 401。 另外两条容易踩的规则： - `settings.json` 的 `env` 和终端 export 设了同一个变量时，**以 settings.json 为准**。改了终端变量没生效，先看 settings.json。 - 不要把 API 密钥写进项目的 `.claude/settings.json`，这个文件通常会提交进仓库。要按项目区分，用不提交的 `.claude/settings.local.json`。 ## 模型映射 Claude Code 里的 `opus`、`sonnet`、`haiku`、`fable` 是别名，可以用环境变量指定它们对应的具体模型。Haiku 那一档还会被 Claude Code 用来跑一些后台小任务。 | 变量 | 作用 | 示例值 | |---|---|---| | `ANTHROPIC_MODEL` | 启动时使用的模型 | `claude-sonnet-5-5` | | `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 别名指向 | `claude-opus-5-5` | | `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 别名指向 | `claude-sonnet-5-5` | | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 别名和后台任务用的模型 | `claude-haiku-5-5` | | `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 别名指向 | `claude-fable-5-1` | ```json title="~/.claude/settings.json（带模型映射）" { "env": { "ANTHROPIC_BASE_URL": "https://1zheai.com", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key", "ANTHROPIC_MODEL": "claude-sonnet-5-5", "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5", "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5", "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5" } } ``` 模型 ID 必须是[支持的模型](/docs/models/)里的。运行中也可以用 `/model claude-opus-5-5` 临时切换。 ## VS Code 插件 Claude Code 的 VS Code 插件在启动前会检查凭据，官方建议把变量写在 VS Code 自己的用户设置里（命令面板 → Preferences: Open User Settings (JSON)）： ```json title="VS Code settings.json" { "claudeCode.environmentVariables": [ { "name": "ANTHROPIC_BASE_URL", "value": "https://1zheai.com" }, { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-你的Key" } ] } ``` 只写在 `~/.claude/settings.json` 时，插件自己的登录检查可能读不到。 ## 可选设置 | 变量 | 作用 | |---|---| | `API_TIMEOUT_MS` | 请求超时，默认 600000（10 分钟），长任务容易超时可以调大 | | `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` | 关掉自动更新、遥测、错误上报等非必要流量。注意设成 `0` 或 `false` 也算开启，要关掉必须删除这个变量 | | `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` | 遇到 "Extra inputs are not permitted" 一类 400 时用 | | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` | 让 `/model` 列表从 `/v1/models` 拉取可用模型 | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` 已实测可用（Claude Code 2.1.296，2026-10-15）：启动后 debug 日志里出现 `[gatewayDiscovery] cached 14 models`，14 个模型和[支持的模型](/docs/models/)一致。 不要设置 `DISABLE_PROMPT_CACHING`，它会关掉缓存，账单会明显变高，见 [Prompt Caching](/docs/prompt-caching/)。 ## 常见问题 Claude Code 没读到 API 密钥。检查变量名拼写；用环境变量的话确认是在新开的终端里启动；用 settings.json 的话确认 JSON 格式正确（多一个逗号就会整体失效）。 API 密钥复制不完整，或者 `ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN` 同时存在且其中一个是旧值。两个只留一个。更多见[错误码与排错](/docs/troubleshooting/)。 `ANTHROPIC_BASE_URL` 多写了 `/v1`。改成 `https://1zheai.com`。 这是 Claude Code 用 Haiku 档跑后台小任务。想换成别的模型，设置 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。 删掉（或注释掉）上面两个变量就回到官方登录。经常切换的话用 [CC Switch](/docs/quickstart-cc-switch/)，点一下就换。 不会产生关联。接入 1折AI 时 Claude Code 用的是我们的 API 密钥，不登录你的 Anthropic 账号。 --- # Codex CLI 接入 Source: https://1zheai.com/docs/quickstart-codex/ Markdown: https://1zheai.com/docs/quickstart-codex.md --- title: Codex CLI 接入 description: OpenAI Codex CLI 接入 1折AI 的配置方法（~/.codex/config.toml 的 model_providers），通过 Responses 接口调用 GPT 模型。 --- OpenAI / GPT 模型已上线。Codex CLI 使用 OpenAI Responses 接口（`/v1/responses`），通过本站 API 密钥接入。可用模型与价格见[模型目录](https://1zheai.com/model-catalog)。 下面先把 Codex 自定义供应商的配置方式讲清楚，格式来自 [Codex 官方配置文档](https://developers.openai.com/codex/config-reference)。 ## 配置文件 Codex 的配置在 `~/.codex/config.toml`。自定义供应商只能写在这个用户级文件里，项目里的 `.codex/config.toml` 设置 `model_provider` 会被忽略。 ```toml title="~/.codex/config.toml" model_provider = "onezhe" model = "gpt-6-astra" [model_providers.onezhe] name = "1折AI" base_url = "https://1zheai.com/v1" env_key = "ONEZHE_API_KEY" wire_api = "responses" ``` 示例使用 `gpt-6-astra`，可替换为你的密钥支持的其他 GPT 模型 ID。 几个字段的意思： | 字段 | 说明 | |---|---| | `model_provider` | 使用哪个供应商，对应下面 `[model_providers.]` 的 id。`openai`、`ollama`、`lmstudio` 是保留名，不能用 | | `base_url` | 要带 `/v1` | | `env_key` | Codex 从这个环境变量里读 API 密钥（API key），名字要和你 export 的完全一致 | | `wire_api` | 官方文档写明目前只支持 `responses`，省略时也是它 | 然后把 API 密钥放进环境变量： ```bash title="macOS / Linux" export ONEZHE_API_KEY="sk-你的Key" ``` ```powershell title="Windows PowerShell" [Environment]::SetEnvironmentVariable("ONEZHE_API_KEY", "sk-你的Key", "User") ``` ## 安装 Codex 以下命令来自 Codex 官方文档： ```bash title="npm" npm install -g @openai/codex ``` ```bash title="Homebrew" brew install --cask codex ``` ```bash title="macOS / Linux 脚本" curl -fsSL https://chatgpt.com/codex/install.sh | sh ``` ```powershell title="Windows" powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" ``` ## 常见问题 `env_key` 写的变量名和你实际 export 的不一致，或者在设置环境变量之前就打开了终端。两边名字核对一遍，重开终端再试。 不能。Codex 官方配置文档里 `wire_api` 只接受 `responses`。只提供 Chat Completions 接口的服务需要额外的协议转换工具才能接 Codex。 在[模型目录](https://1zheai.com/model-catalog)查看当前模型，并把模型 ID 填入 `model`。启动 Codex 后发起简短请求，在[调用日志](/docs/usage-logs/)中核对模型和状态。 --- # OpenCode 接入 Claude API Source: https://1zheai.com/docs/quickstart-opencode/ Markdown: https://1zheai.com/docs/quickstart-opencode.md --- title: OpenCode 接入 Claude API description: OpenCode 配置 1折AI Claude API 中转的地址、密钥与模型教程，包含协议选择、配置示例、验证步骤和常见错误。 --- 使用 OpenCode 的自定义供应商功能连接 1折AI。先[创建 API 密钥](/docs/api-keys/)，并确认[当前可用模型](/docs/models/)；下文模型 ID 是示例，请按你的密钥权限调整。 官方配置核对日期：2026-10-15。以下配置依据官方文档整理，本站端到端验证尚未完成；请先完成简短问答和工具调用验证，再用于长任务。OpenAI / GPT 模型已上线，模型列表与价格见[模型说明](/docs/models/)。 ## OpenCode v1 配置 依据 [官方 v1 Providers](https://opencode.ai/docs/providers/)：运行 `/connect`，选择 Other，provider ID 输入 `onezhe`，填写本站 API Key。在项目 `opencode.json` 合并： ```json { "$schema": "https://opencode.ai/config.json", "provider": { "onezhe": { "npm": "@ai-sdk/openai-compatible", "name": "1折AI", "options": { "baseURL": "https://1zheai.com/v1" }, "models": { "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" } } } } } ``` 随后 `/models` 选择该 provider 的模型。`/connect` 只保存凭据，不代替 provider 配置。这里明确选择 Chat Completions 的 SDK；不能误换为用于 Responses 的 `@ai-sdk/openai`。官方也允许通过 `options.apiKey: "{env:ONEZHE_API_KEY}"` 引用环境变量。 ## OpenCode v2 配置 依据 [官方 v2 Providers](https://opencode.ai/v2/docs/providers)，使用原生 v2 字段，不能与上方 v1 混写。在项目 `opencode.jsonc` 合并： ```json { "$schema": "https://opencode.ai/config.json", "providers": { "onezhe": { "name": "1折AI", "env": ["ONEZHE_API_KEY"], "package": "@opencode/ai/providers/openai-compatible", "settings": { "baseURL": "https://1zheai.com/v1" }, "models": { "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" } } } } } ``` 在启动 OpenCode 的进程环境提供 `ONEZHE_API_KEY`，然后 `/models` 选择 `onezhe/claude-sonnet-4-6`。v2 主要差异是 `providers`、`package`、`settings`，而非 v1 的 `provider`、`npm`、`options`。请先用 `opencode --version` 确认所用大版本。 若要使用原生 Anthropic，v1 官方允许覆盖 `provider.anthropic.options.baseURL`，示例包含 `/v1`；v2 列出 `@opencode/ai/providers/anthropic-compatible`。本教程走明确的 OpenAI 兼容配置，不能据模型名称自行更换协议或承诺缓存、工具调用都已验证。 ## 验证接入与排错 1. 保存并重新加载配置，确认当前选中的是 `onezhe` 供应商或你添加的自定义模型。 2. 发送一句简短问题，确认能够返回；随后尝试一个可撤销的小任务，单独确认工具调用和多轮对话。 3. 打开[调用日志](/docs/usage-logs/)，核对请求时间、模型、状态与用量。一次文本回复成功不代表所有 Agent 能力都已兼容。 4. 遇到 404，核对本文地址和协议是否配套；遇到 401，核对密钥来源和进程是否读取到环境变量；遇到 429，查看限流信息后再重试。更多情况见[错误码与排错](/docs/troubleshooting/)。 密钥只保存在本地环境或工具的凭据存储中，不要提交到代码仓库、截图或公开日志。后台服务可能不继承终端环境变量；辅助模型、搜索和其他工具也可能有独立的供应商设置，需要分别检查。 ## 费用与其他接入方式 查看[Claude API 实时价格](https://1zheai.com/pricing/)和[计费规则](/docs/pricing-explained/)。需要其他客户端时返回[工具接入目录](/docs/integrations/)；自己编写程序可用[SDK 与开发指南](/docs/guides/)。 --- # Cursor 接入 Source: https://1zheai.com/docs/quickstart-cursor/ Markdown: https://1zheai.com/docs/quickstart-cursor.md --- title: Cursor 接入 description: 在 Cursor 里用自定义 OpenAI API 密钥和 Base URL 调用 1折AI 的 Claude 模型，以及哪些功能不会走自定义 API 密钥。 --- Cursor 允许在设置里填自己的 API 密钥（API key），聊天模型会用这个 API 密钥发请求。下面是接 1折AI 的做法，以及几个必须先知道的限制。 先了解这三点再动手： - Cursor 官方说明里，**自定义 API 密钥只对聊天模型生效，Tab 补全始终用 Cursor 自己的模型**。 - 请求会先经过 Cursor 的服务器再发给你填的地址，所以 Base URL 必须是公网可访问的（`https://1zheai.com/v1` 没问题，本地 `localhost` 代理不行）。 - "Override OpenAI Base URL" 这个开关不在 Cursor 的官方文档里，下面的界面描述来自 Cursor 论坛和社区教程，Cursor 改版后可能变化。 ## 配置 Cursor → **Cursor Settings** → **Models**，找到 Keys 区域。 ```text OpenAI API Key sk-你的Key（1折AI 的 Key） Override OpenAI Base URL https://1zheai.com/v1 ``` Base URL 要带 `/v1`。 在模型列表里点 **Add model**，输入模型 ID，例如 `claude-sonnet-5-5`，然后打开它的开关。模型 ID 见[支持的模型](/docs/models/)。 在 Chat 面板选刚加的模型，发一条消息。回复正常后，到控制台[调用日志](/docs/usage-logs/)确认这笔调用。 ## 已知问题 Cursor 论坛有反馈：设置了 Override OpenAI Base URL 后，名字以 `claude-` 开头的模型可能会被 Cursor 当成 Anthropic 模型，交给 Anthropic 的 API 密钥处理，或者直接报错。选择 Claude 时，模型 ID 以 `claude-` 开头，如果遇到这个问题，先清空 Cursor 里填过的 Anthropic API 密钥再试。 参考：[论坛帖 144899](https://forum.cursor.com/t/anthropic-models-break-when-override-openai-baseurl-is-set/144899)、[论坛帖 146998](https://forum.cursor.com/t/override-anthropic-base-url-automatically-switches-on-when-using-anthropic-byok/146998)。 ## 常见问题 不会。按 Cursor 官方说明，Tab 补全一直用 Cursor 自带的模型，不走你的 API 密钥。 先确认 Base URL 带了 `/v1`。社区反馈 Verify 按钮对非 OpenAI 的模型名不一定通过，可以直接在 Chat 里发一条消息测试，以调用日志里有没有记录为准。 社区教程普遍反馈只有 Chat 走自定义 API 密钥，Agent、Apply、Inline Edit 等功能可能仍然走 Cursor 自己的后端。以你实际在调用日志里看到的记录为准。 如果你主要想用 Claude 写代码，[Claude Code](/docs/quickstart-claude-code/)（命令行或 VS Code 插件）和 [Cline](/docs/quickstart-cline/) 对自定义地址的支持更完整。 --- # Cline 接入 Source: https://1zheai.com/docs/quickstart-cline/ Markdown: https://1zheai.com/docs/quickstart-cline.md --- title: Cline 接入 description: 在 VS Code 的 Cline 插件里接入 1折AI：Anthropic 自定义 Base URL，或 OpenAI Compatible 两种方式。 --- Cline 是 VS Code 里的编程 Agent 插件。两种方式都能接 1折AI，推荐 Anthropic 方式，Claude 的原生能力（包括缓存）更完整。 ## 方式一：Anthropic（推荐） 打开 Cline 设置，**API Provider** 选 **Anthropic**。 - **Anthropic API Key**（填 API 密钥）：`sk-你的Key` - 勾选 **Use custom base URL**，填 `https://1zheai.com`（不要加 `/v1`） 在模型下拉里选一个 1折AI [支持的模型](/docs/models/)，比如 `claude-sonnet-5-5`。 ## 方式二：OpenAI Compatible **API Provider** 选 **OpenAI Compatible**。 | 字段 | 值 | |---|---| | Base URL | `https://1zheai.com/v1` | | API Key | `sk-你的Key` | | Model ID | `claude-sonnet-5-5` | 点 **Verify** 确认连接，然后在 Cline 里发一个小任务。 在 Model Configuration 里可以填上下文窗口和最大输出长度，按 [Anthropic 官方模型文档](https://platform.claude.com/docs/en/about-claude/models/overview) 填写对应模型的数值。 ## 常见问题 Anthropic 方式走原生 `/v1/messages`，缓存、thinking 等能力最完整；OpenAI Compatible 走 `/v1/chat/completions`，胜在通用。用 Claude 模型时优先选 Anthropic。 Anthropic 方式的地址不要带 `/v1`；OpenAI Compatible 方式的地址必须带 `/v1`。两者正好相反。 --- # Cherry Studio 接入 Source: https://1zheai.com/docs/quickstart-cherry-studio/ Markdown: https://1zheai.com/docs/quickstart-cherry-studio.md --- title: Cherry Studio 接入 description: 在 Cherry Studio 添加 1折AI 为自定义服务商，选 Anthropic 或 OpenAI 端点，填根地址、API 密钥和模型。 --- Cherry Studio 是桌面端的 AI 对话客户端，可以把 1折AI 添加成一个自定义服务商。 ## 配置 设置（齿轮图标）→ **模型服务** → 列表下方的 **+ 添加服务商**。 | 字段 | 填什么 | |---|---| | 提供商名称 | `1折AI` | | API 密钥 | `sk-你的Key` | | 端点 | 选 **Anthropic**（推荐）或 **OpenAI** | | API 地址 | `https://1zheai.com` | API 地址只填根地址，Cherry Studio 会按所选协议自动补上 `/v1/...`。不要把 `/v1/messages`、`/v1/chat/completions` 这类完整路径粘进去，也不要在末尾加 `#`（`#` 结尾表示不再自动补路径）。 点 **获取模型列表**，从返回的列表里添加要用的模型；或者点 **+** 手动输入模型 ID，比如 `claude-sonnet-5-5`。只有加进列表的模型才会出现在对话的模型选择里。 打开服务商页面右上角的启用开关，回到对话界面，选 1折AI 下的模型发一条消息。 ## 选 Anthropic 还是 OpenAI 端点 | 端点 | 适合 | |---|---| | Anthropic | 想用 extended thinking 等 Claude 原生能力；Cherry Studio 的 Agent 功能也要求 Anthropic 协议 | | OpenAI | 习惯 OpenAI 格式，或要和其他 OpenAI 兼容服务统一管理 | 两种端点用的是同一个 API 密钥（API key）和同一套模型 ID。 ## 常见问题 先检查 API 密钥有没有多余空格；再确认 API 地址是 `https://1zheai.com`，没有多写路径。获取不到也不影响使用，手动输入模型 ID 也能用。 API 地址写成了完整路径，或者末尾加了 `#`。改回根地址 `https://1zheai.com`。 --- # WorkBuddy 接入 Claude API Source: https://1zheai.com/docs/quickstart-workbuddy/ Markdown: https://1zheai.com/docs/quickstart-workbuddy.md --- title: WorkBuddy 接入 Claude API description: WorkBuddy 配置 1折AI Claude API 中转的地址、密钥与模型教程，包含协议选择、配置示例、验证步骤和常见错误。 --- 使用 WorkBuddy 的自定义供应商功能连接 1折AI。先[创建 API 密钥](/docs/api-keys/)，并确认[当前可用模型](/docs/models/)；下文模型 ID 是示例，请按你的密钥权限调整。 官方配置核对日期：2026-10-15。以下配置依据官方文档整理，本站端到端验证尚未完成；请先完成简短问答和工具调用验证，再用于长任务。OpenAI / GPT 模型已上线，模型列表与价格见[模型说明](/docs/models/)。 依据 [官方模型配置](https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Model)：设置 → 模型 → 添加模型 → 自定义/Custom。填写本站密钥、模型 `claude-sonnet-4-6`。 采用完整请求地址配置：高级配置开启「自定义协议」，URL 填 `https://1zheai.com/v1/chat/completions`，保存后在对话模型选择器选该模型。官方说明开启此开关会直接使用所填 URL，不做路径校验和自动补全；关闭时会按标准 `/chat/completions` 补全。因此完整 URL 与开关必须配套描述。 这里的「自定义协议」不表示可以把 OpenAI 请求自动转换成 Anthropic 请求，不能填 `/v1/messages` 后就宣称原生 Claude 协议接通。优先采用 UI，不提供未经核实的 `models.json` 手工格式。官方页面同时出现当前本地配置路径和旧 `~/.codebuddy/models.json` 迁移说明，避免据此把旧路径写成通用现行路径。界面上的工具能力标记也不能替代本站端到端验证。 ## 验证接入与排错 1. 保存并重新加载配置，确认当前选中的是 `onezhe` 供应商或你添加的自定义模型。 2. 发送一句简短问题，确认能够返回；随后尝试一个可撤销的小任务，单独确认工具调用和多轮对话。 3. 打开[调用日志](/docs/usage-logs/)，核对请求时间、模型、状态与用量。一次文本回复成功不代表所有 Agent 能力都已兼容。 4. 遇到 404，核对本文地址和协议是否配套；遇到 401，核对密钥来源和进程是否读取到环境变量；遇到 429，查看限流信息后再重试。更多情况见[错误码与排错](/docs/troubleshooting/)。 密钥只保存在本地环境或工具的凭据存储中，不要提交到代码仓库、截图或公开日志。后台服务可能不继承终端环境变量；辅助模型、搜索和其他工具也可能有独立的供应商设置，需要分别检查。 ## 费用与其他接入方式 查看[Claude API 实时价格](https://1zheai.com/pricing/)和[计费规则](/docs/pricing-explained/)。需要其他客户端时返回[工具接入目录](/docs/integrations/)；自己编写程序可用[SDK 与开发指南](/docs/guides/)。 --- # OpenClaw 接入 Claude API Source: https://1zheai.com/docs/quickstart-openclaw/ Markdown: https://1zheai.com/docs/quickstart-openclaw.md --- title: OpenClaw 接入 Claude API description: OpenClaw 配置 1折AI Claude API 中转的地址、密钥与模型教程，包含协议选择、配置示例、验证步骤和常见错误。 --- 使用 OpenClaw 的自定义供应商功能连接 1折AI。先[创建 API 密钥](/docs/api-keys/)，并确认[当前可用模型](/docs/models/)；下文模型 ID 是示例，请按你的密钥权限调整。 官方配置核对日期：2026-10-15。以下配置依据官方文档整理，本站端到端验证尚未完成；请先完成简短问答和工具调用验证，再用于长任务。OpenAI / GPT 模型已上线，模型列表与价格见[模型说明](/docs/models/)。 依据 [自定义提供商](https://docs.openclaw.ai/gateway/config-tools/custom-providers) 与 [配置示例](https://docs.openclaw.ai/gateway/configuration-examples)，在 `~/.openclaw/openclaw.json` 合并： ```json { "agents": { "defaults": { "model": { "primary": "onezhe/claude-sonnet-4-6" }, "models": { "onezhe/claude-sonnet-4-6": { "alias": "1折AI Claude" } } } }, "models": { "mode": "merge", "providers": { "onezhe": { "baseUrl": "https://1zheai.com", "apiKey": "${ONEZHE_API_KEY}", "api": "anthropic-messages", "models": [ { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" } ] } } } } ``` 确保实际运行 Gateway 的进程可读取 `ONEZHE_API_KEY`；终端中的环境变量不一定传给已有后台服务。[官方 Synthetic 文档](https://docs.openclaw.ai/providers/synthetic) 明确 Anthropic 客户端自动追加 `/v1`，因此这里不带 `/v1`，也不填完整 `/v1/messages`。 改用 Chat Completions 时，成对替换为 `baseUrl: "https://1zheai.com/v1"` 和 `api: "openai-completions"`。虽然名称含 completions，此适配器对应 `/v1/chat/completions`；不要误选 `openai-responses`。已有模型允许列表需保留其他条目并加入新模型。示例未编造成本或上下文参数；若当前安装版本校验需要额外元数据，先核实实际模型能力再补充。 ## 验证接入与排错 1. 保存并重新加载配置，确认当前选中的是 `onezhe` 供应商或你添加的自定义模型。 2. 发送一句简短问题，确认能够返回；随后尝试一个可撤销的小任务，单独确认工具调用和多轮对话。 3. 打开[调用日志](/docs/usage-logs/)，核对请求时间、模型、状态与用量。一次文本回复成功不代表所有 Agent 能力都已兼容。 4. 遇到 404，核对本文地址和协议是否配套；遇到 401，核对密钥来源和进程是否读取到环境变量；遇到 429，查看限流信息后再重试。更多情况见[错误码与排错](/docs/troubleshooting/)。 密钥只保存在本地环境或工具的凭据存储中，不要提交到代码仓库、截图或公开日志。后台服务可能不继承终端环境变量；辅助模型、搜索和其他工具也可能有独立的供应商设置，需要分别检查。 ## 费用与其他接入方式 查看[Claude API 实时价格](https://1zheai.com/pricing/)和[计费规则](/docs/pricing-explained/)。需要其他客户端时返回[工具接入目录](/docs/integrations/)；自己编写程序可用[SDK 与开发指南](/docs/guides/)。 --- # Hermes Agent 接入 Claude API Source: https://1zheai.com/docs/quickstart-hermes/ Markdown: https://1zheai.com/docs/quickstart-hermes.md --- title: Hermes Agent 接入 Claude API description: Hermes Agent 配置 1折AI Claude API 中转的地址、密钥与模型教程，包含协议选择、配置示例、验证步骤和常见错误。 --- 使用 Hermes Agent 的自定义供应商功能连接 1折AI。先[创建 API 密钥](/docs/api-keys/)，并确认[当前可用模型](/docs/models/)；下文模型 ID 是示例，请按你的密钥权限调整。 官方配置核对日期：2026-10-15。以下配置依据官方文档整理，本站端到端验证尚未完成；请先完成简短问答和工具调用验证，再用于长任务。OpenAI / GPT 模型已上线，模型列表与价格见[模型说明](/docs/models/)。 依据 [官方 Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)：终端运行 `hermes model` → Custom endpoint，API mode 明确选择 `chat_completions`，Base URL 填 `https://1zheai.com/v1`，填写密钥和模型。不要选 ChatGPT/Codex 登录，它是另一种接入方式。 可复用的命名 provider 配置，合并到 `~/.hermes/config.yaml`： ```yaml providers: onezhe: api: https://1zheai.com/v1 key_env: ONEZHE_API_KEY transport: chat_completions default_model: claude-sonnet-4-6 model: provider: custom:onezhe default: claude-sonnet-4-6 ``` 在 `~/.hermes/.env` 本地提供： ```dotenv ONEZHE_API_KEY=sk-替换为本站密钥 ``` 已配置后可在对话中切换 `/model custom:onezhe:claude-sonnet-4-6`。`/model` 不能代替终端 `hermes model` 创建新 provider。官方支持 `anthropic_messages` 传输，但本教程使用 Chat Completions，避免按 URL 自动猜测协议。`OPENAI_BASE_URL` 不是所有自定义 provider 的通用配置；应使用上面的显式配置。 ## 验证接入与排错 1. 保存并重新加载配置，确认当前选中的是 `onezhe` 供应商或你添加的自定义模型。 2. 发送一句简短问题，确认能够返回；随后尝试一个可撤销的小任务，单独确认工具调用和多轮对话。 3. 打开[调用日志](/docs/usage-logs/)，核对请求时间、模型、状态与用量。一次文本回复成功不代表所有 Agent 能力都已兼容。 4. 遇到 404，核对本文地址和协议是否配套；遇到 401，核对密钥来源和进程是否读取到环境变量；遇到 429，查看限流信息后再重试。更多情况见[错误码与排错](/docs/troubleshooting/)。 密钥只保存在本地环境或工具的凭据存储中，不要提交到代码仓库、截图或公开日志。后台服务可能不继承终端环境变量；辅助模型、搜索和其他工具也可能有独立的供应商设置，需要分别检查。 ## 费用与其他接入方式 查看[Claude API 实时价格](https://1zheai.com/pricing/)和[计费规则](/docs/pricing-explained/)。需要其他客户端时返回[工具接入目录](/docs/integrations/)；自己编写程序可用[SDK 与开发指南](/docs/guides/)。 --- # 用 CC Switch 接入 Source: https://1zheai.com/docs/quickstart-cc-switch/ Markdown: https://1zheai.com/docs/quickstart-cc-switch.md --- title: 用 CC Switch 接入 description: 在 CC Switch 里用自定义配置添加 1折AI，给 Claude Code 一键切换供应商，不用手改 settings.json。 --- [CC Switch](https://github.com/farion1231/cc-switch) 是一个桌面工具，帮你管理 Claude Code、Codex 等命令行工具的供应商配置。添加一次之后，在官方账号、1折AI 和其他供应商之间切换只要点一下。 ## 安装 - macOS：`brew install --cask cc-switch` - Windows / Linux：到 [GitHub Releases](https://github.com/farion1231/cc-switch/releases) 下载安装包 ## 给 Claude Code 添加 1折AI 在侧栏选中 **Claude Code**，点页头右侧的 **添加供应商**（+ 号）。 1折AI 目前不在 CC Switch 的预设列表里，选列表最上面的 **自定义配置**。 名称填 `1折AI`，配置编辑框里的 `env` 写成： ```json { "env": { "ANTHROPIC_BASE_URL": "https://1zheai.com", "ANTHROPIC_AUTH_TOKEN": "sk-你的Key" } } ``` 想同时固定模型，加上 `ANTHROPIC_MODEL` 等变量，写法见 [Claude Code 接入](/docs/quickstart-claude-code/)的模型映射一节。 点页脚的 **添加**，然后在供应商列表里启用 1折AI。CC Switch 会把配置写进 Claude Code 的 `~/.claude/settings.json`，Claude Code 不用重启就会用新的供应商。 在 Claude Code 里运行 `/status`，base URL 应该是 `https://1zheai.com`。再发一条消息，到控制台[调用日志](/docs/usage-logs/)确认有记录。 CC Switch 官方示例用的是 `ANTHROPIC_API_KEY`，两个变量都能用。我们推荐 `ANTHROPIC_AUTH_TOKEN`，原因见 [Claude Code 接入](/docs/quickstart-claude-code/)。 ## 获取模型列表 编辑供应商时，模型输入框旁边的 **获取模型列表** 按钮会用你的 API 密钥（API key）调用 `/v1/models`，列出可用模型，选一个填进去。 ## Codex CC Switch 也能管理 Codex 的供应商。配置本站 Base URL、API 密钥与 GPT 模型，见 [Codex CLI 接入](/docs/quickstart-codex/)。 ## 常见问题 先在 CC Switch 里确认 1折AI 是启用状态；再检查终端里有没有 export 过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AUTH_TOKEN`。Claude Code 以 settings.json 为准，但手动 export 的旧变量容易让人误判，建议都清掉，统一交给 CC Switch 管理。 API 密钥填错或已删除。重新复制一次 API 密钥，注意不要带空格。 --- # 开发指南 Source: https://1zheai.com/docs/guides/ Markdown: https://1zheai.com/docs/guides.md --- title: 开发指南 description: 选择 SDK 或 HTTP 接入方式，从第一条请求到流式输出与缓存。 --- 已有代码可以从对应 SDK 开始；尚未选择技术栈时，先用 curl 验证调用，再接入应用。 使用 Claude 原生协议，查看 Python 与 TypeScript 示例。 使用 OpenAI SDK 调用 GPT 或 Claude，配置模型 ID 与接口地址。 直接查看 HTTP 请求，排除 SDK 配置差异。 确认端点、协议和适用范围。 ## 接入后继续完善 - [流式输出](/docs/streaming/)：处理增量响应和断流。 - [Prompt Caching](/docs/prompt-caching/)：了解使用条件和结果核对方式。 - [错误码与排错](/docs/troubleshooting/)：按具体错误定位配置或上游问题。 - [用量日志与对账](/docs/usage-logs/)：核对请求记录。 使用现成软件时，可直接进入[工具接入](/docs/integrations/)。 --- # Anthropic SDK 接入（Python / TypeScript） Source: https://1zheai.com/docs/quickstart-anthropic-sdk/ Markdown: https://1zheai.com/docs/quickstart-anthropic-sdk.md --- title: Anthropic SDK 接入（Python / TypeScript） description: 用 Anthropic 官方 SDK 调 1折AI：base_url 填 https://1zheai.com，原生支持缓存、流式、工具调用和 thinking。 --- Anthropic 官方 SDK 走原生 `/v1/messages`，Claude 的所有参数都能直接用。改的地方只有 `base_url` 和 `api_key`。 ## 安装 ```bash title="Python" pip install anthropic ``` ```bash title="TypeScript / Node.js" npm install @anthropic-ai/sdk ``` ## 调用 ```python title="Python" import os import anthropic client = anthropic.Anthropic( base_url="https://1zheai.com", api_key=os.environ["ONEZHE_API_KEY"], ) message = client.messages.create( model="claude-sonnet-5-5", max_tokens=1024, messages=[{"role": "user", "content": "用一句话介绍你自己"}], ) print(message.model) print(message.content[0].text) print(message.usage) ``` ```typescript title="TypeScript" import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic({ baseURL: "https://1zheai.com", apiKey: process.env.ONEZHE_API_KEY, }); const message = await client.messages.create({ model: "claude-sonnet-5-5", max_tokens: 1024, messages: [{ role: "user", content: "用一句话介绍你自己" }], }); console.log(message.model); console.log(message.content); console.log(message.usage); ``` `base_url` 填根地址，不要加 `/v1`。 ## 流式输出 ```python title="Python" 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) ``` ```typescript title="TypeScript" const stream = client.messages.stream({ model: "claude-sonnet-5-5", max_tokens: 1024, messages: [{ role: "user", content: "写一首四行的诗" }], }); stream.on("text", (text) => process.stdout.write(text)); await stream.finalMessage(); ``` ## 带缓存的调用 把长且固定的内容放进 `system`，加上 `cache_control`： ```python title="Python" message = client.messages.create( model="claude-sonnet-5-5", max_tokens=1024, system=[ { "type": "text", "text": LONG_PROJECT_CONTEXT, # 每次都一样的长文本 "cache_control": {"type": "ephemeral"}, } ], messages=[{"role": "user", "content": "根据上面的说明回答：..."}], ) print(message.usage.cache_creation_input_tokens, message.usage.cache_read_input_tokens) ``` 第二次调用时 `cache_read_input_tokens` 大于 0 就是命中了。细节见 [Prompt Caching](/docs/prompt-caching/)。 ## 用环境变量 官方 SDK 会读取 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`，构造客户端时不传参数也行： ```bash export ANTHROPIC_BASE_URL="https://1zheai.com" export ANTHROPIC_API_KEY="sk-你的Key" ``` 然后构造客户端时不传参数： ```python client = anthropic.Anthropic() # 自动读取上面两个变量 ``` 如果这台机器上 Claude Code 也读这两个变量，它们会一起切到 1折AI，这通常正是你想要的。 ## 常见问题 `base_url` 多写了 `/v1`。Anthropic SDK 会自己拼 `/v1/messages`。 检查 API 密钥（API key）；另外，环境里如果同时存在 `ANTHROPIC_AUTH_TOKEN`（比如以前给 Claude Code 设的旧值），SDK 也会读它，把旧值删掉再试。 --- # OpenAI SDK 接入（Python / Node） Source: https://1zheai.com/docs/quickstart-openai-sdk/ Markdown: https://1zheai.com/docs/quickstart-openai-sdk.md --- title: OpenAI SDK 接入（Python / Node） description: 用 OpenAI 官方 SDK 调 1折AI 的 GPT 与 Claude 模型：只改 base_url 和 api_key，附流式示例和环境变量写法。 --- 已经有用 OpenAI SDK 写的代码，换成 1折AI 只要改两个参数：`base_url` 和 `api_key`。模型名填入当前可用的 GPT 或 Claude 模型 ID。 ## 安装 ```bash title="Python" pip install openai ``` ```bash title="Node.js" npm install openai ``` ## 调用 ```python title="Python" import os from openai import OpenAI client = OpenAI( base_url="https://1zheai.com/v1", api_key=os.environ["ONEZHE_API_KEY"], ) resp = client.chat.completions.create( model="gpt-5.6-sol", messages=[{"role": "user", "content": "用一句话解释什么是 prompt caching"}], ) print(resp.model) print(resp.choices[0].message.content) print(resp.usage) ``` ```javascript title="Node.js" import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://1zheai.com/v1", apiKey: process.env.ONEZHE_API_KEY, }); const resp = await client.chat.completions.create({ model: "gpt-5.6-sol", messages: [{ role: "user", content: "用一句话解释什么是 prompt caching" }], }); console.log(resp.model); console.log(resp.choices[0].message.content); console.log(resp.usage); ``` `base_url` 要带 `/v1`。 ## 流式输出 ```python title="Python" stream = client.chat.completions.create( model="gpt-5.6-sol", 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) ``` ```javascript title="Node.js" const stream = await client.chat.completions.create({ model: "gpt-5.6-sol", messages: [{ role: "user", content: "写一首四行的诗" }], stream: true, }); for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta?.content ?? ""); } ``` ## 用环境变量，不改代码 OpenAI 官方 SDK（Python 和 Node）会读取 `OPENAI_BASE_URL` 和 `OPENAI_API_KEY`。代码里不传参数时，设置这两个变量就能切过来： ```bash export OPENAI_BASE_URL="https://1zheai.com/v1" export OPENAI_API_KEY="sk-你的Key" ``` 注意这会影响同一环境里所有用 OpenAI SDK 的程序。 ## 什么时候换 Anthropic SDK OpenAI 兼容接口适合"已有代码、只想换模型"。如果你需要 Prompt Caching 的 `cache_control`、extended thinking、Claude 的工具调用格式，用 [Anthropic SDK](/docs/quickstart-anthropic-sdk/) 走原生接口更合适。 ## 常见问题 `base_url` 少了 `/v1`。OpenAI SDK 只会在后面拼 `/chat/completions`。 可以。OpenAI / GPT 模型已上线，请使用[支持的模型](/docs/models/)中你的密钥可调用的模型 ID。 --- # curl 调用 Source: https://1zheai.com/docs/quickstart-curl/ Markdown: https://1zheai.com/docs/quickstart-curl.md --- title: curl 调用 description: 不装任何 SDK，用 curl 调 1折AI 的 /v1/messages 和 /v1/chat/completions，查模型列表、测缓存、看流式输出。 --- curl 是确认"API 密钥（API key）和地址到底通没通"最快的办法。下面每条都能直接复制，先把 API 密钥放进环境变量： ```bash export ONEZHE_API_KEY="sk-你的Key" ``` Windows 用户建议在 WSL 或 Git Bash 里跑这些命令；PowerShell 的写法见[快速开始](/docs/quickstart/)。 ## Anthropic 原生：/v1/messages ```bash curl https://1zheai.com/v1/messages \ -H "x-api-key: $ONEZHE_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5-5", "max_tokens": 128, "messages": [{"role": "user", "content": "ping"}] }' ``` ## OpenAI 兼容：/v1/chat/completions ```bash curl https://1zheai.com/v1/chat/completions \ -H "Authorization: Bearer $ONEZHE_API_KEY" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5-5", "messages": [{"role": "user", "content": "ping"}] }' ``` ## 模型列表：/v1/models ```bash curl https://1zheai.com/v1/models \ -H "Authorization: Bearer $ONEZHE_API_KEY" ``` ## 流式输出 加 `"stream": true`，并用 `-N` 关掉 curl 的缓冲，才能看到逐段返回： ```bash curl -N https://1zheai.com/v1/messages \ -H "x-api-key: $ONEZHE_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5-5", "max_tokens": 128, "stream": true, "messages": [{"role": "user", "content": "从一数到五"}] }' ``` 事件格式见[流式输出](/docs/streaming/)。 ## 测缓存 同一条请求连发两次，第二次回包的 `usage.cache_read_input_tokens` 大于 0 就说明命中。`system` 里的文本需要达到模型的最小可缓存长度，完整脚本见[核对模型和用量](/docs/verify-model/)，原理见 [Prompt Caching](/docs/prompt-caching/)。 ```bash curl https://1zheai.com/v1/messages \ -H "x-api-key: $ONEZHE_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5-5", "max_tokens": 32, "system": [{ "type": "text", "text": "把一段至少 512 token、每次都一样的长文本放在这里", "cache_control": {"type": "ephemeral"} }], "messages": [{"role": "user", "content": "ping"}] }' ``` ## 排查时加上 -i ```bash curl -i https://1zheai.com/v1/models -H "Authorization: Bearer $ONEZHE_API_KEY" ``` `-i` 会打印状态码和响应头。状态码含义见[错误码与排错](/docs/troubleshooting/)。 --- # 流式输出 Source: https://1zheai.com/docs/streaming/ Markdown: https://1zheai.com/docs/streaming.md --- title: 流式输出 description: 在 1折AI 上用流式输出：Anthropic 原生的 SSE 事件序列、OpenAI 兼容的 chunk 格式，以及断流时怎么处理。 --- 长回答用流式输出（`"stream": true`），首字更快出来，也不容易因为单个请求时间太长被中间网络掐断。两种协议都支持，格式各自和官方一致。 ## Anthropic 原生 请求里加 `"stream": true`，返回的是 Server-Sent Events。一次正常的流按这个顺序（来自 [Anthropic Streaming 文档](https://platform.claude.com/docs/en/build-with-claude/streaming)）： | 事件 | 含义 | |---|---| | `message_start` | 消息开始，带模型和初始 `usage` | | `content_block_start` | 一个内容块开始（文本、thinking、tool_use） | | `content_block_delta` | 内容增量，文本在 `delta.text` 里 | | `content_block_stop` | 这个内容块结束 | | `message_delta` | 消息级更新，带 `stop_reason` 和最终的输出 token 数 | | `message_stop` | 整条消息结束 | 中间可能穿插 `ping` 事件，可以忽略；出错时会收到 `error` 事件。 ```bash curl -N https://1zheai.com/v1/messages \ -H "x-api-key: $ONEZHE_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-sonnet-5-5","max_tokens":128,"stream":true, "messages":[{"role":"user","content":"从一数到五"}]}' ``` 用 SDK 时不用自己解析事件，见 [Anthropic SDK](/docs/quickstart-anthropic-sdk/) 的流式示例。 ## OpenAI 兼容 `/v1/chat/completions` 加 `"stream": true`，返回 `data: {...}` 形式的 chunk，文本在 `choices[0].delta.content` 里，最后以 `data: [DONE]` 结束。SDK 示例见 [OpenAI SDK](/docs/quickstart-openai-sdk/)。 `[DONE]` 前的最后一个 chunk 带 `usage`，`choices` 是空数组。不传 `stream_options.include_usage` 也会返回。2026-10-15 实测的完整流： ```text data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]} data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"content":"ok"},"finish_reason":null}]} data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"content":""},"finish_reason":"stop"}]} data: {"id":"msg_011Cg3ERqM8nN58LxLt7TVuG","object":"chat.completion.chunk","created":1792031230,"model":"claude-sonnet-4-6","choices":[],"usage":{"prompt_tokens":370,"completion_tokens":4,"total_tokens":374}} data: [DONE] ``` 处理 chunk 时先判断 `choices` 是否为空，上面 OpenAI SDK 页的示例已经这样写了。 ## 流断了怎么办 - 先看是不是代理：关掉代理直连再试。 - 客户端的读超时要比模型生成时间长，长输出时调大超时设置。 - 收到 `error` 事件里的 `overloaded_error`，等几秒重试，见[错误码与排错](/docs/troubleshooting/)。 ## 中途断开怎么计费 中途断开的请求不是整笔免费，按断开前已经生成的输出 token 计费，记录在调用日志里。计费的输出可能比客户端实际收到的多一些。2026-10-15 实测，让模型从 1 数到 600，客户端在第 4 秒断开时收到了 188 行（约 380 个输出 token），调用日志记的输出是 750 token。不需要的长输出，与其中途断开，不如一开始就把 `max_tokens` 设小。 --- # Prompt Caching 使用与计费 Source: https://1zheai.com/docs/prompt-caching/ Markdown: https://1zheai.com/docs/prompt-caching.md --- title: Prompt Caching 使用与计费 description: 在 1折AI 上使用 Claude Prompt Caching：怎么开、最小长度、怎么确认命中、命中后怎么计费，以及 Claude Code 的缓存行为。 --- Prompt Caching 让重复发送的长前缀（系统提示、工具定义、长文档、对话历史）只在第一次按写入计费，之后按读取计费。缓存读取的官方单价通常只有输入价的十分之一，我们在此基础上再乘 1.9 折。 ## 先说结论 - **Claude Code 默认就开着缓存**，接上就生效。 - 自己写代码调用时，在要缓存的内容块上加 `cache_control`，用原生 `/v1/messages`。OpenAI 兼容接口目前不缓存。 - 判断有没有命中，只看回包 `usage.cache_read_input_tokens` 是不是大于 0。 - 缓存默认活 5 分钟，每次命中会重新计时。也可以用 `"ttl": "1h"` 写入 1 小时缓存，写入价更高。 ## 怎么开 在 system、tools 或 messages 的内容块上加 `"cache_control": {"type": "ephemeral"}`，这个块及它之前的内容会被缓存。一次请求最多 4 个缓存断点。 ```bash curl https://1zheai.com/v1/messages \ -H "x-api-key: $ONEZHE_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5-5", "max_tokens": 256, "system": [ { "type": "text", "text": "这里放一段很长、每次都一样的内容：项目说明、代码规范、参考文档……", "cache_control": {"type": "ephemeral"} } ], "messages": [{"role": "user", "content": "根据上面的规范，审查这段代码：..."}] }' ``` 被缓存的前缀太短时，请求照常处理，只是不缓存，也不会报错。最小长度因模型而异，见下表。 ## 最小可缓存长度 以下来自 [Anthropic 官方文档](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)（2026-10-14）： | 最小 token 数 | 模型 | |---|---| | 512 | Fable 5.1、Fable 5、Opus 5.5、Opus 5、Sonnet 5.5、Haiku 5.5 | | 1,024 | Opus 4.8、Sonnet 5、Sonnet 4.6、Sonnet 4.5 | | 2,048 | Opus 4.7 | | 4,096 | Opus 4.6、Opus 4.5、Haiku 4.5 | ## 确认命中 同样的请求连发两次（间隔不超过 5 分钟），对比两次的 `usage`。下面是 2026-10-15 用 `claude-sonnet-5-5` 实测的结果，system 里放了约 1.8 万 token 的固定文本： ```json title="第一次：写入缓存" { "input_tokens": 23, "cache_creation_input_tokens": 17920, "cache_read_input_tokens": 0, "cache_creation": {"ephemeral_5m_input_tokens": 17920, "ephemeral_1h_input_tokens": 0}, "output_tokens": 4 } ``` ```json title="第二次：命中缓存" { "input_tokens": 23, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 17920, "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 0}, "output_tokens": 4 } ``` 第二次 `cache_read_input_tokens` 大于 0 就说明缓存在被读取。每一笔的缓存写入和读取 token 也会出现在[调用日志](/docs/usage-logs/)的 Token 列里，读取记为「缓存↓」，写入记为「↑」。 ## 怎么计费 | 类型 | 官方单价 | 1折AI 单价 | |---|---|---| | 缓存写入（5 分钟） | 输入价 × 1.25 | 官方价 × 1.9 折 | | 缓存写入（1 小时） | 输入价 × 2 | 官方价 × 1.9 折 | | 缓存读取 | 输入价 × 0.1（Opus 5.5、Sonnet 5.5 为 0.05，Fable 5.1 为 0.025） | 官方价 × 1.9 折 | 写入比普通输入贵 25%，所以只缓存会被重复用到的内容。一段前缀只要被读到一次就已经划算：写一次加读一次是 1.25 + 0.1 = 1.35 倍输入价，不缓存发两次是 2 倍。完整算例见[价格与计费](/docs/pricing-explained/)。 ### 1 小时缓存 在 `cache_control` 里加 `"ttl": "1h"`，缓存会保留 1 小时，适合间隔超过 5 分钟、但仍会反复用到的前缀： ```json "cache_control": {"type": "ephemeral", "ttl": "1h"} ``` 写入按输入价的 2 倍计，读取和 5 分钟缓存一样。回包里写入的 token 出现在 `cache_creation.ephemeral_1h_input_tokens`。2026-10-15 用同一段 3,144 token 的前缀各写入一次，按调用日志里的费用复算，写入部分分别正好是输入价的 1.25 倍和 2 倍。只有间隔经常超过 5 分钟时，1 小时缓存才划算。 ## Claude Code 的缓存 Claude Code 会自动给系统提示、工具定义和对话历史打缓存断点，[官方说明在这里](https://code.claude.com/docs/zh-CN/prompt-caching)。想让它命中得更好： - 一个会话里连续干活，别中途长时间停下。缓存 5 分钟没被用到就过期了。 - 同一个会话里的后续请求会读缓存。2026-10-15 实测，一次两轮的 Claude Code 任务，第二轮缓存读取 31,440 token、写入 115 token。新开一个会话时，第一轮可能要重新写入整段前缀（实测约 3 万 token），这一笔会比后面的贵。 - 少在会话中途改 `CLAUDE.md`、切换 MCP 服务器或换模型，这些都会让前缀变化。 - 不要设置 `DISABLE_PROMPT_CACHING=1`，这个环境变量会关掉所有模型的缓存。 ## OpenAI 兼容接口能用缓存吗 目前不能。2026-10-15 实测，在 `/v1/chat/completions` 的 system 消息里放约 3,100 token 的固定文本，连发两次，不管内容块上加不加 `cache_control`，两次的 `usage` 都是： ```json {"prompt_tokens": 3167, "completion_tokens": 4, "total_tokens": 3171} ``` 没有 `prompt_tokens_details.cached_tokens`，调用日志里的缓存读取和写入也都是 0，整段按输入价计费。需要缓存的场景请用 `/v1/messages`（Anthropic SDK 或 Claude Code）。 ## 常见问题 缓存写进去了，但下一次没读到。按顺序排查：两次请求是否超过 5 分钟；断点前的内容是否一字不差（时间戳、随机 ID 放进 system 会让每次都不同）；是否换了模型；前缀是否达到上面的最小长度。 每一笔的缓存读取、缓存写入 token 都在调用日志里，可以自己算：缓存读取 ÷（输入 + 缓存写入 + 缓存读取）。 --- # API 参考 Source: https://1zheai.com/docs/api-reference/ Markdown: https://1zheai.com/docs/api-reference.md --- title: API 参考 description: 查找已记录的接口、请求示例和协议差异，明确兼容范围。 --- 这里汇总本站现有接口说明与请求示例。本站已提供 Claude 与 OpenAI / GPT 模型。请按模型和工具选择对应协议，具体模型以你的密钥可用列表为准。 ## 接口索引 | 接口 | 用途 | 说明与示例 | | --- | --- | --- | | `POST /v1/messages` | Anthropic 原生对话 | [地址与请求头](/docs/base-url/)、[Anthropic SDK](/docs/quickstart-anthropic-sdk/)、[curl](/docs/quickstart-curl/) | | `POST /v1/chat/completions` | OpenAI 兼容对话 | [OpenAI SDK](/docs/quickstart-openai-sdk/)、[curl](/docs/quickstart-curl/) | | `POST /v1/responses` | OpenAI Responses | [Codex CLI](/docs/quickstart-codex/) | | `GET /v1/models` | 查询密钥可用的模型 | [模型列表](/docs/models/)、[请求方式](/docs/base-url/) | | `POST /v1/messages/count_tokens` | 输入 token 计数 | [接口说明](/docs/base-url/) | ## 兼容范围 Claude 原生能力优先参考 Anthropic 接入教程。切换协议前，核对所需能力在对应教程中的说明；不要仅凭请求成功推断工具调用、缓存或长任务均受支持。 Codex 使用 `/v1/responses`，见 [Codex CLI 接入](/docs/quickstart-codex/)。当前可用模型以[模型说明](/docs/models/)及你的密钥实际返回的列表为准。 ## 响应与故障 两种协议的事件格式与断流处理。 按状态码和错误信息定位问题。 本页是接口索引，尚未提供完整参数 Schema 或可下载的 OpenAPI 规范。需要具体请求时，使用上面的 SDK 与 curl 示例。 --- # Base URL、接口与鉴权 Source: https://1zheai.com/docs/base-url/ Markdown: https://1zheai.com/docs/base-url.md --- title: Base URL、接口与鉴权 description: 1折AI 的 Base URL、可用接口、请求头写法，以及不同工具里要不要加 /v1。 --- 所有请求都发到同一个域名，按协议分两套路径。 ```text https://1zheai.com ``` ## 可用接口 | 接口 | 协议 | 用途 | |---|---|---| | `POST /v1/messages` | Anthropic 原生 | 对话。Claude Code、Anthropic SDK、Cline（Anthropic 模式）走这里 | | `POST /v1/chat/completions` | OpenAI 兼容 | 对话。OpenAI SDK、Cursor、Cherry Studio（OpenAI 模式）走这里 | | `GET /v1/models` | OpenAI 兼容 | 列出你的 API 密钥（API key）能用的模型 | | `POST /v1/messages/count_tokens` | Anthropic 原生 | 计算一段输入的 token 数，不产生对话，不扣费 | `count_tokens` 的请求体和 `/v1/messages` 一样（`model`、`messages`，可以带 `system` 和 `tools`），回包只有一个字段： ```json {"input_tokens":19} ``` `count_tokens` 只数你发送的内容。用 SDK、curl 或第三方工具实际调用时，每次请求还会附带一段系统提示，按输入 token 计费（Claude Code 不附带），见[系统提示的计费](/docs/pricing-explained/#系统提示的计费)。 Prompt Caching、extended thinking、工具调用这些 Claude 特有的能力，用原生 `/v1/messages` 最稳。OpenAI 兼容接口适合已有 OpenAI 代码、只想换个模型的场景。 ## 要不要加 /v1 不同工具对 Base URL 的理解不一样，这是接入时最常见的坑： | 工具 / SDK | 填什么 | 原因 | |---|---|---| | Claude Code（`ANTHROPIC_BASE_URL`） | `https://1zheai.com` | 工具自己会拼 `/v1/messages` | | Anthropic SDK（`base_url`） | `https://1zheai.com` | 同上 | | OpenAI SDK（`base_url`） | `https://1zheai.com/v1` | SDK 只拼 `/chat/completions` | | Cursor（Override OpenAI Base URL） | `https://1zheai.com/v1` | 同 OpenAI SDK | | Cherry Studio | `https://1zheai.com` | 会自动补 `/v1/...` | | Cline（OpenAI Compatible） | `https://1zheai.com/v1` | 同 OpenAI SDK | 规律：Anthropic 系填根地址，OpenAI 系填到 `/v1`。填错的典型表现是 404。 ## 鉴权请求头 API 密钥放在请求头里，两种写法都可以： ```text title="Anthropic 原生" x-api-key: sk-你的Key anthropic-version: 2023-06-01 content-type: application/json ``` ```text title="Bearer（两种协议都支持）" Authorization: Bearer sk-你的Key content-type: application/json ``` - 调 `/v1/messages` 时按官方协议带上 `anthropic-version`，目前的值是 `2023-06-01`。实测不带也能调通，但官方 SDK 和工具都会带，自己写请求时也照带。 - Claude Code 的 `ANTHROPIC_AUTH_TOKEN` 发的是 `Authorization: Bearer`，`ANTHROPIC_API_KEY` 发的是 `x-api-key`，两种我们都认。 - 需要 beta 功能时，照官方文档带上 `anthropic-beta` 头。带上不认识的值不会报错，所以某个 beta 功能是否生效，以回包里的实际效果为准。 ## 检查 API 密钥是否可用 ```bash curl https://1zheai.com/v1/models \ -H "Authorization: Bearer sk-你的Key" ``` 返回模型列表说明 API 密钥和地址都对。返回 401 是 API 密钥的问题，回包长这样（2026-10-15 实测）： ```json {"error":{"code":"","message":"Invalid token (request id: 202610150244361675490398268d9d6eKJPmcph)","type":"authentication_error"}} ``` 用 `x-api-key` 和 `anthropic-version` 头请求 `/v1/models` 时，返回的是 Anthropic 格式的模型列表（`data[].id`、`display_name`、`has_more`），Claude Code 的模型自动发现读的就是这个格式。 其它情况见[错误码与排错](/docs/troubleshooting/)。 ## 速率限制 目前不对 API 密钥设速率限制。收到 429，通常是上游负载高，稍后重试即可，批量任务加指数退避。详见[错误码与排错](/docs/troubleshooting/)。 ## 网络 连接超时或 TLS 报错时，先确认终端走的网络：开着全局代理的话，关掉代理直连再试一次；公司网络有出口白名单的，需要放行 `1zheai.com`。 --- # 账户与支持 Source: https://1zheai.com/docs/support/ Markdown: https://1zheai.com/docs/support.md --- title: 账户与支持 description: 管理费用与调用记录，定位接入问题，并提供必要的排错信息。 --- ## 费用与账户 了解费用构成和计算说明。 查询支付与售后规则。 定位每次调用并核对费用。 查看创建、存放和轮换说明。 ## 调用遇到问题 先查看[错误码与排错](/docs/troubleshooting/)，再核对[地址与协议](/docs/base-url/)以及[工具限制](/docs/integrations/)。检查模型和用量的方法见[核对模型和用量](/docs/verify-model/)。 如果仍需要帮助，请通过控制台或官网公布的支持渠道提供：发生时间与时区、工具及版本、模型 ID、HTTP 状态码、请求 ID（如有）、脱敏后的错误信息，以及是否能用最小请求复现。 不要发送完整 API 密钥、认证请求头或包含私人内容的完整对话。 --- # 价格与计费 Source: https://1zheai.com/docs/pricing-explained/ Markdown: https://1zheai.com/docs/pricing-explained.md --- title: 价格与计费 description: 1折AI 怎么计价：官方美元标价乘一个折扣，缓存读写同折扣；附一次调用的完整算例。 --- 一句话：**所有模型按 Anthropic 官方美元标价计价，统一乘一个折扣，当前是 1.9 折。** 输入、输出、缓存读、缓存写都用这同一个折扣。实时折扣和每个模型的单价在[价格页](https://1zheai.com/pricing/)。 ## 一次调用扣多少 每次调用按回包 `usage` 里的四类 token 分别计费： ```text 费用 = ( 输入 token × 输入单价 + 缓存写入 token × 缓存写单价 + 缓存读取 token × 缓存读单价 + 输出 token × 输出单价 ) ÷ 1,000,000 每一项单价 = 官方美元单价（每百万 token）× 折扣 ``` 四类 token 对应回包里的字段： | 计费项 | `usage` 字段（Anthropic 原生） | 官方单价相对输入价 | |---|---|---| | 输入 | `input_tokens` | 1× | | 缓存写入 | `cache_creation_input_tokens` | 1.25×（5 分钟缓存），2×（1 小时缓存，`"ttl": "1h"`） | | 缓存读取 | `cache_read_input_tokens` | 0.1×（Opus 5.5、Sonnet 5.5 为 0.05×，Fable 5.1 为 0.025×） | | 输出 | `output_tokens` | 按模型，见价格页 | 缓存的官方倍数来自 [Anthropic Prompt Caching 文档](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)。我们不改这些比例，只在最后乘折扣。 1 小时缓存的写入 token 单独记在 `cache_creation.ephemeral_1h_input_tokens`，按输入价的 2 倍再乘折扣计费，2026-10-15 已按调用日志复算核对。价格页列出的缓存写入单价是 5 分钟缓存的。 ## 算例 下面的单价是为了演示随手取的整数，不对应具体模型；真实单价看价格页。 假设某模型官方单价（每百万 token）：输入 $3，输出 $15，缓存写 $3.75，缓存读 $0.30。一次 Claude Code 请求的 `usage` 是： ```json { "input_tokens": 2000, "cache_creation_input_tokens": 1500, "cache_read_input_tokens": 30000, "output_tokens": 800 } ``` 按官方价： | 项 | token | 官方单价 | 官方费用 | |---|---|---|---| | 输入 | 2,000 | $3 | $0.006 | | 缓存写入 | 1,500 | $3.75 | $0.005625 | | 缓存读取 | 30,000 | $0.30 | $0.009 | | 输出 | 800 | $15 | $0.012 | | 合计 | | | $0.032625 | 在 1折AI 实际扣费 = $0.032625 × 1.9 折。 同一请求如果缓存没命中，那 30,000 token 会按输入价算，单这一项就是 $0.09，整笔变成原来的三倍多。所以对 Claude Code 这类反复发送长上下文的工具，**缓存命中率对账单的影响比单价更大**，开法和检查方法见 [Prompt Caching](/docs/prompt-caching/)。 ## 系统提示的计费 Claude API 来自官方订阅账号池。通过 Claude Code 调用不附带额外内容。其他客户端（SDK、curl 和第三方工具）的每次请求会附带一段系统提示，按输入 token 计费：Sonnet 4.6 约 350 token，5.x 系列约 500 token。这部分和你自己发送的内容一起算在回包 `usage` 的 `input_tokens` 里。 2026-10-15 用 curl 发一句「Reply with just: ok」的实测： | 模型 | `count_tokens` 计数 | 实际 `input_tokens` | 附带的系统提示（约） | |---|---|---|---| | Sonnet 4.6 | 19 | 370 | 350 token | | 5.x 系列 | 18–19 | 510–530 | 约 500 token | - `count_tokens` 只数你发送的内容，不含这段系统提示。用 SDK、curl 或第三方工具预估费用时，把上表的数加上；Claude Code 不需要。 - 调用日志里记录的输入 token 已经包含这部分，按上面的公式复算，结果和日志里的扣费一致。 - 请求越短，这部分占比越高；长上下文请求里占比很小。 ## 余额与币种 - 扣费按上面的美元算法计算，从你的账户余额里扣。余额以美元计。 - 人民币充值按实时汇率换算成美元余额。 ## 为什么只有一个数 所有模型、输入输出和缓存读写都只乘一个折扣，拿它直接和官方价比。每一笔扣费在[调用日志](/docs/usage-logs/)里都能按上面的公式复算。 ## 常见问题 最常见的原因是缓存没命中：两次请求之间隔得太久（默认缓存 5 分钟）、上下文前半段变了、或者换了模型。打开调用日志对比两笔的缓存读取 token 就能看出来。 打折，和输入输出是同一个折扣。缓存写入、缓存读取的单价都是官方单价乘 1.9 折。 通过 Claude Code 调用不附带额外内容。其他客户端（SDK、curl 和第三方工具）的每次请求会附带一段系统提示，按输入 token 计费：Sonnet 4.6 约 350 token，5.x 系列约 500 token。实测数据见[系统提示的计费](#系统提示的计费)。 在调用日志里找到这笔，拿四类 token 数和价格页的单价代进上面的公式，结果应该和日志里的扣费一致。对不上的话把这条日志的时间和模型发给我们。 --- # 用量日志与对账 Source: https://1zheai.com/docs/usage-logs/ Markdown: https://1zheai.com/docs/usage-logs.md --- title: 用量日志与对账 description: 在 1折AI 控制台的调用日志里看每一次调用的模型、四类 token 和扣费，并按公式复算一笔账。 --- 每一次调用都会在调用日志里留下一条明细。这页讲怎么看、怎么对账。 ## 在哪里看 [控制台](https://1zheai.com/console) 左侧菜单 →「使用日志」（地址 `https://1zheai.com/usage-logs`），页面标题是「通用日志」。 顶部可以按时间范围筛选，点「展开」后还能按模型名称、API 密钥名称（「令牌名称」）、请求 ID 和日志类型筛选。筛好后点「搜索」；「导出」把当前筛选结果下载下来，方便在表格里对账。 ## 每条日志有什么 | 列 | 内容 | |---|---| | 时间 | 请求发生的时间 | | 令牌 | 这次调用用的 API 密钥名称 | | 模型 | 实际调用的模型 ID | | 流 | 「流」或「非流」，以及输出速度（t/s） | | Token | 第一行是「输入 / 输出」token；有缓存时下面多一行，「缓存↓」后是缓存读取 token，「↑」后是缓存写入 token | | 费用 | 这次调用扣的美元金额 | | 耗时 | 总耗时；流式请求还会显示首字时间 | | 详情 | 这次调用的单价等明细 | 被网关拒绝的请求（API 密钥无效、余额不足、模型写错等）不扣费。上游返回错误的请求费用为 0。流式请求中途断开不是整笔免费，见[流式输出](/docs/streaming/)。 ## 对一笔账 按时间和模型找到要核对的那一条，记下 Token 列里的输入、输出、缓存读取（缓存↓）和缓存写入（↑）四个数。 在[价格页](https://1zheai.com/pricing/)找到该模型的输入、输出、缓存读、缓存写单价（已经乘过折扣）。 ```text 扣费 = ( 输入 × 输入单价 + 缓存写入 × 缓存写单价 + 缓存读取 × 缓存读单价 + 输出 × 输出单价 ) ÷ 1,000,000 ``` 结果应该和日志里的扣费一致。四舍五入可能带来最后一位的差别。 对不上的话，把这条日志的时间、模型和截图发给我们。 ## 用日志看缓存效果 在 Claude Code 这类工具里，大部分输入应该落在"缓存读取"这一列。如果连续几条都是大量"缓存写入"、"缓存读取"却很少，说明缓存没在复用，原因和改法见 [Prompt Caching](/docs/prompt-caching/)。 一个粗略的命中率：缓存读取 ÷（输入 + 缓存写入 + 缓存读取）。 ## 和你自己的统计对不上 - Claude Code 会用 Haiku 级模型做一些后台小任务，所以日志里会出现你没主动选过的模型。见 [Claude Code 接入](/docs/quickstart-claude-code/)的模型映射。 - 日志里的输入 token 比你发送的内容多出几百：用 SDK、curl 或第三方工具调用时，每次请求会附带一段系统提示，按输入计费（Claude Code 不附带），见[系统提示的计费](/docs/pricing-explained/#系统提示的计费)。 - 一次工具里的"对话"可能对应很多次 API 调用（每次工具调用一轮），日志是按 API 调用记录的。 --- # 充值、退款与发票 Source: https://1zheai.com/docs/billing/ Markdown: https://1zheai.com/docs/billing.md --- title: 充值、退款与发票 description: 1折AI 怎么充值、最低金额、支持的支付方式、7 天未用额度退款规则，以及各支付方式能开什么发票。 --- 按量付费：先充值，调用时从余额里扣，没有月卡和套餐。 ## 充值 | 项 | 说明 | |---|---| | 最低金额 | ¥100 | | 支付方式 | 微信支付、支付宝、Stripe（银行卡）、USDT | | 入口 | [控制台](https://1zheai.com/console) 左侧菜单「钱包」→「添加资金」 | | 怎么扣费 | 官方美元标价 × 1.9 折，见[价格与计费](/docs/pricing-explained/) | 人民币充值按实时汇率换算成美元余额。 ## 退款 **充值 7 天内，没用掉的额度可以退，原路退回到你付款的账户。** 已经用掉的部分按调用日志里的扣费计算，不退。 在调用日志里看这笔充值之后的消耗，可退金额 = 充值金额 − 已用金额。 发邮件到 support@1zheai.com，写明账户、充值时间和支付方式。 第一次用，建议先充 ¥100，按[核对模型和用量](/docs/verify-model/)把检查跑一遍，再在你的真实任务里用几天。不满意，7 天内没用完的部分可以退。 ## 发票 | 支付方式 | 能开什么 | |---|---| | 微信支付 / 支付宝 | 可开发票，另收付款金额的 6% | | Stripe（银行卡） | Stripe invoice（英文） | | USDT | 不提供发票 | 开发票、企业采购和对公转账，发邮件到 support@1zheai.com 联系。 ## 常见问题 够你把一个模型在真实任务里认真试一轮：核对脚本、缓存读取、对账都能跑一遍。试完不满意，7 天内没用完的额度原路退回，所以门槛不等于试错成本。 余额扣完后，请求返回 HTTP 403，回包里是 `Insufficient user quota`（`/v1/messages` 上 `error.type` 为 `billing_error`，`/v1/chat/completions` 上为 `insufficient_quota`）。被拒绝的请求不扣费，充值到账后可以继续用。 通过 Claude Code 调用不附带额外内容。其他客户端（SDK、curl 和第三方工具）的每次请求会附带一段系统提示，按输入 token 计费：Sonnet 4.6 约 350 token，5.x 系列约 500 token。说明和实测数据见[系统提示的计费](/docs/pricing-explained/#系统提示的计费)。 退款规则是充值后 7 天内的未用额度。超过 7 天的情况请单独联系我们说明。 --- # 核对模型和用量 Source: https://1zheai.com/docs/verify-model/ Markdown: https://1zheai.com/docs/verify-model.md --- title: 核对模型和用量 description: 用调用日志和五项检查，核对每次调用的模型、token 用量和费用。 --- ## 调用日志 每次调用都记入控制台的[调用日志](/docs/usage-logs/)，列出模型，输入、输出、缓存读取和缓存写入的 token 用量，以及费用。 ## 五项检查 下面的检查对照 Anthropic 接口的公开格式，用于发现返回字段和格式上的差异。 | 检查 | 预期结果 | 需要留意 | |---|---|---| | 1. 返回的 `model` 字段 | 与请求的模型 ID 一致 | 返回其他模型名，或没有该字段 | | 2. 缓存读取 | 满足缓存条件的同一请求在缓存有效期内发送两次，第二次的 `cache_read_input_tokens` 大于 0 | 始终为 0，或 `usage` 中没有缓存字段 | | 3. 工具调用 ID | `tool_use` 块的 `id` 以 `toolu_` 开头 | 其他格式，或模型不按要求调用工具 | | 4. 流式事件顺序 | 依次出现 `message_start`、`content_block_start`、`content_block_delta`、`message_delta` 和 `message_stop` | 只有 OpenAI 格式的 `data:` 块，或事件缺失、顺序错乱 | | 5. 真实任务对照 | 用一道固定任务，与官方 API 或其他可信来源对比结果 | 结果明显变差、拒答异常或频繁截断 | 这些检查只能发现字段和格式上的差异，不能单独确认实际使用的模型。`model` 字段可以被改写，格式也可以被模仿。 ## 用脚本完成前四项 需要 `bash`、`curl` 和 `jq`。脚本会发起五次小调用，其中一次缓存写入约 1.8 万 token，按正常价格计费。 ```bash title="verify.sh" #!/usr/bin/env bash # 用法：ONEZHE_API_KEY=sk-你的API密钥 bash verify.sh [模型ID] set -euo pipefail BASE="https://1zheai.com" MODEL="${1:-claude-sonnet-5-5}" H=(-H "x-api-key: $ONEZHE_API_KEY" -H "anthropic-version: 2023-06-01" -H "content-type: application/json") echo "== 1. model 字段" curl -s "$BASE/v1/messages" "${H[@]}" \ -d "$(jq -n --arg m "$MODEL" '{model:$m,max_tokens:16,messages:[{role:"user",content:"ping"}]}')" \ | jq 'if .error then .error else {id, model, usage} end' echo "== 2. 缓存：同一请求发两次，看第二次的 cache_read_input_tokens" LONG=$(printf '这是一段用来测试缓存的固定文本，内容不重要，长度够就行。%.0s' {1..600}) BODY=$(jq -n --arg m "$MODEL" --arg t "$LONG" '{model:$m,max_tokens:16, system:[{type:"text",text:$t,cache_control:{type:"ephemeral"}}], messages:[{role:"user",content:"ping"}]}') for i in 1 2; do curl -s "$BASE/v1/messages" "${H[@]}" -d "$BODY" | jq -c 'if .error then .error else .usage end' done echo "== 3. 工具调用 ID" curl -s "$BASE/v1/messages" "${H[@]}" \ -d "$(jq -n --arg m "$MODEL" '{model:$m,max_tokens:256, tools:[{name:"get_weather",description:"查询城市天气", input_schema:{type:"object",properties:{city:{type:"string"}},required:["city"]}}], tool_choice:{type:"auto"}, messages:[{role:"user",content:"北京今天天气怎么样"}]}')" \ | jq -r 'if .error then .error.message else (.content[]? | select(.type=="tool_use") | .id) end' echo "== 4. 流式事件序列" curl -sN "$BASE/v1/messages" "${H[@]}" \ -d "$(jq -n --arg m "$MODEL" '{model:$m,max_tokens:32,stream:true,messages:[{role:"user",content:"数到三"}]}')" \ | grep '^event:' | uniq ``` 第 3 项用的是 `tool_choice: auto`。Sonnet 5.5 等 5.x 模型不支持强制指定工具（`{"type":"tool"}` 或 `{"type":"any"}`），会返回 400 `does not support forced tool_choice`。 2026-10-15 用 `claude-sonnet-5-5` 实测的输出如下（第 1 项只保留了关键字段）： ```text == 1. model 字段 { "id": "msg_011Cg3Esh8zeEdLeXAPVALKe", "model": "claude-sonnet-5-5", "usage": { "input_tokens": 518, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "output_tokens": 12, ... } } == 2. 缓存：同一请求发两次，看第二次的 cache_read_input_tokens {"input_tokens":23,"cache_creation_input_tokens":17920,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":17920,"ephemeral_1h_input_tokens":0},"output_tokens":4,"output_tokens_details":{"thinking_tokens":0},"service_tier":"standard","inference_geo":"global"} {"input_tokens":23,"cache_creation_input_tokens":0,"cache_read_input_tokens":17920,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":0},"output_tokens":4,"output_tokens_details":{"thinking_tokens":0},"service_tier":"standard","inference_geo":"global"} == 3. 工具调用 ID toolu_01UPsdyKX8M9fJTTkDoSKHXA == 4. 流式事件序列 event: message_start event: content_block_start event: ping event: content_block_delta event: content_block_stop event: message_delta event: message_stop ``` `ping` 事件是否出现、出现在哪个位置并不固定，不影响判断。 ## thinking 块 开启 thinking 后，返回的 `thinking` 块带 `signature` 字段，也可以作为一项格式检查。5.x 模型的写法和 4.x 不同，2026-10-15 实测： | 模型 | `thinking` 参数 | 结果 | |---|---|---| | `claude-sonnet-4-6` | `{"type":"enabled","budget_tokens":1024}` | 返回 `thinking` 块，有思考文本和 `signature` | | `claude-sonnet-5` | `{"type":"enabled","budget_tokens":1024}` 或 `{"type":"adaptive"}` | 都能用 | | `claude-sonnet-5-5` | `{"type":"adaptive"}` | 能用；传 `enabled` 返回 400，提示只支持 adaptive | 5.x 模型的 `thinking` 块默认只有 `signature`，思考文本为空字符串。需要看到思考摘要时，加上 `"display": "summarized"`： ```json "thinking": {"type": "adaptive", "display": "summarized"} ``` 使用第三方检测网站时，建议新建一个专用的 API 密钥，测完后删除。 ## 发现不一致时 发邮件至 support@1zheai.com，附上请求时间、模型 ID、完整的返回内容（删去 API 密钥）和对应的检查项。返回内容或错误信息中的 request id 可以帮助定位这次调用。 ## 常见问题 不可靠。模型的自我介绍受系统提示影响，在某些提示下会答错自己的版本。核对返回的字段和事件格式更有参考价值。 Claude Code 会用 Haiku 模型处理部分后台任务，调用日志里会出现对应的记录。可以用 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 环境变量指定这类任务使用的模型，见 [Claude Code 接入](/docs/quickstart-claude-code/)。不使用 Claude Code 时出现这种情况，请把请求时间发至 support@1zheai.com。 --- # 错误码与排错 Source: https://1zheai.com/docs/troubleshooting/ Markdown: https://1zheai.com/docs/troubleshooting.md --- title: 错误码与排错 description: 调用 1折AI 时遇到 401、404、429、529、5xx、超时和 Claude Code 报错时，原因和处理办法。 --- 先按顺序过一遍下面的清单，大多数问题在前三步就能找到。 ## 排查顺序 1. **地址**：Anthropic 系工具填 `https://1zheai.com`，OpenAI 系填 `https://1zheai.com/v1`。见 [Base URL 与鉴权](/docs/base-url/)。 2. **API 密钥（API key）**：是否完整（没有多余空格、换行）、是否已被删除、是否填进了正确的字段。 3. **余额**：控制台里余额是否充足。 4. **模型 ID**：是否和[支持的模型](/docs/models/)里的完全一致。 5. **网络**：关掉代理直连再试一次。 6. **还不行**：拿一条最小的 curl 复现（见下），把回包和时间发给我们。 ```bash title="最小复现" curl -i https://1zheai.com/v1/messages \ -H "x-api-key: sk-你的Key" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{"model":"claude-sonnet-5-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}' ``` `-i` 会把状态码和响应头一起打印出来，排查时很有用。 ## 错误码速查 | 状态码 | 常见原因 | 怎么办 | |---|---|---| | 400 | 请求体有问题：参数名错、字段类型错、`max_tokens` 超过模型上限、带了上游不认的 beta 字段 | 看 `message` 里指出的字段；Claude Code 的情况见下文"Extra inputs are not permitted" | | 401 | API 密钥无效、已删除、已禁用、已过期、自身额度用完，或没带、放错了请求头 | 回包都是 `Invalid token`，逐项检查；Anthropic 原生用 `x-api-key` 或 `Authorization: Bearer` | | 403 | 账户余额不足（`billing_error` / `insufficient_quota`）；这个 API 密钥没开通该模型；请求 IP 不在这个 API 密钥的白名单里（都是 `permission_error`） | 充值，或在「API 密钥」页编辑这个 API 密钥的模型限制和 IP 白名单 | | 404 | 路径不对，或模型不存在 / 当前不可用 | `Invalid URL` 核对地址；`not_found_error` / `model_not_found` 核对模型 ID 和可用列表 | | 413 | 请求体太大 | 减少一次发送的内容，大文件分段 | | 429 | 上游临时限流。目前我们不对 API 密钥设速率限制 | 稍后重试，批量任务加指数退避 | | 503 | 模型存在但暂时没有健康的上游服务，或服务临时故障 | 稍后重试；持续失败时提供请求 ID 联系支持 | | 500 / 502 | 网关或上游临时故障 | 稍后重试；持续出现发邮件到 support@1zheai.com | | 504 | 请求超时 | 长输出用流式；调大客户端超时 | | 529 | 上游 Anthropic 过载（`overloaded_error`） | 等几秒重试，或临时换一个模型 | Anthropic 官方错误类型（`invalid_request_error`、`authentication_error`、`rate_limit_error`、`overloaded_error` 等）的完整含义见[官方 Errors 文档](https://platform.claude.com/docs/en/api/errors)。 上游返回的错误，状态码和 `message` 原样带回，`message` 末尾加上本次请求的 request id。走 `/v1/messages` 时外层是官方的 `{"type":"error","error":{...}}` 结构，`error.type` 按状态码填官方类型；走 `/v1/chat/completions` 时是 OpenAI 的 `{"error":{...}}` 结构。 ## 实测回包 下面是 2026-10-15 对 `/v1/messages` 实测的真实回包。走 `/v1/chat/completions` 时内容相同，外层没有 `"type":"error"`，`error` 里多一个 `code` 字段。 ```json title="401 API 密钥无效、禁用、过期或额度用完" {"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"} ``` ```json title="403 账户余额不足" {"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"} ``` ```json title="403 API 密钥没开通该模型" {"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"} ``` ```json title="403 IP 不在白名单" {"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"} ``` ```json title="400 上游参数错误" {"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"} ``` ```json title="404 路径不存在" {"error":{"message":"Invalid URL (POST /v1/nonexistent)","type":"invalid_request_error","param":"","code":""}} ``` 模型不存在或不可用时的 404 说明见[支持的模型](/docs/models/)。回包里的 request id 对应你的这一次请求，反馈问题时带上它。 ## 按症状排查 ### 401 / Invalid token - API 密钥复制时多了空格或换行，重新复制一次。 - API 密钥已在控制台删除或禁用，或者已过期、自身额度已用完。这几种情况的回包都是同一句 `Invalid token`。 - Claude Code 里同时设置了 `ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN`，而其中一个是旧值：两个只留一个，推荐 `ANTHROPIC_AUTH_TOKEN`。 - `settings.json` 的 `env` 会覆盖终端里 export 的同名变量，改了终端变量不生效时，检查 `~/.claude/settings.json`。 ### 404 / Invalid URL 先看错误类型：`not_found_error` 或 `model_not_found` 要检查[模型 ID 与可用列表](/docs/models/)。`Invalid URL` 则检查 `/v1`：OpenAI SDK、Cursor、Cline（OpenAI Compatible）要填到 `https://1zheai.com/v1`；Claude Code 和 Anthropic SDK 只填 `https://1zheai.com`，填了 `/v1` 会变成 `/v1/v1/messages`。 ### 403 / error code: 1010 回包只有 `error code: 1010` 这一行、没有 JSON，说明请求在到达网关前被拦下了。目前已知用 Python 标准库 `urllib` 直接发请求会遇到（它默认的 User-Agent 是 `Python-urllib/3.x`）。在请求头里加一个自己的 `User-Agent`，或者改用官方 SDK、`requests`、`httpx`。 ### 429 太多请求 目前不对 API 密钥设速率限制。收到 429，通常是上游负载高，稍后重试即可。批量任务建议加指数退避：失败后等一段时间再试，每次等待时间翻倍，并自己用队列控制并发。 ### 529 / overloaded_error 上游 Anthropic 暂时过载，和你的 API 密钥、余额无关。等几秒重试；赶时间的话临时换到同系列的另一个模型。 ### 超时、流式中途断开 - 长回答尽量用流式（`"stream": true`），不容易被中间网络设备掐断。 - Claude Code 可以用 `API_TIMEOUT_MS` 调大超时，默认 600000（10 分钟）。 - 开着代理的话，先关代理试一次，很多断流来自代理节点。 ### Claude Code：直接进了登录界面 说明 Claude Code 没读到你的 API 密钥。在 Claude Code 里运行 `/status`，看 base URL 和凭据来源两行；为空就回到 [Claude Code 接入](/docs/quickstart-claude-code/)检查环境变量或 `settings.json`。 ### Claude Code：Extra inputs are not permitted / context_management 报 400 Claude Code 会在请求里带一些实验性的 beta 字段，严格的上游不认就会报 400。设置下面的环境变量关掉它们（来自 Claude Code 官方 LLM gateway 文档）： ```bash export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 ``` ### 余额充足但调用失败 - 如果只有某个模型失败，可能是该模型暂时不可用、ID 写错，或者这个 API 密钥设了模型限制（403 `This token has no access to model …`）。 - 如果全部失败且是 401，看看这个 API 密钥是不是设了额度上限并且已经用完，或者已经过期。在「API 密钥」页的「额度 ($)」和「过期」两列能看到。 - 其它情况看上面的错误码表。 ## 还是没解决 发邮件到 support@1zheai.com，附上时间、模型 ID、你用的工具和版本、`curl -i` 的完整输出（删掉 API 密钥）。 --- # AI 与自动化 Source: https://1zheai.com/docs/ai/ Markdown: https://1zheai.com/docs/ai.md --- title: AI 与自动化 description: 让 AI 助手按需读取文档，了解现有机器读取入口和文档 MCP 的状态。 --- 你可以让 AI 助手先读取本站文档，再协助配置工具或编写调用代码。普通文档阅读与模型 API 调用是两件事：读取公开文档不需要提供 API 密钥。 ## 可用的机器读取入口 | 入口 | 用途 | | --- | --- | | [llms.txt](/docs/llms.txt) | 按栏目发现文档，选择需要读取的页面 | | [文档清单](/docs/docs-manifest.json) | 获取页面标题、所属栏目、网页与 Markdown 地址 | | [完整文档文本](/docs/llms-full.txt) | 一次读取全部页面；内容较长，优先按页读取 | | [首页 Markdown](/docs/index.md) | 阅读不含站点导航的源文档内容 | 每篇文章都有对应的 Markdown 地址，例如 `/docs/quickstart-claude-code/` 对应 `/docs/quickstart-claude-code.md`。也可以使用页面顶部的“复制本页”。Markdown 中可能保留卡片等文档组件标记。 ## 交给 AI 的接入任务 复制任务说明，让助手先查支持范围，再配置并验证。 按工具选择协议、地址和模型配置。 ## 文档 MCP 状态 本站目前尚未提供可连接的文档 MCP 服务端。请先使用上面的文档地址，或将页面内容复制给助手；不要把模型 API 的 Base URL 当作 MCP 地址。 文档 MCP 的用途是搜索与读取公开资料。账户查询、密钥管理等操作属于另一类能力，不能由公开文档入口获得。 --- # 让 AI 帮你接入 Source: https://1zheai.com/docs/agent-workflow/ Markdown: https://1zheai.com/docs/agent-workflow.md --- title: 让 AI 帮你接入 description: 可复制的接入任务说明，帮助 AI 先读取资料、核对限制，再完成配置与验证。 --- ## 复制任务说明 把下面的说明交给能够读取网页的 AI 助手，并补充工具名称与操作系统。如果助手无法联网，先通过[机器读取入口](/docs/ai/)获取对应文章内容。 ```text 请帮助我将现有工具或应用接入 1折AI。 目标工具与版本：[填写] 操作系统或编程语言：[填写] 先读取 https://1zheai.com/docs/llms.txt，找到目标工具或 SDK 的文档。 再读取该页 Markdown，以及 API 参考和模型说明。 要求： 1. 先说明当前支持范围和工具配置要求。 2. 根据目标工具确定 Base URL，不要统一添加或删除 /v1。 3. 模型 ID 以当前文档和密钥可用模型列表为准，不要猜测。 4. 查看现有配置，只修改必要字段，保留其他供应商配置。 5. 使用环境变量或工具提供的凭据存储方式；不要把密钥写入源码、 对话、日志或提交记录。需要密钥时，让我在本地安全配置。 6. 执行会产生费用的测试前，说明测试内容并取得我的同意。 7. 用一次最小请求验证，再提示我在调用日志里核对记录。 8. 如果验证失败，保留脱敏的状态码与请求 ID，按排错文档处理； 不要用反复重试掩盖配置问题。 9. 最后说明修改位置、验证结果、剩余限制及恢复原配置的方法。 ``` ## 判断是否完成 完成配置不等于完成接入。应同时确认工具返回正常、实际使用的模型符合预期，并且能在[调用日志](/docs/usage-logs/)找到对应记录。 本页是可复制的任务说明，并非已安装的 Agent Skill 或 MCP 服务。任何助手仍需要具备读取文档和操作本地配置的相应能力。 ---