scottpan/msh-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
msh-system/docs/Testing/Coze-API测试文档.md

12 KiB
Raw Permalink Blame History

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: 基础对话测试
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": "你好，请介绍一下自己"
    }
  ]
}'

预期响应

{
  "code": 200,
  "message": "success",
  "data": {
    "id": "xxxxx",
    "conversationId": "xxxxx",
    "botId": "7591133240535449654",
    "status": "completed",
    "createdAt": 1707350400,
    "completedAt": 1707350405
  }
}
TC-COZE-02: 食谱计算器测试（男性透析患者）
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: 食谱计算器测试（女性非透析患者）
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: 带历史上下文的对话
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: 流式对话测试
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: 同步执行工作流
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: 异步执行工作流
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: 流式工作流测试
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: 查询对话详情
curl -X POST 'http://localhost:20822/api/front/coze/chat/retrieve' \
-H "Content-Type: application/json" \
-d '{
  "conversationId": "7460461142355574825",
  "chatId": "7460461142355590000"
}'

预期响应

{
  "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: 获取对话消息列表
curl -X POST 'http://localhost:20822/api/front/coze/chat/messages/list' \
-H "Content-Type: application/json" \
-d '{
  "conversationId": "7460461142355574825",
  "chatId": "7460461142355590000"
}'

预期响应

{
  "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: 上传图片文件
curl -X POST 'http://localhost:20822/api/front/coze/file/upload' \
-F "file=@/path/to/your/image.jpg"
TC-COZE-12: 上传文档文件
curl -X POST 'http://localhost:20822/api/front/coze/file/upload' \
-F "file=@/path/to/your/document.pdf"

预期响应

{
  "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 进行测试：

{
  "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 初稿

文档结束

Reference in New Issue View Git Blame Copy Permalink