JianYingAPI
main
  • main
  • afanti
  1. 工作流
JianYingAPI
main
  • main
  • afanti
  • 默认模块
    • 一分钟,了解 流光剪辑!
    • 扣子工作流示例
    • 如何下载草稿
    • 在线预览草稿
    • 获取API Key
    • 使用工作流功能
    • 飞书智能表格示例
    • 直播间演示
    • 文本
      • 使用花字
      • 使用文字模版
      • 如何上传文字模板
      • get_text_intro_types
      • get_text_outro_types
      • get_text_loop_anim_types
      • get_font_types
      • add_text
      • add_subtitle
      • search_artist
      • add_text_template
    • 图片
      • get_intro_animation_types
      • get_outro_animation_types
      • get_combo_animation_types
      • add_image
    • 视频
      • add_video
    • 转场
      • get_transition_types
    • 蒙版
      • get_mask_types
    • 音频
      • get_audio_effect_types
      • add_audio
    • 关键帧
      • add_video_keyframe
    • 特效
      • get_video_character_effect_types
      • get_video_scene_effect_types
      • add_effect
    • 贴纸
      • search_sticker
      • add_sticker
    • 云渲染
      • generate_video
      • task_status
    • 工作流
      • 工作流脚本技术文档
      • 工作流 AI Prompt 提示词
      • execute_workflow
        POST
    • 模版/预设
      • 如何使用模版/预设功能
      • 如何上传模版
      • add_preset
    • 滤镜
      • add_filter
      • get_filter_types
    • create_draft
      POST
    • save_draft
      POST
    • get_duration
      POST
  1. 工作流

工作流脚本技术文档

本文档详细介绍了 Workflow脚本的结构、核心字段定义、变量管理以及流程控制机制,帮助用户构建灵活、强大的自动化工作流。

一、 脚本结构概览#

Workflow 脚本采用标准的 JSON 格式,包含两个顶层键:inputs (输入变量定义) 和 script (工作流步骤定义)。
{
    "inputs": {
        // 定义输入变量及其默认值
        "variable_name": "default_value",
        "segments": []
    },
    "script": [
        // 步骤列表,按顺序执行
        { ... step 1 ... },
        { ... step 2 ... },
        // ...
    ]
}

二、 核心概念:变量与引用#

2.1 显式变量引用机制#

为了区分字符串字面量和变量名,系统强制使用 ${} 包裹来显式引用所有变量和表达式。
类别格式示例描述
输入变量${variable_name}${first_image}引用在 inputs 中定义的变量。
步骤输出${step_id.output}${uuid_2.output}引用 ID 为 uuid_2 的步骤的执行结果。
循环变量${item} 或 ${index}${item.audio_url}在 for 循环内部,item 指当前元素,index 指当前索引(从 0 开始)。
表达式${expression}${total_duration} + ${uuid_2.output}包含变量和运算符的 Python 风格表达式。

2.2 变量类型与运算(基于 SimpleEval)#

表达式评估基于 Python 风格,使用 simpleeval 安全地执行算术和布尔运算。
类别运算符/关键词示例结果类型
算术运算+, -, *, /${a} + 5数字 (Int/Float)
比较运算==, !=, >, <, >=, <=${index} == 0布尔 (True/False)
逻辑运算and, or, notnot ${scale_big}布尔 (True/False)
列表/字典索引 ([]), 属性 (.)${segments}[0], ${item.audio_url}混合

三、 脚本步骤定义(script 数组)#

所有步骤对象都必须包含 type、id 和 index 字段。

3.1 步骤通用字段定义#

字段类型是否必须描述
typeString是步骤的类型,决定执行什么操作。枚举见下表。
nameString否用于用户界面展示的步骤名称(通常用于 set_var)。
idString是步骤的唯一标识符。用于在后续步骤中引用其输出(如 ${uuid_2.output})。
indexNumber是执行顺序优先级。 步骤将按此字段升序执行。相同 index 的步骤按其在数组中的自然顺序执行。

3.2 步骤类型枚举(type)#

Type描述必需字段主要用途
set_var设置或更新一个工作流变量。name, value状态管理,计数器,布尔标志。
action调用一个外部功能/原子操作。action_type, params调用视频编辑 API、获取时长等。
if实现条件分支逻辑。condition, then根据条件跳转执行不同的步骤。
for实现循环迭代逻辑。in, loop遍历列表(如视频片段)执行重复操作。
break立即终止当前 for 循环。无跳出循环。

四、 流程控制详解#

4.1 赋值与变量管理 (type: set_var)#

该步骤用于在工作流运行时创建和更新变量。
字段类型必需描述
nameString是要设置的变量名。
valueString/Number是变量的新值。通常需要使用 ${} 来计算表达式。
示例 (累加总时长并取反布尔值):
[
    // 1. 累加总时长
    {
        "type": "set_var",
        "name": "total_duration",
        "value": "${total_duration} + ${uuid_2.output}", 
        "index": 6
    },
    // 2. 布尔变量取反
    {
        "type": "set_var",
        "name": "scale_big",
        "value": "not ${scale_big}", // 必须使用 'not' 关键字
        "index": 5
    }
]

4.2 条件分支 (type: if)#

