余额 $1.00
总览/接入文档/3 步接入

3 步开始调用 Claude

完全兼容 Anthropic 官方 API 协议。已经在用 anthropic SDK?把 baseURL 换成我们的端点就行 — 代码一行不改。

POSThttps://cldapi.com/v1/messages

概述

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 anthropic

2. 替换 baseURL 和 API Key

只改两处:base_url 指向 cldapi.comapi_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 就能在官方和中转之间切换。

i
建议把 API Key 放到环境变量里。 比如 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
claude
i
如果之前用官方 key 登录过,先 claude /logout 再设置环境变量。Windows 下 cmd.exeset / 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 ProviderAnthropic
Anthropic API Keysk-cr-xxxxxxxxxxxxxx
勾选 "Use custom base URL"https://cldapi.com
Modelclaude-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-6

RoRoo 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

!
Cursor 和 Windsurf 作为闭源 AI 编辑器,大部分功能(Tab 补全、Composer Agent)走官方专有通道,无法切换到第三方 API。只有 Chat 面板里 "Override" 出的 OpenAI 兼容端点能走外部——这意味着你用它俩的 Claude 体验依然会是"被阉割版"。如果你在意纯血 Claude Agent 体验,推荐用上面的 Claude Code / OpenCode / Cline。

Messages API

所有对话请求都打到 POST /v1/messages。下面是常用字段速查;完整定义和官方一致。

字段类型说明
modelstring 必填模型 ID,如 claude-sonnet-4-6。完整列表见模型列表
messagesarray 必填对话历史,每条 {role, content}roleuser / assistant,必须以 user 开头、交替出现。
max_tokensinteger 必填本次回复最多生成多少 token。Sonnet/Opus 上限 8192,Haiku 上限 4096。
systemstring · array系统提示,可选。要使用 Prompt Caching 时传数组形式 [{type:"text", text:"...", cache_control:{type:"ephemeral"}}]
temperaturenumber 默认 1.0采样温度 0–1。代码生成、事实问答建议 0–0.3,创作类 0.7–1。
top_p / top_knumber / integer核采样和截断采样,二选一,一般保持默认。
streamboolean 默认 false是否启用 SSE 流式返回。详见 流式输出
stop_sequencesarray<string>遇到这些字符串就停止生成。
toolsarray工具定义。详见 Tool Use

响应里几个高频字段:

字段说明
content数组,每个元素 {type, text}{type:"tool_use", ...}
stop_reasonend_turn / max_tokens / stop_sequence / tool_use
usageinput_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},
            ]},
        ],
    )
i
循环约定。stop_reasontool_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.6Opus 4.7Haiku 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 / min1,000所有模型合计每分钟请求数
ITPM input tokens / min2,000,000每分钟累计输入 token
OTPM output tokens / min400,000每分钟累计输出 token
并发 in-flight50同时进行中的请求数
i
需要更高限额?在 设置页面提交工单,企业认证后可申请到 10× 默认值。建议在客户端实现 令牌桶 + 指数退避,能把命中 429 的概率降到接近 0。

常见错误

HTTP错误类型原因
401authentication_errorAPI Key 无效或已禁用
402insufficient_balance账户余额不足,请充值
429rate_limit_error超过并发或 RPM 限制
529overloaded_error上游繁忙,请重试(已自动重试 3 次)
!
建议在客户端对 429529 加指数退避重试(最多 3 次,基数 1s)。