# Coze API 测试文档

> **版本**：v1.0  
> **创建日期**：2026-02-08  
> **基础路径**：`/api/front/coze`  
> **服务端口**：20822  
> **认证方式**：免登录（已加入白名单）

---

## 一、配置信息

### 1.1 当前环境配置

| 配置项 | 值 | 说明 |
|--------|-----|------|
| Base URL | `https://api.coze.cn` | Coze 平台 API 地址 |
| Auth Type | `pat` | Personal Access Token 模式 |
| Default Bot ID | `7591133240535449654` | 食谱计算器 Bot |
| Default User ID | `3243981400446844` | 测试用户 ID |

---

## 二、接口清单

| 序号 | 接口名称 | HTTP方法 | 路径 | 说明 |
|------|----------|----------|------|------|
| 1 | 发起对话 | `POST` | `/chat` | 与 Coze Bot 对话（支持流式/非流式） |
| 2 | 流式对话 | `POST` | `/chat/stream` | SSE 流式对话 |
| 3 | 执行工作流 | `POST` | `/workflow/run` | 触发预定义工作流 |
| 4 | 流式执行工作流 | `POST` | `/workflow/stream` | SSE 流式执行工作流 |
| 5 | 查看对话详情 | `POST` | `/chat/retrieve` | 查询对话状态 |
| 6 | 查看对话消息列表 | `POST` | `/chat/messages/list` | 获取对话消息 |
| 7 | 上传文件 | `POST` | `/file/upload` | 上传文件获取 file_id |

---

## 三、接口详细说明

### 3.1 发起对话

#### 基础信息

| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/chat` |
| Content-Type | `application/json` |
| 是否鉴权 | **否**（白名单） |

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `botId` | String | 是 | Coze Bot ID |
| `userId` | String | 是 | 业务系统用户 ID |
| `stream` | Boolean | 否 | 是否流式返回，默认 false |
| `chatHistory` | Array | 否 | 历史对话上下文 |
| `additionalMessages` | Array | 否 | 当前发送的消息 |

**chatHistory 结构**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| `role` | String | 角色：`user` / `assistant` |
| `content` | String | 消息内容 |
| `contentType` | String | 内容类型：`text` / `object_string` / `card` |

#### 测试用例

##### TC-COZE-01: 基础对话测试

```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat' \
-H "Content-Type: application/json" \
-d '{
  "botId": "7591133240535449654",
  "userId": "test_user_001",
  "stream": false,
  "additionalMessages": [
    {
      "role": "user",
      "content": "你好，请介绍一下自己"
    }
  ]
}'
```

**预期响应**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "xxxxx",
    "conversationId": "xxxxx",
    "botId": "7591133240535449654",
    "status": "completed",
    "createdAt": 1707350400,
    "completedAt": 1707350405
  }
}
```

##### TC-COZE-02: 食谱计算器测试（男性透析患者）

```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat' \
-H "Content-Type: application/json" \
-d '{
  "botId": "7591133240535449654",
  "userId": "3243981400446844",
  "stream": false,
  "additionalMessages": [
    {
      "role": "user",
      "content": "请帮我计算营养方案，我的信息如下：性别男，年龄55岁，身高170cm，正在进行血液透析，干体重65.5kg，血肌酐850μmol/L"
    }
  ]
}'
```

##### TC-COZE-03: 食谱计算器测试（女性非透析患者）

```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat' \
-H "Content-Type: application/json" \
-d '{
  "botId": "7591133240535449654",
  "userId": "3243981400446844",
  "stream": false,
  "additionalMessages": [
    {
      "role": "user",
      "content": "请帮我计算营养方案，我的信息如下：性别女，年龄48岁，身高160cm，未透析，体重52kg，血肌酐180μmol/L"
    }
  ]
}'
```

##### TC-COZE-04: 带历史上下文的对话

