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 'https://open.vectcut.com/cut_jianying/execute_workflow' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "inputs": { "text": { "word": { "word": { "word": { "word": "Hello!" } } } }, "start": [0, 1, 2, 3], "end": { "time1": [ { "start": 5.0, "end": 10.0 }, { "start": 10.0, "end": 15.0 } ] } }, "script": [ { "type": "action", "id": "uuid_1", "index": 0, "action_type": "add_text", "params": { "text": "${text.word.word.word.word}", "start": "${start[3]}*${start[2]}", "end": "${end.time1[1].start}+20", "track_name": "text_main", "font_size": 8.0, "font_color": "#FF0000" } }, { "type": "action", "id": "uuid_2", "index": 1, "action_type": "add_text", "params": { "text": "draft_id_${uuid_1.draft_id}_123", "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你333好，我是孙关南开发的剪映草稿助手。\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", "scale_x": 0.8, "scale_y": 0.8 } }, { "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" } } ] }'

{ "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. 一次完整调用流程