012-kaopeilian/docs/规划/全链路联调/Ai工作流/coze/播课/Coze工作流运行API文档.md

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	可选	是否异步运行（仅付费版可用）

播课工作流请求示例

{
  "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 总量

播课工作流返回示例

{
  "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版本）

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	异步运行需付费版	使用同步模式或升级账号

错误日志记录

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
维护人: 考培练系统开发团队