Docs / Quickstart

Claude API 接入文档与 Claude Code 国内使用教程

本站提供 Anthropic Messages 形态的 API，网关国内直连，不用代理。用 Claude Code 的话，直接看 Claude Code 国内使用一节。下文用 <你的网关地址> 表示网关基址（含协议和域名），请替换为实际地址。

网关地址：。下文示例已经填好这个地址。

• 快速开始
• 鉴权
• 接口
• 模型别名
• 请求字段
• 图片和文档
• 错误
• 控制台接口
• 并发与速率
• 计费规则
• Key 撤销
• 待核算
• 数据记录
• Claude Code
• 客户端兼容

快速开始

1. 在控制台开通套餐或充值，然后创建 API Key。完整 Key 只在创建时显示一次，请当场保存。
2. 查询当前 Key 可用的模型版本。
3. 发起调用，model 填上一步返回的版本 ID。

curl <你的网关地址>/v1/models \
  -H "x-api-key: $API_KEY"

curl -N <你的网关地址>/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "<模型版本 ID>",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{ "role": "user", "content": "你好" }]
  }'

stream 为 true 时返回 SSE 事件流，正常结束的最后一个事件是 message_stop；去掉 stream 则返回一次性 JSON。max_tokens 必填。

个别上游在带 stop_reason 的最终 message_delta 之后直接结束连接，没有发出完整的 message_stop。这时内容和用量都已完整，网关按正常完成结算，不发错误事件，也不会替上游补写 message_stop，请以最终 message_delta 判断生成已结束。

流里的注释行统一写成 : keepalive，只保留保活的节奏；上游的 id:、retry: 字段不转发。协议之外的新事件照常转发，其中的地址、凭证形态的内容会替换为 [已隐藏]。

请求体不能压缩：带 identity 以外的 Content-Encoding 返回 400 unsupported_content_encoding，请求不会发往上游。

每个响应都带 request-id 响应头。遇到问题时，用这个编号可以在控制台定位到对应的请求。

anthropic-version 未传时按 2023-06-01 处理，不在通道允许清单内的版本返回 400。

鉴权

• x-api-key 和 Authorization: Bearer 都可以传 API Key，任选其一。
• 两者同时存在且不一致时返回 400 credential_conflict，绝不随机挑选其中一个。
• Authorization 只支持 Bearer 方案；带了 x-api-key 时，别的方案（比如前置代理加的 Basic）不读取。Key 缺失、无效、已过期、已停用或已撤销都返回 401 invalid_api_key。
• 鉴权失败次数过多时，来源 IP 会被短暂限制，返回 429 auth_abuse。
• API Key 只能调用模型接口，不能操作充值、退款或用户管理。

接口

模型别名

model 除了版本 ID，也可以填稳定别名。别名当前指向哪个版本、最近一次切换的通知，公开在首页价目表（接口是 GET /api/public/models 的 aliases）。

• 请求在接受时解析成明确的版本，计费和请求明细都按解析后的版本记录。
• 切换别名指向的版本必须发布通知，已经在途的请求不受影响。需要版本固定不变时，请直接填版本 ID。
• Key 的模型白名单只接受版本 ID，不接受别名，创建时填别名返回 400 bad_model_allowlist。

请求字段

支持的顶层字段：model、messages、max_tokens、system、metadata、stop_sequences、stream、temperature、top_k、top_p、tools、tool_choice、thinking、output_config、cache_control、context_management。

• context_management.edits 只接受 clear_thinking 和 clear_tool_uses 两类编辑（如 clear_thinking_20251015、clear_tool_uses_20250919）。上下文压缩（compact_ 开头）等会额外调用模型的编辑无法计费，返回 400 invalid_context_management。
• messages 里可以有 role 为 system 的消息，它的文本和其他消息一样算输入。这类消息还可以带 output_config.effort，内容里可以用 tool_addition、tool_removal 按名字启用或撤下 tools 里已声明的工具。

