引子
假设你要基于 Coze（扣子）搭建一个自动化内容生产系统。想法很直接：用 API 创建几个工作流，每天自动跑一次，出结果后推到公众号。听起来没什么特别的，对吧？
然后你翻文档，调 API，发现一个尴尬的事实：
Coze API 不能创建工作流。
不只是创建——不能编辑、不能删除、不能管理知识库、不能配置插件。Coze 的 REST API 是”只读+执行”接口，所有写操作都要在网页上手动完成。
这不是文档没写清楚，这是 API 的设计定位问题。这篇文章把所有”能做”和”不能做”一次性讲清楚，外加 5 个实测踩坑。
Coze API 能做什么
先讲能做的，不然显得这 API 什么用都没有。
查询类
- 列出工作流列表（
GET /v1/workflows） - 查看已发布智能体（
GET /v1/space/published_bots_list） - 查询对话状态和消息历史
执行类
- 执行工作流：非流式（
/v1/workflow/run）和流式 SSE（/v1/workflow/stream_run） - 发起智能体对话（
/v3/chat，异步，需要轮询结果）
工作流节点能力
工作流内部的能力是完整的：LLM 节点（支持豆包和自定义 OpenAI 兼容模型）、知识库检索（1GB 免费）、插件调用、Code 节点（Python/JS）、条件判断、变量传递、并行节点。
所以你可以在 Coze 里搭一个复杂的工作流，然后用 API 触发它、获取结果。核心价值在这里。
Coze API 不能做什么（核心 8 条）
这才是重点。以下限制不搞清楚，项目做到一半才发现才是真痛苦。
1. API 不能创建/编辑/删除工作流和智能体
这是最大的能力边界。Coze REST API 没有写操作端点：
❌ POST /v1/workflows — 不存在
❌ PUT /v1/workflows/{id} — 不存在
❌ DELETE /v1/workflows/{id} — 不存在
❌ POST /v1/bots — 不存在
❌ PUT /v1/bots/{id} — 不存在
所有创建和修改操作必须在 coze.cn 网页上手动完成。备选方案有 Coze CLI（@coze/cli，支持 create --type workflow）或者用 Playwright 做浏览器自动化，但都不算轻量。
这意味着你不能构建一个”全自动的 Coze 工作流管理平台”。API 只对”已存在的、已发布的工作流”生效。
2. 工作流必须先发布才能用 API 调用
这是个很隐蔽的坑。你刚搭好一个工作流，用 API 调它——报 code: 4000 Invalid request parameters。不是参数写错了，是因为工作流是”草稿”状态。
每次修改工作流后，必须在网页上点「发布」，API 才能调最新版本。 这是个容易漏掉的操作，特别是在迭代阶段频繁修改工作流时。
3. 执行时长限制
工作流执行建议不超过 5 分钟，超时自动终止。所以重型计算任务（视频编码、大规模数据处理）不适合走工作流。
4. 免费版硬限制
免费版每天 100 次 API 调用，超出直接停，不扣费也不降级。知识库容量 1GB。商用必须升级到个人进阶版或企业版。
5. 对话 API 是异步的
# 发起对话 → 拿到 chat_id → 轮询结果
POST /v3/chat → 返回 chat_id
# 不能立即获取回复
GET /v3/chat/retrieve?conversation_id=xxx&chat_id=xxx # 轮询直到 completed
GET /v3/chat/message/list # 获取消息
不支持同步等待，不支持 WebSocket 实时推送，不支持打断正在执行的对话。
6. 不能管理知识库
上传、删除文档必须在网页操作。API 没有知识库管理端点。
7. 不能管理插件配置
插件的添加、配置、删除同样只能在网页上完成。
8. 不支持 GPU 计算和系统级工具
工作流不能跑 ffmpeg、OpenCV 这类系统级工具。没有 GPU 资源。不能访问本地文件系统或内网服务。
踩坑实录
五个实测踩坑，每个都是翻过文档才搞清楚的。
踩坑 1：parameters 必须是 JSON 对象，不是字符串
官方文档说 parameters 是 JSON 字符串——实测传字符串报 4000。正确做法是直接传 Python dict：
# ❌ 按文档写的
json={"parameters": '{"key": "val"}'} # 报 4000
# ✅ 实测可行
json={"parameters": {"key": "val"}} # 传 dict
踩坑 2：列出工作流必须带 page_num
# ❌ 漏参数
GET /v1/workflows?workspace_id=xxx # 报错
# ✅ 正确
GET /v1/workflows?workspace_id=xxx&page_num=1&page_size=20
踩坑 3：space_id vs workspace_id 命名混乱
列出智能体用 space_id，列出工作流用 workspace_id，但它们指向同一个值：
# 名字不同，值相同
GET /v1/space/published_bots_list?space_id=7644825698909634611
GET /v1/workflows?workspace_id=7644825698909634611
踩坑 4：v1 和 v3 API 混用
管理工作流用 v1，调用对话用 v3，新手很容易搞混。建议按功能分类记忆：v1 是管理和执行，v3 是对话。
踩坑 5：Bot ID 不是智能体名称
Bot ID 是 URL 中 /bot/ 后面的数字（如 7348293334），不是智能体的名称或别名。必须在智能体开发页的 URL 中获取。
跟竞品比一下
| 维度 | Coze | n8n | Dify |
|---|---|---|---|
| API 创建工作流 | ❌ 不能 | ✅ 完整 REST | ✅ 支持 |
| 自托管 | ⚠️ 部分开源 | ✅ 成熟 | ✅ 完全开源 |
| 定位 | AI 智能体平台 | 系统自动化 | AI 应用开发 |
| 自定义代码 | ✅ Code 节点 | ✅ Function 节点 | ✅ |
Coze 在字节生态集成上有天然优势（抖音、飞书），但在 API 完整度上不如 n8n 和 Dify。
总结
Coze API 的核心定位是”触发和执行”——你在网页上搭好工作流和智能体，API 负责调它们、拿结果。它不是一个能完全编程管理的平台。
适合用 Coze API 的场景：已有 Coze 工作流，需要从外部系统触发执行；需要将 Coze 智能体集成到自有应用中；需要流式响应的实时交互场景。
不适合用 Coze API 的场景：需要全自动创建和管理工作流；需要工作流跑重型计算；需要低延迟的实时对话。
如果你正在评估 Coze API，先问自己一个问题：你的工作流搭好之后，还需要不需要改？如果不需要频繁改，Coze API 很好用。如果需要频繁创建和修改，那 Coze API 不是正确答案。