Claude Chat（OpenAI 兼容） - 数字先锋API文档

##Claude Chat Completions API（OpenAI 兼容）

## 1. 接口说明

用于多轮对话、文本生成、指令跟随等场景，Claude兼容 OpenAI Chat Completions 请求格式。

- **请求路径**：`POST /v1/chat/completions`
- **完整示例**：`https://api.cxsee.com/v1/chat/completions`
- **请求格式**：`application/json`
- **响应格式**：`application/json`

---

## 2. 认证方式

在请求头中携带 API Key：

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

> 如网关有额外要求，可增加：`x-api-key: YOUR_API_KEY`

---

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `model` | string | 是 | 模型名称，如 `claude-sonnet-4-6` |
| `messages` | array | 是 | 对话消息列表（`system`/`user`/`assistant`） |
| `temperature` | number | 否 | 采样温度，建议 `0~2`，越大越发散 |
| `max_tokens` | integer | 否 | 最大生成 token 数 |

### `messages` 示例

```json
[
  { "role": "system", "content": "你是一个专业、简洁的中文助手。" },
  { "role": "user", "content": "请用三点总结什么是RAG，并给一个落地建议。" }
]
```

---

## 4. 请求示例（cURL）

```bash
curl --request POST "https://api.cxsee.com/v1/chat/completions" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {
        "role": "system",
        "content": "你是一个专业、简洁的中文助手。"
      },
      {
        "role": "user",
        "content": "请用三点总结什么是RAG，并给一个落地建议。"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 800
  }'
```

---

## 5. 成功响应示例

```json
{
  "id": "msg_xxx",
  "object": "chat.completion",
  "created": 1774035320,
  "model": "claude-sonnet-4-6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 47,
    "completion_tokens": 222,
    "total_tokens": 269
  }
}
```

---

## 6. 字段说明（响应）

### 顶层字段
- `id`：请求唯一 ID
- `object`：对象类型，固定为 `chat.completion`
- `created`：Unix 时间戳（秒）
- `model`：实际使用模型
- `choices`：生成结果数组（通常取 `choices[0]`）
- `usage`：token 用量统计

### `choices[*]`
- `index`：候选序号
- `message.role`：通常为 `assistant`
- `message.content`：模型回复文本
- `finish_reason`：停止原因（如 `stop`、`length`）

---

## 7. 错误码

| HTTP 状态码 | 说明 |
|---|---|
| `400` | 请求参数错误（JSON 非法、字段缺失） |
| `401` | 认证失败（API Key 无效） |
| `403` | 无访问权限（模型不可用） |
| `429` | 请求过多，触发限流 |
| `500` | 服务内部错误 |

错误响应示例：
```json
{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

---

## 8. 最佳实践

1. **生产环境务必走服务端调用**，不要在前端暴露 API Key。
2. `temperature`：事实问答建议 `0~0.3`，创意写作可 `0.7~1.0`。
3. 控制 `max_tokens` 防止超长输出导致延迟增加。
4. 记录 `id` 和 `usage` 方便排障与计费核对。

---

上一篇：Claude Messages（函数调用）下一篇：Gemini 官方格式