543 lines
12 KiB
Markdown
543 lines
12 KiB
Markdown
# 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 | 初稿 |
|
||
|
||
---
|
||
|
||
*文档结束*
|