execute_workflow

这套接口的目标是：你提交一次工作流定义（或 workflow_id），服务端就会执行脚本并返回执行结果（通常包含草稿信息或步骤输出）。

它尤其适合批量、循环编排场景，例如：

给所有字幕批量设置统一样式（字体、颜色、描边、动画等）。

循环添加大量素材（如一次性添加 100 张图片）。

相比在客户端循环调用多个原子接口，工作流接口能减少请求次数和网络往返，通常整体耗时更短、执行速度更快。

1. 我该怎么传参数（按场景）

你可以用两种方式调用：

方式 A：直接传完整工作流（inputs + script），适合临时执行、调试流程。

方式 B：只传 workflow_id，适合线上复用已保存工作流。

2. 我需要输入什么

2.1 执行工作流

请求体：

直接传原始 JSON 文本（Raw Body），接口会把整个 body 当成 workflow_json。

inputs：输入参数区，放可复用变量（如文案、素材列表、样式参数）。你可以在 script 里通过 ${inputs.xxx} 引用。

script：执行步骤区，定义具体怎么做（动作顺序、循环、条件等），是工作流真正的执行逻辑。

workflow_id：已保存工作流的标识；传它可以复用线上工作流配置，不必每次传完整 script。

最小可用示例（方式 A，直接传工作流）：

{
  "inputs": {
    "title": "你好世界"
  },
  "script": [
    {
      "type": "action",
      "id": "step_1",
      "index": 0,
      "action_type": "add_text",
      "params": {
        "text": "${inputs.title}"
      }
    }
  ]
}

最小可用示例（方式 B，按 workflow_id 执行）：

{
  "workflow_id": "your_workflow_id"
}

3. 我能拿到什么结果

接口返回结构固定，HTTP 状态码统一为 200，通过 success 判断成功失败。

成功时示例：

{
  "success": true,
  "output": {
    "draft_id": "xxxxxxxx",
    "draft_url": "https://..."
  },
  "error": "",
  "purchase_link": "https://www.vectcut.com"
}

失败时示例：

{
  "success": false,
  "output": "",
  "error": "缺少必要的workflow_json参数",
  "purchase_link": "https://www.vectcut.com"
}

4. 常见报错与处理建议

缺少必要的workflow_json参数：请求体为空，需传入原始 JSON 文本。

未找到ID为xxx的工作流：workflow_id 不存在，或当前用户无权限读取该工作流。

无效的JSON格式: ...：传入 JSON/JSON5 结构不合法，或字段类型不符合执行要求。

执行工作流失败: ...：执行阶段异常，建议保留完整请求体与错误信息排查。

5. 一次完整调用流程

准备调用方式：传完整工作流，或只传 workflow_id。

组装 POST 请求，body 传原始 JSON 文本。

收到响应后先看 success，成功则读取 output，失败则处理 error。

