Python / TypeScript SDK

HyperAI Relay 对官方 Anthropic SDK 完全兼容,接入只需要改 base_url 和 api_key 两个参数,其余一行代码都不用动。原因很简单:我们是透明代理,不做签名改写、不裁剪 payload、不替换 model 名。

为什么推荐用官方 SDK

  • 追新最快:Anthropic 发布新特性当天,SDK 更新后我们这里就能用(prompt caching、extended thinking、memory tool 等都是这个逻辑)
  • 重试 / 限流 / 流式 全部开箱即用
  • 类型提示完备(Python 和 TypeScript 都有官方类型)
  • 出了问题,先用官方 SDK 排查;如果是我们的 relay 问题,错误栈会很清楚

Python

安装官方 SDK:

pip install anthropic
# 或 uv add anthropic

最小可用示例:

from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.hyper-ailab.com",
    api_key="sk-relay-xxx",  # 在 /app/keys 生成
)

msg = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "用一句话解释什么是透明代理"}],
)
print(msg.content[0].text)

或者用环境变量(推荐,避免把 key 硬编码进代码仓库):

export ANTHROPIC_BASE_URL="https://api.hyper-ailab.com"
export ANTHROPIC_API_KEY="sk-relay-xxx"

然后代码里直接:

from anthropic import Anthropic
client = Anthropic()   # 自动读环境变量

TypeScript / JavaScript

安装:

npm install @anthropic-ai/sdk
# 或 pnpm add @anthropic-ai/sdk

最小示例:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://api.hyper-ailab.com",
  apiKey: process.env.ANTHROPIC_API_KEY,   // sk-relay-xxx
});

const msg = await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hi Claude" }],
});

console.log(msg.content[0]);

注意 JavaScript SDK 用的是 camelCase (baseURL),不是 snake_case。这是 SDK 自己的约定,不是我们强加的。

高级特性也都直接透传

我们没有改签名,所以下面这些东西完全不需要特殊适配:

  • 流式响应:client.messages.stream(...) / stream=True —— 见 流式响应
  • Beta 端点:client.beta.messages.create(...) —— 原样透传到 Anthropic beta API
  • Tool use:传 tools=[...] 让 Claude 调用工具,我们会把 tool_use block 原封不动还给你
  • Memory Tool:tools=[{"type": "memory_20250818", "name": "memory"}] —— 这个是我们在后端实现了真实存储的,唯一的差异点是"存哪里",协议跟 Anthropic 一致
  • Prompt Caching:在 system 和 messages 里加 cache_control,我们原样透传(缓存命中价格见 定价与订阅)
  • Extended Thinking(Opus 4.6 的扩展思考):传 thinking={"type": "enabled", "budget_tokens": 10000},同样透传

换句话说:任何在 Anthropic 官方文档 上能找到的用法,在 HyperAI Relay 上都能直接用,不用查"这个 feature 你们支持吗"。

计费相关的 SDK 使用

SDK 的 message.usage 字段(包含 input_tokens / output_tokens / cache_read_input_tokens / cache_creation_input_tokens)会原样返回,和我们后端入账的口径完全一致。所以你可以用 SDK 本地计算成本,不会跟 /app/usage 对不上账。

计费精度是 NUMERIC(18, 6),详见 定价与订阅。

常见问题

Q:SDK 里的自动重试会不会跟你们的限流叠加? A:官方 SDK 对 429 / 503 默认重试 2 次(带指数退避),我们这边对上游同样做了重试,但加起来最多 4~5 次,不会打循环。详见 错误码与重试。

Q:我用 SDK 看到 429 rate_limit_error,但 /app/usage 显示我没超量? A:大概率是上游 Anthropic 在限流我们。我们不改错误码,原样透传。重试一下就好。

Q:能直接用 OpenAI SDK 吗(走 OpenAI → Anthropic 兼容层)? A:不能。我们不做协议转换,只讲 Anthropic 原生协议。如果你真的需要 OpenAI 协议,见 其他客户端 里的"转换层"部分。

下一步