Doubao（豆包）对话(OpenAI 兼容）

# 豆包文本对话 API 文档
### 接口路径 
/v1/chat/completions
/v1/responses
/v1/messages

本文档用于说明如何通过 `https://api.cxsee.com/v1/chat/completions` 接口调用豆包文本对话模型，完成基础的多轮文本对话请求。

###### 支持发送包含文本、图片、视频、音频等模态的消息列表，模型将生成对话中的下一条消息。

---

## 1. 接口说明

### 接口地址

```http
POST https://api.cxsee.com/v1/chat/completions
```

### 接口功能

用于调用豆包文本对话模型，向模型发送系统提示词和用户消息，并获取模型生成的回复内容。

---

## 2. 请求方式

```http
POST
```

---

## 3. 请求头 Headers

| 参数名 | 必填 | 示例 | 说明 |
|---|---|---|---|
| `Content-Type` | 是 | `application/json` | 请求体格式，固定为 JSON |
| `Authorization` | 是 | `Bearer sk-xxxx` | API 密钥认证信息 |

示例：

```http
Content-Type: application/json
Authorization: Bearer sk-xxxxxxxxxxxxxxxx
```

> 注意：请勿在前端页面或公开代码仓库中暴露 API Key。

---

## 4. 请求参数

### Body 参数

| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | 是 | 使用的模型名称 |
| `messages` | array | 是 | 对话消息列表 |

---

## 5. messages 参数说明

`messages` 是一个数组，用于描述上下文对话内容。每条消息包含：

| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `role` | string | 是 | 消息角色，可选值：`system`、`user`、`assistant` |
| `content` | string | 是 | 消息内容 |

### role 说明

| role | 说明 |
|---|---|
| `system` | 系统提示词，用于设定模型身份、回复风格和行为规则 |
| `user` | 用户输入内容 |
| `assistant` | 模型历史回复内容，常用于多轮对话 |

---

## 6. 推荐中文系统提示词

可以将原来的英文提示词：

```text
You are a helpful assistant.
```

替换为更规范的中文提示词：

```text
你是一名专业、友好且严谨的智能助手。请根据用户的问题提供准确、清晰、易理解的回答。在回答时保持礼貌，避免编造信息；如果问题缺少必要背景，请主动说明并引导用户补充信息。
```

---

## 7. CURL 请求示例

```bash
curl https://api.cxsee.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "doubao-seed-2-0-mini-260428",
    "messages": [
      {
        "role": "system",
        "content": "你是一名专业、友好且严谨的智能助手。请根据用户的问题提供准确、清晰、易理解的回答。在回答时保持礼貌，避免编造信息；如果问题缺少必要背景，请主动说明并引导用户补充信息。"
      },
      {
        "role": "user",
        "content": "你好，请简单介绍一下你能做什么。"
      }
    ]
  }'
```

---

## 8. 请求体示例

```json
{
  "model": "doubao-seed-2-0-mini-260428",
  "messages": [
    {
      "role": "system",
      "content": "你是一名专业、友好且严谨的智能助手。请根据用户的问题提供准确、清晰、易理解的回答。在回答时保持礼貌，避免编造信息；如果问题缺少必要背景，请主动说明并引导用户补充信息。"
    },
    {
      "role": "user",
      "content": "你好，请简单介绍一下你能做什么。"
    }
  ]
}
```

---

## 9. 响应示例

接口请求成功后，会返回类似如下结果：

```json
{
  "id": "021782675903246b686cf77507a74aa4905f351832e6617c58df0",
  "object": "chat.completion",
  "created": 1782675904,
  "model": "doubao-seed-2-0-mini-260428",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是一个智能助手，可以帮助你解答问题、撰写文案、整理资料、翻译文本、生成代码、分析内容等。你可以直接告诉我你的需求，我会尽力提供清晰、准确的帮助。",
        "reasoning_content": "..."
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 45,
    "completion_tokens": 69,
    "total_tokens": 114,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 60
    }
  },
  "service_tier": "default"
}
```

---

## 10. 响应字段说明

| 字段名 | 类型 | 说明 |
|---|---|---|
| `id` | string | 本次请求的唯一 ID |
| `object` | string | 返回对象类型，通常为 `chat.completion` |
| `created` | integer | 响应创建时间戳 |
| `model` | string | 实际使用的模型名称 |
| `choices` | array | 模型回复结果列表 |
| `usage` | object | Token 使用统计 |
| `service_tier` | string | 服务等级 |

---

## 11. choices 字段说明

| 字段名 | 类型 | 说明 |
|---|---|---|
| `index` | integer | 回复序号 |
| `message` | object | 模型返回的消息内容 |
| `finish_reason` | string | 生成结束原因 |

### message 字段说明

| 字段名 | 类型 | 说明 |
|---|---|---|
| `role` | string | 返回消息角色，通常为 `assistant` |
| `content` | string | 模型最终回复内容 |
| `reasoning_content` | string | 模型推理过程内容，如接口返回则可读取 |

---

## 12. usage 字段说明

| 字段名 | 类型 | 说明 |
|---|---|---|
| `prompt_tokens` | integer | 输入内容消耗的 Token 数 |
| `completion_tokens` | integer | 输出内容消耗的 Token 数 |
| `total_tokens` | integer | 总 Token 数 |
| `prompt_tokens_details.cached_tokens` | integer | 命中缓存的 Token 数 |
| `completion_tokens_details.reasoning_tokens` | integer | 推理过程消耗的 Token 数 |

---

## 13. Python 调用示例

```python
import requests

url = "https://api.cxsee.com/v1/chat/completions"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk-xxxxxxxxxxxxxxxx"
}

data = {
    "model": "doubao-seed-2-0-mini-260428",
    "messages": [
        {
            "role": "system",
            "content": "你是一名专业、友好且严谨的智能助手。请根据用户的问题提供准确、清晰、易理解的回答。在回答时保持礼貌，避免编造信息；如果问题缺少必要背景，请主动说明并引导用户补充信息。"
        },
        {
            "role": "user",
            "content": "你好，请简单介绍一下你能做什么。"
        }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
```

---

## 14. JavaScript 调用示例

```javascript
const response = await fetch("https://api.cxsee.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer sk-xxxxxxxxxxxxxxxx"
  },
  body: JSON.stringify({
    model: "doubao-seed-2-0-mini-260428",
    messages: [
      {
        role: "system",
        content: "你是一名专业、友好且严谨的智能助手。请根据用户的问题提供准确、清晰、易理解的回答。在回答时保持礼貌，避免编造信息；如果问题缺少必要背景，请主动说明并引导用户补充信息。"
      },
      {
        role: "user",
        content: "你好，请简单介绍一下你能做什么。"
      }
    ]
  })
});

const data = await response.json();
console.log(data);
```

---

## 15. 多轮对话示例

如果需要让模型记住前文，需要将历史对话一并传入 `messages`。

```json
{
  "model": "doubao-seed-2-0-mini-260428",
  "messages": [
    {
      "role": "system",
      "content": "你是一名专业、友好且严谨的智能助手。请根据用户的问题提供准确、清晰、易理解的回答。"
    },
    {
      "role": "user",
      "content": "什么是人工智能？"
    },
    {
      "role": "assistant",
      "content": "人工智能是指让计算机系统模拟人类智能能力的技术，例如理解语言、识别图像、进行推理和辅助决策等。"
    },
    {
      "role": "user",
      "content": "请用一句话再解释得更简单一些。"
    }
  ]
}
```

---

## 16. 常见错误说明

| HTTP 状态码 | 可能原因 | 处理方式 |
|---|---|---|
| `400` | 请求参数格式错误 | 检查 JSON 格式、`model` 和 `messages` 是否正确 |
| `401` | API Key 无效或未传入 | 检查 `Authorization` 请求头 |
| `403` | 当前 Key 无权限访问该模型 | 确认账号或分组权限 |
| `429` | 请求过于频繁或额度不足 | 降低请求频率或检查额度 |
| `500` | 服务端异常 | 稍后重试或联系服务提供方 |

---

## 17. 最简调用示例

```bash
curl https://api.cxsee.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -d '{
    "model": "doubao-seed-2-0-mini-260428",
    "messages": [
      {
        "role": "system",
        "content": "你是一名专业、友好且严谨的智能助手。请使用简洁、准确的中文回答用户问题。"
      },
      {
        "role": "user",
        "content": "你好！"
      }
    ]
  }'
```

---

## 18. 安全建议

1. 不要将 API Key 写入前端代码。
2. 不要把 API Key 提交到 GitHub、Gitee 等公开仓库。
3. 建议在服务端环境变量中保存 API Key。
4. 如果 API Key 已经泄露，应立即删除或重置。
5. 生产环境建议增加请求频率限制和日志审计。

上一篇：千问Qwen 对话（OpenAI 兼容）下一篇：Xiaomi MiMo 对话（OpenAI 兼容）