998211c483
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
184 lines
5.2 KiB
Markdown
184 lines
5.2 KiB
Markdown
# Coze 工作流运行 API 文档
|
||
|
||
## 接口说明
|
||
|
||
执行已发布的工作流。此接口为非流式响应模式，对于支持流式输出的节点，应使用流式响应接口。
|
||
|
||
## 播课工作流配置信息
|
||
|
||
- **workflow_id**: `7561161554420482088`
|
||
- **space_id**: `7474971491470688296`
|
||
- **个人令牌**: 同陪练功能使用的 COZE_API_TOKEN
|
||
- **输入参数**: `course_id`（字符串类型）
|
||
- **输出结果**: mp3 音频文件 URL
|
||
|
||
## 基础信息
|
||
|
||
| 项目 | 内容 |
|
||
|------|------|
|
||
| 请求方式 | POST |
|
||
| 请求地址 | `https://api.coze.cn/v1/workflow/run` |
|
||
| 权限 | run（确保个人令牌开通了 run 权限） |
|
||
| 超时时间 | 默认 10 分钟，建议控制在 5 分钟以内 |
|
||
|
||
## 限制说明
|
||
|
||
| 限制项 | 说明 |
|
||
|--------|------|
|
||
| 工作流发布状态 | 必须为已发布状态 |
|
||
| 请求大小上限 | 20 MB |
|
||
| 超时时间 | 未开启异步时为 10 分钟，开启异步后为 24 小时 |
|
||
|
||
## 请求参数
|
||
|
||
### Header
|
||
|
||
| 参数 | 取值 | 说明 |
|
||
|------|------|------|
|
||
| Authorization | Bearer $Access_Token | Personal Access Token 认证 |
|
||
| Content-Type | application/json | 请求正文格式 |
|
||
|
||
### Body
|
||
|
||
| 参数 | 类型 | 是否必选 | 说明 |
|
||
|------|------|----------|------|
|
||
| workflow_id | String | 必选 | 待执行的 Workflow ID |
|
||
| parameters | Map | 可选 | 工作流开始节点的输入参数，JSON 格式 |
|
||
| bot_id | String | 可选 | 需要关联的智能体 ID |
|
||
| app_id | String | 可选 | 关联的扣子应用 ID |
|
||
| ext | JSON Map | 可选 | 额外字段（经纬度、user_id 等） |
|
||
| is_async | Boolean | 可选 | 是否异步运行（仅付费版可用） |
|
||
|
||
## 播课工作流请求示例
|
||
|
||
```json
|
||
{
|
||
"workflow_id": "7561161554420482088",
|
||
"parameters": {
|
||
"course_id": "5"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 返回参数
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| code | Long | 调用状态码，0 表示成功 |
|
||
| data | String | 工作流执行结果，通常为 JSON 序列化字符串 |
|
||
| msg | String | 状态信息，失败时包含详细错误信息 |
|
||
| execute_id | String | 异步执行的事件 ID |
|
||
| debug_url | String | 调试页面 URL（7天有效期） |
|
||
| usage | Object | Token 使用情况 |
|
||
| detail | Object | 请求详情（包含 logid） |
|
||
|
||
### Usage 对象
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| input_count | Integer | 输入 Token 数 |
|
||
| output_count | Integer | 输出 Token 数 |
|
||
| token_count | Integer | Token 总量 |
|
||
|
||
## 播课工作流返回示例
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": "{\"mp3_url\":\"https://example.com/broadcast/course_5.mp3\"}",
|
||
"debug_url": "https://www.coze.cn/work_flow?execute_id=741364789030728****&space_id=7474971491470688296&workflow_id=7561161554420482088",
|
||
"msg": "",
|
||
"usage": {
|
||
"input_count": 120,
|
||
"token_count": 350,
|
||
"output_count": 230
|
||
}
|
||
}
|
||
```
|
||
|
||
## 使用 cozepy SDK 调用示例
|
||
|
||
### Python SDK（0.2.0版本）
|
||
|
||
```python
|
||
from cozepy import Coze, TokenAuth
|
||
from app.core.config import settings
|
||
import json
|
||
|
||
async def generate_broadcast(course_id: int) -> str:
|
||
"""调用 Coze 工作流生成播课音频"""
|
||
|
||
# 初始化 Coze 客户端
|
||
coze = Coze(
|
||
auth=TokenAuth(token=settings.COZE_API_TOKEN),
|
||
base_url=settings.COZE_API_BASE
|
||
)
|
||
|
||
try:
|
||
# 调用工作流
|
||
result = await coze.workflows.runs.create(
|
||
workflow_id=settings.COZE_BROADCAST_WORKFLOW_ID,
|
||
parameters={"course_id": str(course_id)}
|
||
)
|
||
|
||
# 解析返回结果
|
||
if result.code == 0:
|
||
data = json.loads(result.data)
|
||
mp3_url = data.get("mp3_url")
|
||
return mp3_url
|
||
else:
|
||
raise Exception(f"工作流执行失败: {result.msg}")
|
||
|
||
except Exception as e:
|
||
logger.error(f"调用 Coze 工作流失败: {e}")
|
||
raise
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
### 常见错误码
|
||
|
||
| code | 说明 | 处理方式 |
|
||
|------|------|---------|
|
||
| 0 | 成功 | 正常处理 |
|
||
| 400 | 参数错误 | 检查 workflow_id 和 parameters |
|
||
| 4200 | 工作流未发布 | 确保工作流已发布 |
|
||
| 500 | 服务器错误 | 记录 logid 并重试 |
|
||
| 6003 | 异步运行需付费版 | 使用同步模式或升级账号 |
|
||
|
||
### 错误日志记录
|
||
|
||
```python
|
||
logger.error(
|
||
f"Coze工作流执行失败",
|
||
extra={
|
||
"workflow_id": workflow_id,
|
||
"course_id": course_id,
|
||
"logid": result.detail.logid if hasattr(result, 'detail') else None,
|
||
"error_code": result.code,
|
||
"error_msg": result.msg
|
||
}
|
||
)
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **超时配置**：播课音频生成通常需要 10 分钟，建议设置超时时间为 180 秒
|
||
2. **Token 认证**：使用 Personal Access Token，与陪练功能共用同一个 token
|
||
3. **参数类型**：course_id 需要转换为字符串类型传递
|
||
4. **返回解析**：data 字段为 JSON 字符串，需要反序列化后提取 mp3_url
|
||
5. **调试支持**：返回的 debug_url 可用于查看工作流执行详情（7天有效期）
|
||
6. **异步模式**：免费版不支持异步模式，使用同步调用即可
|
||
|
||
## 参考链接
|
||
|
||
- Coze 官方文档：https://www.coze.cn/open/docs/developer_guides/workflow_run
|
||
- cozepy SDK 文档：https://github.com/coze-dev/coze-py
|
||
|
||
---
|
||
|
||
**文档版本**: v1.0
|
||
**创建日期**: 2025-10-14
|
||
**维护人**: 考培练系统开发团队
|
||
|