所有对话模型均兼容 OpenAI 格式

# 所有对话模型均兼容 OpenAI 格式，一键对接

请求路径	/v1/chat/completions

你也可以使用同步响应接口 /v1/responses（本接口兼容 Responses API 调用方式）
仅需替换 model ，即可使用 OpenAI、Claude、Gemini、DeepSeek、Grok、Qwen 等大语言模
OpenAI 兼容格式”的标准 curl 示例（可让AI帮你写）
将 YOUR_API_BASE 替换为你的服务地址 https://api.cxsee.com
将 YOUR_API_KEY 替换为用户自己的密钥

---

### 对话生成 API 文档

用于调用如OpenAI、Claude、Gemini等大模型进行多轮对话、问答与内容生成。

## 1. 接口地址

**POST** `/v1/chat/completions`

> 生产环境示例：`https://cxsee.cxsee.com/v1/chat/completions`

---

## 2. 认证方式

在请求头中传入 API Key：

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

---

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| model | string | 是 | 模型 ID，例如：`gpt-5.4` |
| messages | array | 是 | 对话消息列表（按顺序） |
| messages[].role | string | 是 | 角色：`system` / `user` / `assistant` |
| messages[].content | string | 是 | 消息内容 |
| temperature | number | 否 | 采样随机性，建议 `0~2`，默认 `1` |
| stream | boolean | 否 | 是否流式返回，默认 `false` |

---

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

```bash
curl -X POST "https://cxsee.cxsee.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "user",
        "content": "你好，请用一句话介绍你自己"
      }
    ],
    "temperature": 0.7,
    "stream": false
  }'
```

---

## 5. 返回示例（成功）

```json
{
  "id": "chatcmpl-5fceea0d-305e-4517-85d2-efb3105a8876",
  "object": "chat.completion",
  "created": 1773596471,
  "model": "gpt-5.4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好，我是一个由 OpenAI 提供的 AI 助手，可以帮你解答问题、写作、翻译、编程和整理思路。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 38,
    "total_tokens": 52
  }
}
```
##流式回复请求示例（stream=true）
```
curl -N -X POST "https://cxsee.cxsee.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "messages": [
      {
        "role": "user",
        "content": "请用3句话介绍一下人工智能的发展"
      }
    ],
    "temperature": 0.7,
    "stream": true
  }'
```
### 流式返回示例（SSE）
```
data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1773599999,"model":"gpt-5.4","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1773599999,"model":"gpt-5.4","choices":[{"index":0,"delta":{"content":"人工智能起源于"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1773599999,"model":"gpt-5.4","choices":[{"index":0,"delta":{"content":"20世纪中期，"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1773599999,"model":"gpt-5.4","choices":[{"index":0,"delta":{"content":"经历了符号主义、机器学习和深度学习等阶段。"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1773599999,"model":"gpt-5.4","choices":[{"index":0,"delta":{"content":"近年来，大模型推动了自然语言、视觉与多模态能力的快速突破。"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1773599999,"model":"gpt-5.4","choices":[{"index":0,"delta":{"content":"未来人工智能将更深入地重塑教育、医疗、制造与办公协作。"},"finish_reason":"stop"}]}

data: [DONE]
```

## 6. 响应字段说明

| 字段 | 说明 |
|---|---|
| id | 本次请求唯一 ID（可用于排障与日志追踪） |
| object | 对象类型，通常为 `chat.completion` |
| created | 响应创建时间（Unix 时间戳） |
| model | 实际使用的模型 ID |
| choices | 生成结果数组（通常取 `choices[0]`） |
| choices[].message.role | 返回角色，通常为 `assistant` |
| choices[].message.content | 模型生成内容 |
| finish_reason | 结束原因：`stop` 表示正常结束 |
| usage.prompt_tokens | 输入消耗 tokens |
| usage.completion_tokens | 输出消耗 tokens |
| usage.total_tokens | 总消耗 tokens |

---

## 7. 错误码说明（通用）

| HTTP 状态码 | 含义 | 建议处理 |
|---:|---|---|
| 400 | 参数错误 | 检查 `model/messages` 等字段格式 |
| 401 | 认证失败 | 检查 API Key 是否正确、是否过期 |
| 403 | 无权限 | 检查账号权限/模型调用权限 |
| 429 | 请求过频 | 退避重试（指数退避） |
| 500 | 服务异常 | 稍后重试，并携带 `id` 联系支持 |

---

## 8. 调用建议

1. 生产环境请妥善保管 API Key，避免写入前端代码。
2. 建议记录响应中的 `id` 与 `usage`，便于审计和成本统计。
3. 对 429/5xx 错误建议实现自动重试机制。
4. 首次接入建议使用 `stream=false` 调通后，再切换流式输出。

---

## 9. 快速排查清单

- URL 是否正确：`https://cxsee.cxsee.com/v1/chat/completions`
- Header 是否包含：`Authorization: Bearer YOUR_API_KEY`
- `model` 是否为可用模型 ID（如 `gpt-5.4`）
- `messages` 是否为数组，且每项含 `role` + `content`

---

上一篇：操练场下一篇：Models（列出可用模型）