```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat' \
-H "Content-Type: application/json" \
-d '{
  "botId": "7591133240535449654",
  "userId": "test_user_001",
  "stream": false,
  "chatHistory": [
    {
      "role": "user",
      "content": "我是一名55岁的男性透析患者",
      "contentType": "text"
    },
    {
      "role": "assistant",
      "content": "好的，我了解了您的基本情况。请问您还有其他健康数据需要提供吗？",
      "contentType": "text"
    }
  ],
  "additionalMessages": [
    {
      "role": "user",
      "content": "我的身高是170cm，体重65.5kg，血肌酐850"
    }
  ]
}'
```

---

### 3.2 流式对话

#### 基础信息

| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/chat/stream` |
| Content-Type | `application/json` |
| Response Type | `text/event-stream` |

#### 测试用例

##### TC-COZE-05: 流式对话测试

```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat/stream' \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
  "botId": "7591133240535449654",
  "userId": "test_user_001",
  "additionalMessages": [
    {
      "role": "user",
      "content": "请详细介绍一下肾病患者的饮食注意事项"
    }
  ]
}'
```

**预期响应（SSE 格式）**

```
event: message
data: {"event":"conversation.chat.created","chat":{"id":"xxx","conversation_id":"xxx"}}

event: message
data: {"event":"conversation.message.delta","message":{"content":"肾病患者..."}}

event: message
data: {"event":"conversation.message.delta","message":{"content":"需要注意..."}}

event: message
data: {"event":"conversation.chat.completed","chat":{"status":"completed"}}
```

---

### 3.3 执行工作流

#### 基础信息

| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/workflow/run` |
| Content-Type | `application/json` |

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `workflowId` | String | 是 | 工作流 ID |
| `parameters` | Object | 否 | 工作流输入参数 |
| `isAsync` | Boolean | 否 | 是否异步执行，默认 false |

#### 测试用例

##### TC-COZE-06: 同步执行工作流

```bash
curl -X POST 'http://localhost:20822/api/front/coze/workflow/run' \
-H "Content-Type: application/json" \
-d '{
  "workflowId": "1180790412263",
  "isAsync": false,
  "parameters": {
    "gender": "male",
    "age": 55,
    "height": 170,
    "dialysis": true,
    "dialysisType": "hemodialysis",
    "dryWeight": 65.5,
    "creatinine": 850
  }
}'
```

##### TC-COZE-07: 异步执行工作流

```bash
curl -X POST 'http://localhost:20822/api/front/coze/workflow/run' \
-H "Content-Type: application/json" \
-d '{
  "workflowId": "1180790412263",
  "isAsync": true,
  "parameters": {
    "userId": "test_user_001",
    "recordId": 12345
  }
}'
```

---

### 3.4 流式执行工作流

#### 基础信息

| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/workflow/stream` |
| Content-Type | `application/json` |
| Response Type | `text/event-stream` |

#### 测试用例

##### TC-COZE-08: 流式工作流测试

```bash
curl -X POST 'http://localhost:20822/api/front/coze/workflow/stream' \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
  "workflowId": "1180790412263",
  "parameters": {
    "input": "分析用户的饮食记录"
  }
}'
```

---

### 3.5 查看对话详情

#### 基础信息

| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/chat/retrieve` |
| Content-Type | `application/json` |

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `conversationId` | String | 是 | 对话 ID |
| `chatId` | String | 是 | Chat ID |

#### 测试用例

##### TC-COZE-09: 查询对话详情

```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat/retrieve' \
-H "Content-Type: application/json" \
-d '{
  "conversationId": "7460461142355574825",
  "chatId": "7460461142355590000"
}'
```

**预期响应**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "7460461142355590000",
    "conversationId": "7460461142355574825",
    "botId": "7591133240535449654",
    "status": "completed",
    "createdAt": 1707350400,
    "completedAt": 1707350410,
    "usage": {
      "tokenCount": 1500,
      "outputCount": 800,
      "inputCount": 700
    }
  }
}
```

---

### 3.6 查看对话消息列表

#### 基础信息

| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/chat/messages/list` |
| Content-Type | `application/json` |

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `conversationId` | String | 是 | 对话 ID |
| `chatId` | String | 是 | Chat ID |