其他字段一律返回明确的 400（capability_mismatch），不会被默默丢弃。包括：

• 会改变计费或模型的字段：fallbacks、speed、service_tier、inference_geo、mcp_servers。
• 有按次附加费的服务端工具：tools 里的 web_search、code_execution 等类型。这类费用没有计费模型，无法冻结也无法结算，一律拒绝，任何通道配置都不能开放。其他工具类型按通道清单放行。

同样在发往上游前返回 400 的还有：max_tokens 超过模型上限（max_tokens_exceeded）、不支持的内容来源（见下一节）、模型或通道不支持的能力。支持范围按模型和通道维护。

图片和文档

base64 PDF 按页数冻结。网关从 PDF 的结构里读出页数，输入上限按每页 12000 Token 加上请求里其余内容的估算，再加 max_tokens 计算费用上限，不超过模型的上下文窗口。页数读不出来时（加密、结构损坏、页树放在压缩的对象流里、页数前后矛盾），以及其它 base64 文档，费用上限按该模型的完整上下文窗口加 max_tokens 计算，单价档也按这个窗口选取。可用额度覆盖不了这个上限时返回 402，文件再小也一样；这时可以降低 max_tokens、改用 text 类型，或补足额度。结算按实际用量，差额全部释放；实际费用超过冻结时，在资金来源和 Key 预算允许的范围内补扣。

图片数量超限返回 413 too_many_images，单个媒体内容超限返回 413 media_too_large。

错误

错误体结构兼容 Anthropic 错误格式，并带 request_id。error.code 是本服务的扩展字段，用来区分具体原因。下面是一个示例：

{
  "type": "error",
  "error": {
    "type": "billing_error",
    "code": "subscription_insufficient",
    "message": "本次请求费用上限 ¥X，套餐剩余 ¥Y，未开启超额使用钱包。可降低 max_tokens，或在控制台开启超额使用。"
  },
  "request_id": "req_示例"
}

402 和平台业务原因属于本服务扩展，并不声称全部是 Anthropic 原生契约。

• entry_limit（429）：同一账户同时处在入口阶段（鉴权、读取账户和请求体）的请求太多。和 RPM、TPM、并发是不同的限制，请按 Retry-After 稍后重试。
• body_read_limit（429）：同一账户同时上传中的请求太多，请等前面的请求传完再发。
• account_suspended（403）：账户已暂停，所有模型请求都被拒绝，重试没有意义，请联系支持。在途请求允许收尾并正常结算。

504 表示请求可能已被上游接受：网关不会自动重复生成，用量进入核算。自行重发前请先按 request_id 查看这次请求，重发是一次新请求。

请求已经发到上游、结果不明（用量进入核算）的错误响应带 x-should-retry: false，官方 SDK 据此不会自动重试，例如 first_response_timeout、total_timeout、connection_unknown、upstream_timeout。connect_timeout 和 no_available_upstream 表示请求没有被上游接受，不带这个头，可以重试。上游返回普通 500、503 并给出 Retry-After 时，upstream_error 响应会带上它，最多 60 秒。

HTTP 响应头发出后不能再改状态码。流式响应中途出错时，错误以 SSE error 事件给出，结构相同，并且不会出现 message_stop：

event: error
data: {"type":"error","error":{"type":"api_error","code":"stream_interrupted","message":"上游流中断，响应未完整。可用请求编号查询本次用量。"},"request_id":"req_示例"}

控制台接口

控制台使用的 /api/ 接口用登录会话鉴权，不接受 API Key。错误体和模型接口不同，结构是 {"error":{"code":"…","message":"…"}}。写操作的请求体里不能含 \u0000，否则返回 400 bad_json。

并发与速率

各档套餐的上限见首页套餐区，未订阅的按量账户使用单独的基础档。

