API 使用详解

基础信息

项目	值
API 基础 URL	https://api.hyper-ailab.com
认证方式	请求头 x-api-key
API 版本	2023-06-01

所有请求必须在 Header 中包含以下三个字段：

x-api-key: 你的 API Key
anthropic-version: 必须为 2023-06-01
content-type: 必须为 application/json

支持的端点

目前 HyperAI Relay 仅支持以下端点：

端点	方法	说明
/v1/messages	POST	发送消息（支持非流式和流式）

其他 Anthropic API 端点将陆续支持。如需使用尚未支持的端点，请联系客服。

请求示例

非流式请求

curl https://api.hyper-ailab.com/v1/messages \
  -H "x-api-key: sk-relay-v1-你的key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "请用一句话解释量子计算"}
    ]
  }'

流式请求

将 stream 设为 true 以启用 Server-Sent Events 流式响应：

curl https://api.hyper-ailab.com/v1/messages \
  -H "x-api-key: sk-relay-v1-你的key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "请讲一个关于机器人的短故事"}
    ]
  }'

流式响应格式为标准 SSE,事件类型与 Anthropic 官方完全一致:message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop、ping。参考 Anthropic 流式文档。

响应格式

HyperAI Relay 作为透明中转，响应格式与 Anthropic 官方 API 完全一致。以非流式响应为例：

{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "这里是模型的回复内容"
    }
  ],
  "model": "claude-haiku-4-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 15,
    "output_tokens": 42
  }
}

错误码说明

HTTP 状态码	错误类型	说明
401	authentication_error	API Key 无效或缺失，请检查 Key 是否正确
402	insufficient_balance	账户余额不足，请充值后再试
400	unknown_model	请求的模型未配置，请联系客服添加
503	no_upstream	上游 Anthropic 服务不可用，属于紧急情况，请稍后重试
其他 4xx/5xx	-	由 Anthropic 官方返回的错误，HyperAI Relay 透传

计费说明

HyperAI Relay 按以下四类 Token 分别计费：

Token 类型	说明
input_tokens	输入消息消耗的 Token
output_tokens	模型输出消耗的 Token
cache_read_tokens	Prompt Caching 中缓存读取消耗的 Token
cache_write_tokens	Prompt Caching 中缓存写入消耗的 Token

每次请求的响应体包含 Anthropic 原生 usage 字段(含 input_tokens、output_tokens、cache_creation_input_tokens、cache_read_input_tokens)。

具体扣费金额不会出现在响应体里,请登录控制台 /app/usage 查看每次请求的扣费明细(含 charged_cents 字段,单位:美分的 6 位小数)。

Rate Limit

HyperAI Relay 透传 Anthropic 原生的 Rate Limit 响应头。Anthropic 有多个维度的 rate limit:

anthropic-ratelimit-requests-limit / -remaining / -reset — 请求数
anthropic-ratelimit-input-tokens-limit / -remaining / -reset — 输入 token
anthropic-ratelimit-output-tokens-limit / -remaining / -reset — 输出 token
anthropic-ratelimit-tokens-limit / -remaining / -reset — 总 token

rate limit 共享所有用户的上游 key(本服务目前单上游)。你个人的速率限制由 virtual_keys.rate_limit_rpm 控制(如果 admin 设置了)。

当收到 429 rate_limit_error 时,请等待 Anthropic 返回的 retry-after 秒后重试,或使用指数退避。