千问Qwen 对话（OpenAI 兼容）

# 通义千问（Qwen）对话 API 文档（OpenAI 兼容）
所有通义千问（Qwen）对话模型均支持
## 1. 接口简介

本接口兼容 OpenAI Chat Completions 协议，可用于调用通义千问对话模型。

- **Base URL**: `https://api.cxsee.com/v1`
- **Endpoint**: `POST /chat/completions`
- **模型示例**: `qwen-turbo`

---

## 2. 鉴权方式

在请求头中传入 API Key：

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

---

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型名称，如 `qwen-turbo` |
| messages | array | 是 | 对话消息列表（OpenAI 标准格式） |
| stream | boolean | 否 | 是否流式返回，默认 `false` |
| temperature | number | 否 | 随机性参数（可选） |
| max_tokens | integer | 否 | 最大输出 token 数（可选） |

### messages 格式
```json
[
  {"role": "user", "content": "你好，介绍下自己"}
]
```

支持常见 role：`system`、`user`、`assistant`。

---

## 4. 请求示例（cURL）

```bash
curl -X POST "https://api.cxsee.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-turbo",
    "messages": [
      {"role": "user", "content": "你好，介绍下自己"}
    ]
  }'
```

---

## 5. 成功响应示例

```json
{
  "id": "chatcmpl-0c3363ad-54dc-9179-8a4c-c0ba70238617",
  "object": "chat.completion",
  "created": 1774088137,
  "model": "qwen-turbo",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "你好！我是通义千问..."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 17,
    "completion_tokens": 139,
    "total_tokens": 156,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  }
}
```

---

## 6. 响应字段说明

- `id`：请求唯一 ID
- `object`：固定为 `chat.completion`
- `created`：生成时间戳
- `model`：实际调用模型
- `choices[0].message.content`：模型回复文本
- `choices[0].finish_reason`：结束原因（如 `stop`）
- `usage`：token 统计信息（用于计费与监控）

---

## 7. 错误响应格式

```json
{
  "error": {
    "message": "错误描述",
    "type": "error_type",
    "code": "error_code"
  }
}
```

常见错误：
- `401 Unauthorized`：API Key 无效
- `429 Too Many Requests`：请求频率超限
- `400 Bad Request`：参数格式错误
- `402/余额相关错误`：额度不足

---

## 8. Python（OpenAI SDK）调用示例

```python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.cxsee.com/v1"
)

resp = client.chat.completions.create(
    model="qwen-turbo",
    messages=[
        {"role": "user", "content": "你好，介绍下自己"}
    ]
)

print(resp.choices[0].message.content)
```

---

## 9. 最佳实践建议

- 生产环境务必设置请求超时与重试机制
- 保留 `id` 和 `usage` 字段用于排障与计费核对
- 对用户输入做长度限制，避免超长上下文导致失败
- 若需稳定风格，建议增加 `system` 提示词约束回复语气

---

上一篇：智谱对话（OpenAI 兼容）下一篇：OCR 识别 API 文档