• 并发、RPM、TPM 三个约束同时生效，还可以在项目和 Key 上进一步收紧，并受上游通道和平台容量限制。拆分 Key 不增加账户总容量。
• 超限返回 429 和 Retry-After，error.code 说明触发的是哪一项。超限请求可能短暂排队，排队有上限，这不是响应时延承诺。
• 流式请求从开始到结束或取消，一直占用一个并发名额。
• TPM 准入时按输入估算加输出预留放行，输出预留取 max_tokens 和 32000 中较小的一个，结束后按实际用量校正：实际输出超过预留的部分在结束时计入（中途断开的请求按已收到的内容计入），之后的请求相应等待（429 tpm_limit，按 Retry-After 重试）。资金冻结仍按完整的 max_tokens（见计费规则）。
• RPM 和 TPM 使用令牌桶，容量等于每分钟额度。空闲之后可以一次性突发到这个容量，之后按每分钟额度匀速恢复，并非按自然分钟清零。

计费规则

1. 支付验证且权益发放成功后开始周期。套餐金额和单价版本在订单中快照保存。
2. 当期 API 额度 30 天有效，到期不结转、不提现。
3. 扣款顺序：有效套餐、最早到期的赠送额度、本金。有效套餐先扣，只有用户主动开启超额使用钱包，才在套餐不足后继续扣有效赠送额度与本金。
4. 套餐已到期与从未订阅的按量用户状态分开：已到期且未允许钱包继续消费时暂停收费请求，避免静默切换扣款方式。此时返回 402 subscription_expired；从未订阅的按量账户直接使用赠送额度与本金。
5. 自动续费默认关闭；已授权的站内续费仅从钱包本金扣款，不能用赠送或套餐额度再次购买订阅。
6. 关闭续费不取消当期权益。首期升降级安排在下一周期；一个账户同一时刻只有一个生效套餐。
7. 消费金额精确记录，界面按需要显示四至六位小数。避免小请求逐笔四舍五入到「分」。

每个请求先冻结费用上限，结束时按接受时固定的价格版本分项结算，差额释放。费用上限超过可用额度时返回 402，不会先扣一部分再失败，可以降低 max_tokens 后重试。base64 PDF 按页数冻结，读不出页数的按完整上下文窗口冻结，见图片和文档。

模型在输出任何内容之前拒答（stop_reason 为 refusal、没有内容块）时，按上游的规则计费：类别（stop_details.category）为 bio、frontier_llm、reasoning_extraction 的照常按用量计费，其它类别和没有类别的不收费，冻结全部释放，请求明细的关闭原因显示「模型在输出任何内容之前拒答」。已经输出了内容之后才拒答的，按实际用量计费。

带缓存标记的请求会多一小段输入。请求里任何位置带 cache_control 时，网关在 system 最前面加一个按账户固定的文本块：cache-scope: 加 16 位十六进制数，共 29 个字符。上游的提示词缓存按前缀内容共用，加了这段之后每个账户的前缀都不一样，别的账户无法从缓存命中情况得知你发过什么；你自己的前缀不变，缓存照常命中。这段文本和其它输入一样计费，按每 2 到 4 字节 1 个 Token 估算约 8 到 15 个 Token，确切数量以上游报告、请求明细里显示的用量为准。count_tokens 的结果不包含这段文本，所以带缓存标记的请求实际计费的输入会比计数结果多这几个 Token。没有缓存标记的请求不加任何内容。

Key 撤销

Key 撤销后，新请求立即被拦截，返回 401。已经在途的请求允许收尾并正常结算，已产生的费用不因撤销而免计。

待核算（usage_pending）

请求已发送或已开始输出，却拿不到可靠用量时，账务进入 usage_pending，冻结保留，并尝试核对用量。