curl --location --request POST 'https://open.vectcut.com/cut_jianying/execute_workflow' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "inputs": { "text": "Hello!", "start": 0, "end": 15.0 }, "script": [ { "type": "action", "id": "uuid_1", "index": 0, "action_type": "add_text", "params": { "text": "${text}", "start": "${start}", "end": "${end}", "track_name": "text_main", "font_size": "8.0", "font_color": "#FF0000" } }, { "type": "action", "id": "uuid_2", "index": 1, "action_type": "add_text", "params": { "text": "这是第二行文本", "start": "0", "end": "5.0", "track_name": "text_1", "transform_y": "0.3" } }, { "type": "action", "id": "uuid_3", "index": 2, "action_type": "add_subtitle", "params": { "srt": "1\\n00:00:00,000 --> 00:00:04,433\\n你好，我是孙观楠开发的剪映草稿助手。\\n\\n2\\n00:00:04,433 --> 00:00:11,360\\n我擅长将音频、视频、图片素材拼接在一起剪辑输出剪映草稿。\\n", "track_name": "subtitle_1", "font_size": "5.0" } }, { "type": "action", "id": "uuid_4", "index": 3, "action_type": "add_text_template", "params": { "template_id": "7373303725881822491", "start": "2.0", "track_name": "text_template_main" } }, { "type": "action", "id": "uuid_5", "index": 4, "action_type": "add_image", "params": { "image_url": "https://pic1.imgdb.cn/item/68ba8fc058cb8da5c8801ab0.png", "start": "5.0", "end": "10.0", "track_name": "image_main" } }, { "type": "action", "id": "uuid_6", "index": 5, "action_type": "add_video", "params": { "video_url": "https://cdn.wanx.aliyuncs.com/wanx/1719234057367822001/text_to_video/092faf3c94244973ab752ee1280ba76f.mp4?spm=5176.29623064.0.0.41ed26d6cBOhV3&file=092faf3c94244973ab752ee1280ba76f.mp4", "target_start": "10.0", "track_name": "video_main" } }, { "type": "action", "id": "uuid_7", "index": 6, "action_type": "add_audio", "params": { "audio_url": "https://lf3-lv-music-tos.faceu.com/obj/tos-cn-ve-2774/oYACBQRCMlWBIrZipvQZhI5LAlUFYii0RwEPh", "start": "0.0", "track_name": "audio_main", "volume": "0.8" } }, { "type": "action", "id": "uuid_8", "index": 7, "action_type": "add_video_keyframe", "params": { "track_name": "video_main", "time": "10.5", "property_type": "position_y", "value": "1" } }, { "type": "action", "id": "uuid_9", "index": 8, "action_type": "add_video_keyframe", "params": { "track_name": "video_main", "time": "11.5", "property_type": "position_y", "value": "0.2" } }, { "type": "action", "id": "uuid_10", "index": 9, "action_type": "add_video_keyframe", "params": { "track_name": "video_main", "times": [ 10.5, 12.5 ], "property_types": [ "position_x", "position_x" ], "values": [ 1, -1 ] } }, { "type": "action", "id": "uuid_11", "index": 10, "action_type": "add_effect", "params": { "effect_category": "scene", "effect_type": "金粉闪闪", "start": "0", "end": "10", "track_name": "effect_01", "params": [ 100, 50, 34 ] } }, { "type": "action", "id": "uuid_12", "index": 11, "action_type": "add_sticker", "params": { "sticker_id": "7107529669750066445", "start": "20.0", "end": "25.0", "transform_y": "0.3", "transform_x": "-0.2", "alpha": "0.8", "rotation": "45.0", "scale_x": "1.5", "scale_y": "1.5", "track_name": "sticker_main" } }, { "type": "action", "id": "uuid_13", "index": 12, "action_type": "add_filter", "params": { "filter_type": "黑胶唱片", "start": 0, "end": 3, "track_name": "filter_1", "relative_index": 1, "intensity": 86 } } ] }'

{ "error": "", "output": { "draft_id": "dfd_cat_1760946180_fc9a8560", "draft_url": "https://cn.capcutapi.top/draft/downloader?draft_id=dfd_cat_1760946180_fc9a8560&is_capcut=0&api_key_hash=15b082f53a67b381693cc2c62982d3bf662463523721ca35544106af2d2bb57c" }, "purchase_link": "https://www.coze.cn/store/project/7498257920212647946?entity_id=1&bid=6g6miqtbk3009", "success": true }

1. 我该怎么传参数（按场景）

2. 我需要输入什么

2.1 执行工作流

3. 我能拿到什么结果

4. 常见报错与处理建议

5. 一次完整调用流程

请求参数

返回响应

execute_workflow

1. 我该怎么传参数（按场景）#

2. 我需要输入什么#

2.1 执行工作流#

3. 我能拿到什么结果#

4. 常见报错与处理建议#

5. 一次完整调用流程#

请求参数

返回响应

1. 我该怎么传参数（按场景）

2. 我需要输入什么

2.1 执行工作流

3. 我能拿到什么结果

4. 常见报错与处理建议

5. 一次完整调用流程