if 步骤用于根据布尔条件选择性地执行一组步骤。
字段类型必需描述
conditionString是必须是一个计算结果为 True 或 False 的表达式。
thenArray是当 condition 为 True 时执行的步骤列表。
elseArray否当 condition 为 False 时执行的步骤列表。
示例 (判断是否是第一个片段):
{
    "type": "if",
    "condition": "${index} == 0", // 使用循环变量 index
    "id": "uuid_4",
    "index": 3,
    "then": [
        // index == 0 时执行的步骤 (例如添加片头)
        { "type": "action", ... } 
    ],
    "else": [
        // index != 0 时执行的步骤
        { "type": "action", ... }
    ]
}

4.3 循环控制 (type: for)#

for 步骤用于迭代列表、字典或数字范围,并重复执行内部的步骤序列。
字段类型必需描述
inString是必须是一个引用列表变量的表达式,例如 ${segments}。
loopArray是在每次迭代中执行的步骤列表。
item_nameString否循环内代表当前元素的变量名 (默认: item)。
index_nameString否循环内代表当前索引的变量名 (默认: index)。
示例 (遍历 segments 列表):
{
    "type": "for",
    "in": "${segments}", // 遍历输入的 segments 列表
    "id": "uuid_1", 
    "index": 1, 
    "loop": [
        // 在这里,可以使用 ${item} 和 ${index}
        {
            "type": "action",
            "action_type": "add_audio",
            "params": "{\\"audio_url\\":\\"${item.audio_url}\\"}" // 引用当前元素的属性
        },
        // ... 其他步骤
    ]
}

4.4 外部动作调用 (type: action)#

action 步骤用于调用预定义的外部功能(例如视频编辑 API)。
字段类型必需描述
action_typeString是要执行的具体操作类型。(由系统定义,例如 add_image, get_duration 等)。
paramsString是包含操作所需参数的 JSON 字符串。内部的变量必须使用双反斜杠进行转义 (\\")。
示例 (添加图片并引用步骤输出):
{
    "type": "action",
    "action_type": "add_image",
    "id": "uuid_3", 
    "params": "{\\"image_url\\":\\"${item.image_url}\\",\\"start\\":\\"${total_duration}\\",\\"end\\":\\"${total_duration} + ${uuid_2.output}\\"}"
    // 注意:${uuid_2.output} 是前一步骤 get_duration 的执行结果
}

五、剪辑操作(Action)与剪辑参数#

当步骤类型 (type) 设置为 action 时,系统将调用一个预定义的剪辑操作来执行具体的剪辑任务。您需要通过填写 params 字段来设置该操作的所有配置参数。
核心提示:
由于每个剪辑操作(如添加文本、视频或关键帧)都拥有相当复杂的参数配置,强烈建议您在使用前查阅相应操作的详细参数文档,以确保参数设置的正确性。

支持的剪辑操作 (action_type 枚举)#

Action Type描述文档链接
add_text在视频上添加静态或动态文本。add_text
add_subtitle添加字幕轨道,通常用于显示音频或视频内容对应的文本。add_subtitle
add_text_template添加基于预设样式的文本模板(如标题卡、动态文字效果)。add_text_template
add_image将图片添加到时间线上的特定轨道和时间段。add_image
add_video将视频素材添加到时间线上的特定轨道和时间段。add_video
add_audio将音频素材添加到时间线上的特定轨道和时间段。add_audio
add_video_keyframe为时间线上已有的素材(图片/视频)添加关键帧动画。add_video_keyframe
add_effect为时间线上的素材或整个视频添加视觉效果或滤镜。add_effect
add_sticker添加动态贴纸或装饰性元素。add_sticker
get_duration获取指定媒体文件(音频或视频)的精确时长。video_url 或 audio_urlget_duration

params 字段格式说明#

示例:使用变量引用设置 add_audio 的参数
"params": "{\"audio_url\":\"${item.audio_url}\",\"target_start\":\"${total_duration}\"}"
一些常用的params我必须要给你说明白。
时间单位都是秒,精确到小数点后6位,例如
"params": "{\"start\":1.234}"
对于音频add_audio/视频add_video接口,因为素材有原始时长,所有有四个时间参数容易搞混
duration: 原始素材的时长,例如5秒
start: 从原始素材的截取开始时间戳,例如1秒,表示从原始素材的第1秒开始截取
end: 从原始素材的街区结束的时间戳,例如2秒,表示截取到原始素材的第2秒
target_start: 表示插入目标轨道的起始时间
需要注意默认画布是1920(高)x1080(宽)
需要注意transform_x, transform_y分别对应画布宽和高的相对值,实际像素值=transform_xheight,或者transform_ywidth

六,支持的文字字体,入场动画,出场动画,转场动画,特效#

如果不清楚可以去这里查:
https://docs.capcutapi.top/321242300e0
https://docs.capcutapi.top/321242330e0
https://docs.capcutapi.top/321242352e0
https://docs.capcutapi.top/321241595e0
https://docs.capcutapi.top/321181567e0
https://docs.capcutapi.top/321183440e0
https://docs.capcutapi.top/321183634e0
https://docs.capcutapi.top/321183893e0
https://docs.capcutapi.top/321197911e0

七, 目前工作流不支持直接云渲染#

不要直接在工作流里调用云渲染。目前可以利用工作流的返回值draft_id,然后再调用generate_video去渲染
修改于 2025-10-25 14:59:19
上一页
task_status
下一页
工作流 AI Prompt 提示词
Built with