#### 测试用例

##### TC-COZE-10: 获取对话消息列表

```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat/messages/list' \
-H "Content-Type: application/json" \
-d '{
  "conversationId": "7460461142355574825",
  "chatId": "7460461142355590000"
}'
```

**预期响应**

```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "msg_001",
      "role": "user",
      "type": "question",
      "content": "请帮我计算营养方案",
      "contentType": "text",
      "createdAt": 1707350400
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "type": "answer",
      "content": "根据您提供的信息，我为您计算了以下营养方案...",
      "contentType": "text",
      "createdAt": 1707350410
    }
  ]
}
```

---

### 3.7 上传文件

#### 基础信息

| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/file/upload` |
| Content-Type | `multipart/form-data` |

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `file` | File | 是 | 待上传的文件 |

#### 测试用例

##### TC-COZE-11: 上传图片文件

```bash
curl -X POST 'http://localhost:20822/api/front/coze/file/upload' \
-F "file=@/path/to/your/image.jpg"
```

##### TC-COZE-12: 上传文档文件

```bash
curl -X POST 'http://localhost:20822/api/front/coze/file/upload' \
-F "file=@/path/to/your/document.pdf"
```

**预期响应**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "file_xxxxx",
    "bytes": 102400,
    "createdAt": 1707350400,
    "fileName": "image.jpg"
  }
}
```

---

## 四、错误码说明

| code | message | 说明 |
|------|---------|------|
| 200 | success | 请求成功 |
| 400 | Bad Request | 请求参数错误 |
| 401 | Unauthorized | 认证失败（Token 无效或过期） |
| 404 | Not Found | 资源不存在 |
| 429 | Too Many Requests | 请求频率超限 |
| 500 | Internal Server Error | 服务端内部错误 |

---

## 五、常见问题

### 5.1 Token 过期

当前使用 PAT 模式，Token 有效期 30 天。如遇 401 错误，请检查配置文件中的 `coze.api.token` 是否过期。

### 5.2 Bot ID 无效

确保使用正确的 Bot ID。默认 Bot ID `7591133240535449654` 为食谱计算器专用。

### 5.3 流式接口超时

流式接口默认超时时间为 60 秒。对于长时间运行的对话，请确保客户端保持连接。

---

## 六、Postman 测试集合

可导入以下 JSON 到 Postman 进行测试：

```json
{
  "info": {
    "name": "Coze API Tests",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "基础对话",
      "request": {
        "method": "POST",
        "header": [{"key": "Content-Type", "value": "application/json"}],
        "body": {
          "mode": "raw",
          "raw": "{\"botId\": \"7591133240535449654\", \"userId\": \"test_user_001\", \"stream\": false, \"additionalMessages\": [{\"role\": \"user\", \"content\": \"你好\"}]}"
        },
        "url": {"raw": "http://localhost:20822/api/front/coze/chat"}
      }
    },
    {
      "name": "食谱计算-男性透析",
      "request": {
        "method": "POST",
        "header": [{"key": "Content-Type", "value": "application/json"}],
        "body": {
          "mode": "raw",
          "raw": "{\"botId\": \"7591133240535449654\", \"userId\": \"3243981400446844\", \"stream\": false, \"additionalMessages\": [{\"role\": \"user\", \"content\": \"请帮我计算营养方案，我的信息如下：性别男，年龄55岁，身高170cm，正在进行血液透析，干体重65.5kg，血肌酐850μmol/L\"}]}"
        },
        "url": {"raw": "http://localhost:20822/api/front/coze/chat"}
      }
    }
  ]
}
```

---

## 七、变更记录

| 版本 | 日期 | 作者 | 变更内容 |
|------|------|------|----------|
| v1.0 | 2026-02-08 | System | 初稿 |

---

*文档结束*