Claude Messages（对话） - 数字先锋API文档

# Claude Messages（对话）API 文档

## 1. 接口说明

本接口兼容官方 Anthropic Messages 格式，用于调用 Claude 模型进行对话生成。

- **Base URL**: `https://api.cxsee.com`
- **Endpoint**: `POST /v1/messages`
- **Content-Type**: `application/json`
- **鉴权方式**: `Authorization: Bearer YOUR_API_KEY`

---

## 2. 支持模型

当前可用（示例）：

- `claude-opus-4-6-thinking`（推荐，支持 thinking 内容）
- 实际返回中的 `model` 字段可能表现为 `claude-opus-4-6`，属于服务端标准化命名。

---

## 3. 请求头（Headers）

| Header | 必填 | 说明 |
|---|---|---|
| Authorization | 是 | `Bearer {API_KEY}` |
| Content-Type | 是 | `application/json` |

> 如需 Anthropic 原生风格，也可支持 `x-api-key` + `anthropic-version`（按网关配置）。

---

## 4. 请求参数（Request Body）

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型名称，如 `claude-opus-4-6-thinking` |
| max_tokens | integer | 是 | 最大输出 token 数 |
| messages | array | 是 | 对话消息列表 |
| messages[].role | string | 是 | 角色：`user` / `assistant` |
| messages[].content | string / array | 是 | 消息内容，常用 string |
| stream | boolean | 否 | 是否流式返回，默认 `false` |

---

## 5. 请求示例（非流式）

```bash
curl --location --request POST 'https://api.cxsee.com/v1/messages' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "claude-opus-4-6-thinking",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "你好，请用一句话介绍你自己。"
      }
    ]
  }'
```

---

## 6. 响应示例（非流式）

```json
{
  "content": [
    { "text": "\n\n", "type": "text" },
    { "thinking": "\nThe user is greeting me in Chinese ...\n", "type": "thinking" },
    { "text": "你好！我是 Claude Opus 4.6，一个由 Anthropic 打造的 AI 助手...", "type": "text" }
  ],
  "id": "msg_xxx",
  "model": "claude-opus-4-6",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 23,
    "output_tokens": 114,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}
```

---

## 7. 响应字段说明

| 字段 | 说明 |
|---|---|
| id | 消息唯一 ID |
| type | 固定为 `message` |
| role | 固定为 `assistant` |
| model | 实际使用模型 |
| content | 输出内容块数组，可能包含 `text` 和 `thinking` |
| stop_reason | 结束原因，如 `end_turn` |
| usage | token 使用统计 |

---

## 8. 如何提取最终回答文本

由于 `content` 中可能同时有 `thinking` 和 `text`，建议客户端只拼接 `type == "text"` 的内容作为最终展示给用户的答案。

伪代码：

```js
const finalText = resp.content
  .filter(item => item.type === "text" && item.text)
  .map(item => item.text)
  .join("");
```

---

## 9. 流式调用（可选）

请求增加：

```json
"stream": true
```

返回为 SSE 分块流，适用于打字机效果和长文本场景。

---

## 10. 错误码建议（对外约定）

| HTTP 状态码 | 含义 |
|---|---|
| 400 | 参数错误（如缺失 model/messages） |
| 401 | 鉴权失败（API Key 无效） |
| 403 | 无权限访问该模型 |
| 429 | 触发限流 |
| 500 | 服务器内部错误 |
| 503 | 上游模型服务不可用 |

---

## 11. 最佳实践建议

1. **设置合理 `max_tokens`**，避免超长输出导致成本升高。
2. **前端默认隐藏 thinking**，仅展示 `text`。
3. **记录 `id` 和 `usage`**，便于审计和计费。
4. **重试策略**：对 `429/503` 做指数退避重试。
5. **API Key 安全**：仅服务端保存，不下发浏览器端。

---

上一篇：Responses（统一响应）下一篇：Claude Messages（识图）