3 步开始调用 Claude
完全兼容 Anthropic 官方 API 协议。已经在用 anthropic SDK?把 baseURL 换成我们的端点就行 — 代码一行不改。
概述
Claude Relay 是一个 纯血直连 的 Claude API 中转服务 —— 我们把你的请求原样转发给 Anthropic 官方端点,再把响应原样吐回来。不是反代、不做提示注入、不做模型替换,所有协议字段(包括 stream 事件、tool_use、cache_control)都 1:1 透传。
- 协议完全一致 · 官方 SDK / curl / 任何语言的 HTTP 客户端都能用,
baseURL一换即可 - 计费 1:1 · 按官方公开价格透传,查看模型广场
- 额外功能 · 多 Key 管理、用量看板、限流告警、团队子账号、按 Key 维度统计
下面这页面会带你 3 步接入(< 5 分钟),然后说明几个常用进阶能力(流式、工具调用、视觉输入、Prompt Caching)。如果你赶时间,直接跳到下一节。
3 步接入
把官方 baseURL 替换成我们的端点,其余保持不变。下面是主流语言的最小可运行示例。
1. 安装 SDK(如果还没装)
cURL 系统自带可跳过这步;Python 和 Node.js 选你常用的语言装一个就行。
pip install anthropic2. 替换 baseURL 和 API Key
只改两处:base_url 指向 cldapi.com,api_key 使用你在 密钥管理 里创建的 sk-cr- 开头的密钥。
from anthropic import Anthropic
client = Anthropic(
base_url="https://cldapi.com", # ← 改这里
api_key="sk-cr-xxxxxxxxxxxxxx",
)
msg = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
messages=[{"role": "user",
"content": "Hello, Claude"}],
)
print(msg.content[0].text)3. 运行 — 就这样
响应和官方完全一致。同一份代码只要改 baseURL 就能在官方和中转之间切换。
export CLAUDE_RELAY_KEY=sk-cr-...,然后 api_key=os.environ["CLAUDE_RELAY_KEY"]。不要写死在代码里。认证
和官方一样通过 HTTP Header 认证。SDK 会自动带上;直接调 HTTP 的话需要设置 x-api-key:
x-api-key: sk-cr-xxxxxxxxxxxxxx anthropic-version: 2023-06-01 content-type: application/json
主流 AI Agent 接入
Claude 生态下的开发工具绝大多数都支持自定义 baseURL,下面是 2025–2026 年主流工具的接入方式,任选一个即可开工。
CCClaude Code官方 · 最推荐
Anthropic 2025 年推出的官方终端 Agent。通过两个环境变量指向我们的端点即可;ANTHROPIC_AUTH_TOKEN 优先级高于 ANTHROPIC_API_KEY,第三方中转统一用前者更稳。
# 1. 安装(需要 Node.js 18+)
npm install -g @anthropic-ai/claude-code
# 2. 在 ~/.zshrc 或 ~/.bashrc 追加(永久生效)
export ANTHROPIC_BASE_URL="https://cldapi.com"
export ANTHROPIC_AUTH_TOKEN="sk-cr-xxxxxxxxxxxxxx"
# 3. source 后在任意项目目录跑
source ~/.zshrc
claudeclaude /logout 再设置环境变量。Windows 下 cmd.exe 用 set / setx,推荐直接上 PowerShell。OCOpenCode
开源社区最受欢迎的 Claude Code 平替,支持 100+ 模型,配置文件同时提供全局(~/.config/opencode/opencode.json)和项目级(opencode.json)两种方式。
// macOS / Linux: ~/.config/opencode/opencode.json
// Windows: %APPDATA%\opencode\opencode.json
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"options": {
"baseURL": "https://cldapi.com/v1",
"apiKey": "sk-cr-xxxxxxxxxxxxxx"
}
}
}
}ClClineVS Code · Plan & Act 模式
VS Code 里最早做 Agent 的插件之一。VS Code 本身跨平台,所以 macOS / Linux / Windows 配置完全相同 —— 装好插件后打开设置面板,按下表填写即可。Roo Code 配置位置一模一样。
| 字段 | 填写 |
|---|---|
| API Provider | Anthropic |
| Anthropic API Key | sk-cr-xxxxxxxxxxxxxx |
| 勾选 "Use custom base URL" | https://cldapi.com |
| Model | claude-sonnet-4-6 (性价比首选) |
CoContinue
VS Code 和 JetBrains 通用的开源 AI 助手。编辑配置文件加一个 anthropic provider(macOS / Linux:~/.continue/config.yaml;Windows:%USERPROFILE%\.continue\config.yaml):
# macOS / Linux: ~/.continue/config.yaml
# Windows: %USERPROFILE%\.continue\config.yaml
models:
- name: Claude Sonnet 4.6 via Relay
provider: anthropic
model: claude-sonnet-4-6
apiBase: https://cldapi.com
apiKey: sk-cr-xxxxxxxxxxxxxx
roles: [chat, edit, apply]AiAider
终端里和 Git 深度集成的结对工具,适合重构和多文件修改。Aider 通过 LiteLLM 调用 Anthropic,所以用 ANTHROPIC_API_BASE 覆盖端点:
export ANTHROPIC_API_BASE="https://cldapi.com"
export ANTHROPIC_API_KEY="sk-cr-xxxxxxxxxxxxxx"
# 在你的项目目录跑
aider --model anthropic/claude-sonnet-4-6RoRoo Code
从 Cline fork 出来的增强版,支持 Code / Architect / Ask / Debug 四种模式。配置界面和 Cline 完全一样,参考上面 Cline 的表格即可。
ZZed
Atom 原作者打造的 Rust 编辑器,2025 年内建了 Agent Panel。Zed 目前仅支持 macOS 与 Linux,Windows 版仍在预览中;在 ~/.config/zed/settings.json 里配置:
{
"language_models": {
"anthropic": {
"api_url": "https://cldapi.com"
}
},
"assistant": {
"default_model": {
"provider": "anthropic",
"model": "claude-sonnet-4-6"
}
}
}API Key 通过 zed: open keymap 命令的 UI 面板填入,不要写到 settings.json 里。
CuCursor / Windsurf
Messages API
所有对话请求都打到 POST /v1/messages。下面是常用字段速查;完整定义和官方一致。
| 字段 | 类型 | 说明 |
|---|---|---|
model | string 必填 | 模型 ID,如 claude-sonnet-4-6。完整列表见模型列表。 |
messages | array 必填 | 对话历史,每条 {role, content}。role ∈ user / assistant,必须以 user 开头、交替出现。 |
max_tokens | integer 必填 | 本次回复最多生成多少 token。Sonnet/Opus 上限 8192,Haiku 上限 4096。 |
system | string · array | 系统提示,可选。要使用 Prompt Caching 时传数组形式 [{type:"text", text:"...", cache_control:{type:"ephemeral"}}]。 |
temperature | number 默认 1.0 | 采样温度 0–1。代码生成、事实问答建议 0–0.3,创作类 0.7–1。 |
top_p / top_k | number / integer | 核采样和截断采样,二选一,一般保持默认。 |
stream | boolean 默认 false | 是否启用 SSE 流式返回。详见 流式输出。 |
stop_sequences | array<string> | 遇到这些字符串就停止生成。 |
tools | array | 工具定义。详见 Tool Use。 |
响应里几个高频字段:
| 字段 | 说明 |
|---|---|
content | 数组,每个元素 {type, text} 或 {type:"tool_use", ...}。 |
stop_reason | end_turn / max_tokens / stop_sequence / tool_use。 |
usage | input_tokens / output_tokens / cache_read_input_tokens / cache_creation_input_tokens — 用于核账。 |
流式输出
加一个 stream=True 即可,事件流格式与官方 SSE 一致:
with client.messages.stream(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[{"role": "user", "content": "写一首关于咖啡的俳句"}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)Tool Use(函数调用)
给模型一组"工具",让它在需要时返回 tool_use 块——你执行后把结果以 tool_result 塞回 messages 即可。整个协议和官方完全一致。
tools = [{
"name": "get_weather",
"description": "获取指定城市的当前天气",
"input_schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
}]
resp = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "上海现在多少度?"}],
)
# 如果 stop_reason == "tool_use",执行工具,把结果塞回去再调一次
if resp.stop_reason == "tool_use":
tu = next(b for b in resp.content if b.type == "tool_use")
result = my_get_weather(**tu.input)
resp = client.messages.create(
model="claude-sonnet-4-6", max_tokens=1024, tools=tools,
messages=[
{"role": "user", "content": "上海现在多少度?"},
{"role": "assistant", "content": resp.content},
{"role": "user", "content": [
{"type": "tool_result", "tool_use_id": tu.id, "content": result},
]},
],
)stop_reason 为 tool_use 时进入工具循环;执行完所有工具调用后再次发送 messages 直到收到 end_turn。SDK 提供了 messages.tool_runner 帮你封装这个循环。视觉输入
把图片以 image block 嵌入 message 即可,支持 base64 和公网 url 两种来源。所有 Claude 4.x 系列都默认开启视觉能力,无需额外开关。
import base64, httpx
img = base64.standard_b64encode(httpx.get("https://example.com/diagram.png").content).decode()
resp = client.messages.create(
model="claude-sonnet-4-6", max_tokens=1024,
messages=[{"role": "user", "content": [
{"type": "image", "source": {
"type": "base64",
"media_type": "image/png",
"data": img,
}},
{"type": "text", "text": "用三句话概括这张图"},
]}],
)单张图最大 5 MB,长边自动缩放到 1568 px;超过会按 token 算成 ~1600 输入 token。多图混排没问题,但单次请求最多 100 张。
Prompt Caching
把长 system prompt 或固定上下文打上 cache_control 标记,下次命中时输入费用降到 10%,缓存写入额外加 25%(一次性)。我们原样透传,不收任何上浮费用。
resp = client.messages.create(
model="claude-sonnet-4-6", max_tokens=1024,
system=[
{"type": "text", "text": "你是一个资深 Rust 编译器开发者..."},
{ # 长文档作为可缓存上下文
"type": "text",
"text": long_codebase,
"cache_control": {"type": "ephemeral"},
},
],
messages=[{"role": "user", "content": "为什么我这段 lifetime 推断不通过?"}],
)
# 检查命中:
print(resp.usage.cache_read_input_tokens, resp.usage.cache_creation_input_tokens)| 价格档 | Sonnet 4.6 | Opus 4.7 | Haiku 4.5 |
|---|---|---|---|
| 普通输入 / 1M | $3.00 | $15.00 | $1.00 |
| 缓存写入 / 1M +25% | $3.75 | $18.75 | $1.25 |
| 缓存命中 / 1M 10% | $0.30 | $1.50 | $0.10 |
缓存最少 1024 token 才会生效,TTL 5 分钟(每次命中续期)。最多打 4 个 cache_control 断点。
模型列表
和官方完全同步,发布 24 小时内上线。
| 模型 ID | 上下文 | 输入 / 1M | 输出 / 1M |
|---|---|---|---|
claude-opus-4-7最强推理与创作 | 200K | $15.00 | $75.00 |
claude-sonnet-4-6性价比主力 · 支持 1M 上下文 (beta) | 200K · 1M (beta) | $3.00 >200K: $6.00 | $15.00 >200K: $22.50 |
claude-haiku-4-5轻量级 · 高并发 | 200K | $1.00 | $5.00 |
限流
每个 API Key 默认共享账户级限额;可以在密钥管理页面给单 Key 单独设置上限。超过会返回 429,Header 里会带 retry-after。
| 维度 | 默认 | 说明 |
|---|---|---|
| RPM requests / min | 1,000 | 所有模型合计每分钟请求数 |
| ITPM input tokens / min | 2,000,000 | 每分钟累计输入 token |
| OTPM output tokens / min | 400,000 | 每分钟累计输出 token |
| 并发 in-flight | 50 | 同时进行中的请求数 |
常见错误
| HTTP | 错误类型 | 原因 |
|---|---|---|
401 | authentication_error | API Key 无效或已禁用 |
402 | insufficient_balance | 账户余额不足,请充值 |
429 | rate_limit_error | 超过并发或 RPM 限制 |
529 | overloaded_error | 上游繁忙,请重试(已自动重试 3 次) |
429 和 529 加指数退避重试(最多 3 次,基数 1s)。