Claude API 接入指南：Anthropic 原生接口与密钥配置

一、概述

极智时代为开发者提供 Anthropic Messages API（/v1/messages） 兼容的中转接入。你只需把请求发到本站网关，并将鉴权 Key 换成在「用户中心 - API 密钥」中创建的 sk- 密钥，即可直接使用 Claude 系列模型，无需改动已有代码。

当前开放的模型以模型广场为准（如 claude-sonnet-5、claude-opus-5、claude-sonnet-4-6、claude-opus-4-8 等），完整清单与单价随时通过 GET /v1/models 查询。

二、接口地址

方法	路径	说明
POST	/v1/messages	中转转发入口，请求体为 Anthropic /v1/messages 载荷
GET	/v1/models	模型与单价列表（无需鉴权）

网关地址：https://www.azztimes.com。请求路径按上表原样填写。

三、鉴权方式

在「用户中心 → API 密钥」创建密钥，格式 sk-xxxxxxxx。调用时通过以下任一方式携带：

• Authorization 头：Authorization: Bearer sk-你的密钥（推荐，兼容大部分 SDK）
• x-api-key 头：x-api-key: sk-你的密钥

密钥无效、停用或余额不足时会返回 401 / 403，请先确认密钥状态与账户余额。

四、快速开始（curl）

4.1 非流式对话

curl -X POST https://www.azztimes.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己"}
    ]
  }'

4.2 携带 system 提示词与多轮对话

curl -X POST https://www.azztimes.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-你的密钥" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 2048,
    "system": "你是一位严谨的技术文档工程师。",
    "messages": [
      {"role": "user", "content": "Claude Messages API 的鉴权头是什么？"},
      {"role": "assistant", "content": "使用 x-api-key 或 Authorization: Bearer 携带密钥。"},
      {"role": "user", "content": "再举一个流式请求的例子。"}
    ],
    "metadata": {"request_id": "demo-001"}
  }'

metadata.request_id 会写入用量日志，方便在「用户中心 → 用量明细」中对账。

五、请求参数

字段	类型	必填	说明
model	string	是	模型 slug，如 claude-sonnet-5
max_tokens	int	是	最大输出 token 数，建议 1~64000
messages	array	是	对话消息，元素为 {role, content}，role 取值 user / assistant
system	string	否	系统提示词
temperature	number	否	采样温度，默认 1.0，范围 0~1
top_p	number	否	核采样，默认 0.999
stream	bool	否	是否流式返回，默认 false
stop_sequences	array	否	停止序列
metadata.request_id	string	否	自定义请求 ID，用于对账

六、响应结构

非流式请求返回标准 Anthropic Messages 结构：

{
  "id": "msg_01ABCDEFG",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5",
  "content": [
    {"type": "text", "text": "你好！我是 Claude。"}
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 18,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}

字段	说明
id	消息唯一 ID
content[].type	内容块类型，text / thinking 等
content[].text	文本内容
stop_reason	停止原因：end_turn / max_tokens / stop_sequence
usage.input_tokens	输入 token 数（计费依据）
usage.output_tokens	输出 token 数（计费依据）
usage.cache_read_input_tokens	缓存命中的输入 token 数（按缓存读价计费）
usage.cache_creation_input_tokens	写入缓存的 token 数（按缓存写价计费）

七、流式输出

请求体加 "stream": true 后，服务端以 SSE（Server-Sent Events） 逐块返回，事件类型与 Anthropic 一致：

event: message_start
data: {"type": "message_start", "message": {"id": "msg_...", "model": "claude-sonnet-5"}}

event: content_block_delta
data: {"type": "content_block_delta", "delta": {"type": "text_delta", "text": "你好"}}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn"}, "usage": {"output_tokens": 18}}

event: message_stop
data: {"type": "message_stop"}

客户端需按 data: 行解析 JSON，忽略 event: 行与空行；收到 message_stop 表示流结束。计费在服务端按整次请求的 usage 结算，与流式无关。

八、常见错误码

HTTP 状态码	含义	处理建议
400	请求参数不合法（缺少 model/max_tokens、模型未启用等）	按响应 message 修正请求体
401	未携带或携带无效的 API 密钥	检查 Authorization / x-api-key 头
403	密钥被停用、余额不足，或该密钥未授权此模型/路线	充值、检查密钥状态或调整密钥授权
404	请求的模型不存在	通过 GET /v1/models 查看可用模型
429	请求过于频繁或触发限流	退避重试（指数退避）
500	服务内部错误	稍后重试；持续失败请联系客服

错误响应体统一为 {"code": 状态码, "message": "错误说明", "data": null} 结构。

九、用量与余额

• 每笔调用按 token 用量 × 模型单价 × 路线倍率实时扣费，单价与路线见 GET /v1/models。
• 登录后在「用户中心 → API 用量」查看调用记录（模型、token、费用、状态）。
• 余额不足时调用返回 403，充值后立即恢复。