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