• 1 小时未解决，触发告警。
• 24 小时仍无可靠用量证据时关闭：只按已被上游证实的字段计费，未证实部分释放；一个字段都未证实则全额释放。成本差异由平台承担。
• 已经交付给客户端的内容不因拿不到最终用量而免计：输出按已交付内容的下限计费。流式请求在思考阶段取消的（包括 thinking.display 为 omitted、思考内容不下发的情况），上游照样按思考 Token 收费，思考时长按每秒 10 Token 计入输出下限，不含断开后的等待。输出下限不超过 max_tokens。
• 客户端取消的流式请求，如果上游已经报出完整的提示词用量，待核算期间的冻结收缩到已报告的提示词费用，加上取消前可能产生的输出。之后核对到的用量更大时，超出冻结的部分在资金来源和 Key 预算允许的范围内补扣。

待核算不会无限期冻结额度。

数据记录

默认记录脱敏元数据（请求编号、模型、状态、用量、金额、时间和来源 IP），不记录提示词和生成正文。

Claude Code 国内使用（中转站配置）

在国内使用 Claude Code（常简称 cc）不用代理，命令行客户端可以直接接入本站这个 Claude Code 中转站。设置两个环境变量后照常启动：

export ANTHROPIC_BASE_URL=<你的网关地址>
export ANTHROPIC_API_KEY=<控制台创建的 API Key>
claude

Windows PowerShell 写作 $env:ANTHROPIC_BASE_URL="…" 和 $env:ANTHROPIC_API_KEY="…"。

• ANTHROPIC_BASE_URL 填网关基址，不带 /v1。ANTHROPIC_API_KEY 填本平台的 API Key，不是 Anthropic 官方的 Key。不要同时设置 ANTHROPIC_AUTH_TOKEN：两个凭证不一致时返回 400 credential_conflict。
• 它发出的模型 ID 是 claude-opus-5-5 和 claude-sonnet-5-5，Key 设了模型白名单时要包含它们。选择 sonnet[1m] 这类带 [1m] 的模型时，按基础模型（如 claude-sonnet-5-5）调用和计费，不提供 100 万 Token 的长上下文，提示词上限按通道配置。
• 联网搜索不可用：服务端的 web_search 工具按次另收费用，无法计费，带这个工具的请求返回 400，说明写着「本平台不支持联网搜索」。读写文件、运行命令等在本机执行的工具不受影响。
• Claude Code 每个请求的 max_tokens 都是 128000，而每个请求都按 max_tokens 冻结费用上限：冻结金额是 128000 × 输出单价，加上输入估算 × 输入单价（带缓存标记时按写缓存单价），单价见首页价目表。这笔钱在请求结算前不能用于别的请求，同时进行的请求越多，冻结越多；结算后按实际用量扣费，差额释放。可用额度覆盖不了时返回 402。
• TPM 准入的输出预留最多 32000（不是 128000），结束后按实际用量校正，所以一个会话的连续请求通常可以直接放行。TPM 按实际用量计：Plus 和按量基础档每分钟 10 万，长时间的会话、并行的子代理或单次输出很长时，累计用量超过这个速率仍会收到 429 tpm_limit，客户端会按 Retry-After 等待后重试。
• 用 Claude Code 的环境变量 CLAUDE_CODE_MAX_OUTPUT_TOKENS 调低每次的最大输出，可以减少冻结金额；它小于 32000 时也会减少 TPM 预留。
• 它带的 anthropic-beta（见下一节）默认放行，原样转发给上游。会话编号、客户端版本、x-stainless-* 等其他请求头不转发；上游收到的 Key 是平台的渠道凭证，不是你的 API Key。

客户端兼容

已经测试并声明支持的客户端是 Claude Code（见上一节）。其他 CLI 客户端在声明之前，请不要假定它的全部功能都可用。

默认放行的 anthropic-beta：claude-code-20250219、interleaved-thinking-2025-05-14、context-management-2025-06-27、per-turn-control-2026-07-01、mid-conversation-tool-changes-2026-07-01、thinking-token-count-2026-05-13、advanced-tool-use-2025-11-20、effort-2025-11-24。其他不在通道允许清单内的值返回 400。查询参数只接受 beta=true，原样转发给上游；其他查询参数同样返回 400。