本文为您详细介绍如何调用 StartExecution 接口提交异步的高光智剪任务。该接口基于大模型视频理解技术，支持对单个或多个短剧、游戏视频进行智能分析，精准识别并提取精彩瞬间，并可根据配置自动生成带有营销元素的混剪成片。

使用说明

调用准备：在调用本接口前，建议您先阅读如何调用 OpenAPI 文档，以了解 OpenAPI 的通用调用流程，包括在线调试、获取 curl 命令、请求签名等基础操作。

核心业务场景与模型选择：

短剧模型 (Model: Miniseries)：适用于短剧、电影等剧情类内容。推荐使用 StorylineCuts 模式，系统会结合故事线逻辑进行片段提取。如需快速产出带投放美化效果的视频，建议开启 MiniseriesEdit 模式以一键添加“短剧三要素”。

小游戏模型 (Model: Game)：适用于游戏录屏内容。您需通过 MiniGame 参数描述游戏特征，系统将据此识别击杀、通关等高光时刻。注意该模型目前不支持多输入。

结果获取方式：任务提交后，系统将在后台进行异步处理。您可以通过以下任一方式获取任务的最终结果：

主动查询：调用 GetExecution，传入 RunId 来轮询任务状态。若任务成功且您配置了 Edit，可在 Output.Task.Highlight.Edits 数组中获取产物 FileName。

事件通知：配置事件通知并订阅媒体处理任务执行完成事件，任务完成后系统将主动向您配置的地址发送回调通知。

注意事项

计费说明：提交任务会产生视频 AI 费用，具体参见视频 AI 应用计费。

QPS 限制：本接口的单用户 QPS 限制为 50 次/秒。超过限制，API 调用会被限流，这可能会影响您的业务，请合理调用。更多信息，请参见 QPS 限制。

请求说明

请求方式：POST

请求地址：https://vod.volcengineapi.com?Action=StartExecution&Version=2025-01-01

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共请求参数。

Query

Action String 必选示例值：StartExecution

接口名称。当前 API 的名称为 StartExecution。

Version String 必选示例值：2025-01-01

接口版本。当前 API 的版本为 2025-01-01。

Body

Input Object 可选示例值：-

输入文件信息。

Type String 必选示例值：Vid

输入文件类型。取值如下：

Vid：Vid 模式。此模式下，您还需设置 Vid 参数。

DirectUrl：DirectUrl 模式。此模式下，您还需设置 DirectUrl 参数。

Vid String 可选示例值：v0ccfeg7007acsg***fog65ubr7niqng

待处理视频的 Vid。您需要在调用本接口前，通过任一方式将视频上传至点播空间，并获取其 Vid。

注意

您必须设置 Vid 或 DirectUrl参数之一，但不能同时设置这两个参数。

DirectUrl Object 可选示例值：-

通过 DirectUrl 模式指定待处理视频的信息。您需要在调用本接口前，通过任一方式将视频上传至点播空间，并获取其相关信息。

注意

您必须设置 Vid 或 DirectUrl参数之一，但不能同时设置这两个参数。

SpaceName String 必选示例值：test

空间名称。可调用 ListSpace 获取当前账号下所有空间的信息。

FileName String 必选示例值：example.mp4

文件路径。音视频上传至视频点播服务后，您可通过媒资上传完成事件获取 FileName。

BucketName String 可选示例值：tos-cn-v-cd3a11

存储桶名称。可调用 ListSpace 获取空间所绑定的存储桶名称。

MultiInputs Object[] 可选示例值：-

输入文件信息数组。

注意

您必须设置 Input 或 MultiInputs 参数之一，但不能同时设置这两个参数。

仅高光智剪和长视频故事线分析任务支持多个输入文件。

单次任务最多输入 30 个文件。

多个输入文件的类型必须保持一致。

若为 Vid 类型，这些文件需来自同一个空间。

若为 DirectUrl类型，文件则需来自同一个空间。

Type String 必选示例值：Vid

输入文件类型。取值如下：

Vid：Vid 模式。此模式下，您还需设置 Vid 参数。

DirectUrl：DirectUrl 模式。此模式下，您还需设置 DirectUrl参数。

Vid String 可选示例值：v0ccfeg7007acsg***fog65ubr7niqng

视频 ID。音视频上传至视频点播服务后，您可通过媒资上传完成事件获取 Vid。

注意

您必须设置 Vid、DirectUrl参数之一，但不能同时设置这两个参数。

DirectUrl Object 可选示例值：-

通过 DirectUrl 模式指定待处理视频的信息。您需要在调用本接口前，通过任一方式将视频上传至点播空间，并获取其相关信息。

注意

您必须设置 Vid 或 DirectUrl参数之一，但不能同时设置这两个参数。

SpaceName String 必选示例值：test

空间名称。可调用 ListSpace 获取当前账号下所有空间的信息。

FileName String 必选示例值：example.mp4

文件路径。音视频上传至视频点播服务后，您可通过媒资上传完成事件获取 FileName。

BucketName String 可选示例值：tos-cn-v-cd3a11

存储桶名称。可调用 ListSpace 获取空间所绑定的存储桶名称。

Operation Object 必选示例值：-

媒体处理操作配置。

Type String 必选示例值：Task

处理类型。取值如下：

Task：单任务。

Task Object 可选示例值：-

单任务配置。当 Type 为 Task 时需要设置此参数。

Type String 必选示例值：Highlight

任务类型：

Highlight: 高光智剪任务。

Highlight Object 可选示例值：-

高光智剪任务配置。当 Type 为 Highlight时需要设置此参数。

Model String 可选示例值：Miniseries

高光智剪任务所使用的模型类型，用于指定视频内容的分析模式。支持的取值如下：

Miniseries：（默认）短剧模型。

Game: 游戏模型。本模式不支持多输入。

Mode String 必选示例值：StorylineCuts

高光智剪任务的模式：

当 Model 为 Miniseries 时，支持以下取值：

StorylineCuts：故事线混剪模式，在高光片段模式基础上融入故事线信息。

当 Model 为 Game 时，支持以下取值：

MiniGame：小游戏模式

Edit Object 可选示例值：-

剪辑成片配置。仅当 Mode 为 StorylineCuts 时生效。配置此参数后，系统将在高光分析完成后，直接基于分析结果自动剪辑并输出高光视频，而不仅仅是返回分析数据。

Mode String 必选示例值：HighlightClips

剪辑模式。支持以下取值：

HighlightClips：智能片段剪辑模式。系统将自动应用一套默认的剪辑参数，快速生成效果均衡的高光集锦视频。此模式无需额外配置。

CustomEdit: 自定义剪辑模式。您可以通过 CustomEdit 参数，详细自定义最终输出视频的编码、分辨率等。

MiniseriesEdit：短剧三要素模板剪辑。使用预设的视觉模板，为高光视频一键添加“短剧三要素”（剧名、角标、提示语）。

注意

“短剧三要素”（MiniseriesEdit 模式）仅适用于竖屏短剧，暂不支持横屏剧。

CustomEdit Object 可选示例值：-

自定义剪辑参数。当 Mode 为 CustomEdit 时，此参数为必填，用于详细配置最终输出视频的参数。

Output Object 可选示例值：-

编码输出配置。用于配置最终输出视频的编码格式、码率、帧率、分辨率等参数。

Alpha Boolean 可选示例值：false

输出视频中是否包含 alpha 通道。默认值为 false。

说明

Alpha 的优先级高于 VideoCodec。当 Alpha 为 true 时，VideoCodec 默认采用 VP9，而不再关注您设置的 VideoCodec参数。

Format String 可选示例值：mp4

输出文件的封装格式。取值如下：

（默认）mp4

hls

mp3

说明

Format 的优先级高于 VideoCodec。

当 Format 设为 hls 时，表示以 HLS 格式输出视频，此时 VideoCodec 仅支持设为 h264 和 h265。

当 DisableVideo 参数取值为 true 时，Format 取值为 mp3才生效，表示 MP3 音频导出专用格式。

Fps Double 可选示例值：30

输出视频的帧率。单位为 fps。默认值为 30。

Codec Object 可选示例值：-

音视频编码参数设置。

VideoCodec String 可选示例值：h264

视频编码格式。取值如下：

h264: （默认）H.264

vp9: VP9

h265: H.265

Preset String 可选示例值：medium

用于调节视频编码速度和质量。默认值为 medium。仅当 VideoCodec 设为 h264、h265 时生效。

Crf Integer 可选示例值：23

恒定质量因子 CRF。默认值为 23。

说明

仅当 VideoCodec 设为 h264、h265时生效。

VideoBitRate Integer 可选示例值：2000

视频编码码率。单位为 bps。该参数如不设置，视频编码码率通过 Crf 控制。设置该参数后，Crf 设置不生效。

AudioCodec String 可选示例值：aac

音频编码格式。默认值为 aac。支持的取值有 aac。

AudioBitrate Integer 可选示例值：128

音频编码码率。默认值为 128。单位为 kbps。

DisableVideo Boolean 可选示例值：false

是否仅输出音频：

false: （默认）输出音视频。

true: 仅输出音频。

说明

DisableVideo 和 DisableAudio 同时设为 false时，最终输出一个完整的音视频文件。

DisableAudio Boolean 可选示例值：false

是否仅输出视频：

false: （默认）输出音视频。

true: 仅输出视频。

CanvasWithMax Boolean 可选示例值：false

画布分辨率是否遵循最大分辨率。默认为 false。如设为 true，画布分辨率与资源中的最大分辨率保持一致。

说明

最大分辨率是指宽*高的值在所有资源中最大。画布分辨率相关参数的优先级按以下顺序递减：

Int 型的 Canvas.Width 和 Canvas.Height

CanvasWithMax

CanvaswithRatio

String 型的 Canvas.Width 和 Canvas.Height

CanvasWithRatio Boolean 可选示例值：false

画布分辨率是否遵循长短边比。默认为 false。如设为 true，画布分辨率保持固定的长短边比。长短边比默认为 16:9。您也可以通过 Canvas 中的 Long、Short、Ratio 参数设置长、短边以及长短边比。

AudioPhaseDetect Boolean 可选示例值：false

是否进行音频反相检测。默认关闭。当片源时长较长时，该操作较为耗时。

Canvas Object 可选示例值：-

渲染画布配置。用于定义最终输出视频的宽高、背景色等参数。

Width Integer 可选示例值：720

输出视频的宽。单位为 pixel，默认值为 720。取值范围为 [160,8192]。

说明

Canvas 还支持通过表达式来自动匹配某个 Element 的宽和高。具体请见通过表达式指定画布宽高。

Height Integer 可选示例值：1280

输出视频的高。单位为 pixel，默认值为 1280。取值范围为 [160,8192]。

BackgroundColor String 可选示例值：#FF0000FF

画布颜色。RGBA 类型，默认值为 #00000000。

Long Integer 可选示例值：1280

输出视频画布的长边。单位为 pixel，默认值为 1280。取值范围为 [160,8192]。

注意

此参数仅当 CanvasWithRatio 为 true时生效。

Short Integer 可选示例值：720

输出视频画布的短边。单位为 pixel，默认值为 720。取值范围为 [160,8192]。

注意

此参数仅当 CanvasWithRatio 为 true 时生效。

同时设置短边和长边时，短边的优先级高于长边。

Index String 可选示例值：0|0

设置输出视频画布的屏幕方向（横屏还是竖屏）与哪个资源保持一致。默认值为 0|0，即对齐第 0 个 Track 的第 0 个 Element。当 Index 设为 MAX 时，则表示跟随基准分辨率，也就是与资源中的最大分辨率保持一致。

注意

此参数仅当 CanvasWithRatio 为 true时生效。

Ratio String 可选示例值：16:9

输出视频画布的长短边比，默认值为 16:9。当 Ratio 设为 -1:-1 或者 -1，则表示跟随指定输入源。

注意

此参数仅当 CanvasWithRatio 为 true时生效。

MiniseriesEdit Object 可选示例值：-

短剧模板剪辑模式的详细参数。当 Mode 为 MiniseriesEdit 时，此参数为必填。

Template String 必选示例值：热门短剧1

“短剧三要素”视觉模板名称。不同的模板决定了剧名、角标、提示语的位置和样式。支持的取值如下：

热门短剧1

热门短剧2

热门短剧3

热门短剧4

热门短剧5

说明

具体效果，请见短剧三要素视觉模板。

Title String 可选示例值：《短剧名称》

短剧名称。在高光视频画面上展示剧名，用于品牌识别和引导用户搜索。不得超过 22 个字。

Hint String 可选示例值：影视效果请勿模仿

短剧提示语。画面左右两侧的一行文字，可以是概括视频核心冲突或亮点的引导性文字，也可以是类似“影视效果请勿模仿无不良价值观引导”的免责声明。不得超过 20 个字。

HighlightCuts Object 可选示例值：-

高光片段配置。仅当 Model 取值为 Miniseries 且 Mode 为 StorylineCuts时生效。

WithStoryboard Boolean 可选示例值：true

是否在任务结果中输出详细的分镜信息。取值如下：

true：系统会在高光分析结果中包含 Storyboard 数组，输出算法基于分镜理解得出的视频片段信息。每个片段涵盖片段开始时间、结束时间、高光打分、字幕信息、剧情描述以及片段源自哪个输入视频等信息。

false：（默认）不输出分镜信息。

MinDuration Double 可选示例值：60

期望输出高光视频的最小时长，单位为秒，默认值为 90。

注意

在实际高光分析过程中，为确保剧情的连贯性并保留“钩子”剧情，算法所输出高光视频的时长可能不会与您所设置的 MinDuration 和 MaxDuration严格相符。

MaxDuration Double 可选示例值：180

期望输出高光视频的最大时长，单位为秒。默认值为 300。若您指定最大时长，系统会将混剪结果截断至合适长度，可能不会使用全部输入视频片段。

MaxNumber Integer 可选示例值：1

输出高光视频的最多个数，默认值为 6。

MiniseriesOption Object 可选示例值：-

短剧场景下的专属配置，目前用于指定剪辑模式（顺剪/混剪）。仅在短剧模型下生效。

CutMode String 可选示例值：Mixed

剪辑模式，决定了视频片段的组织方式。支持的取值如下：

Mixed：（默认）混剪模式。算法会打乱原始时序，优先组合最精彩、最具冲突感的片段，以达到最佳营销效果。

Sequential：顺剪模式。算法会基本保持原始剧情的时间顺序进行剪辑（去除片头片尾等非正片内容）。

OpeningHook Object 可选示例值：-

精彩前置功能配置。开启精彩前置功能后，系统将自动分析并提取视频中最精彩的片段，将其置于视频开头，以吸引观众。仅当 Model 取值为 Miniseries 且 Mode 为 StorylineCuts时生效。

WithOpeningHook Boolean 可选示例值：true

是否启用精彩前置功能：

true: 开启精彩前置功能。系统将自动分析并提取视频中最精彩的片段，将其置于视频开头，以吸引观众。

false:（默认）关闭精彩前置功能。

MinDuration Double 可选示例值：5

视频开头精彩片段的最小时长，单位为秒，默认为 5。

MaxDuration Double 可选示例值：15

视频开头精彩片段的最大时长，单位为秒，默认值为 15。

MinClipDuration Double 可选示例值：5

设置构成视频开头精彩片段的单个高光片段的最小持续时长。单位为秒，默认值为 5。视频开头的精彩片段可能会由多个高光片段拼接而成。此参数用于避免因拼接过多过短片段而导致的画面频闪问题，以确保最终成片的视觉流畅性。

注意

请确保 MinClipDuration 大于 MinDuration，否则可能会导致输出多个独立的前置精彩片段。

MinScore Double 可选示例值：3

设置构成视频开头精彩片段的单个高光片段的高光打分下限，默认值为 3。视频开头精彩片段可能会由多个高光片段拼接而成，此参数用于筛选高质量片段以确保开场效果。

MiniGame Object 可选

小游戏分析配置。仅当 Model 取值为 Game 且 Mode 取值为 MiniGame 时生效。

Name String 可选示例值：王XX耀

游戏名称，用于在高光智剪任务中标识游戏内容，最大长度为 5000 个字符。

PlayDefinition String 可选示例值：玩家需要控制角色在限定时间内完成指定任务，通过收集道具和击败敌人来获得分数。

游戏玩法描述，用于在高光智剪任务中详细说明游戏的玩法规则或特点，最大长度为 5000 个字符。

HighlightDefinition String 可选示例值：玩家在游戏中连续击败多名对手，完成五杀操作，展现出极高的操作技巧和反应速度。

高光描述，用于在高光智剪任务中详细说明游戏中的高光时刻或精彩瞬间，最大长度为 5000 个字符。

Control Object 可选示例值：-

任务控制配置。

ClientToken String 可选示例值：QqS3o5L4BLFCDxGZ&b

用户请求凭证，用于区分不同请求。大小写敏感，不超过 64 个 ASCII 码可打印字符。默认情况下，视频点播转码服务在接收到触发工作流请求后，会执行幂等行为。这意味着，如果判定当前请求与之前发送的请求相同，则不会重复执行该请求。关于幂等行为、目的和条件，请参考工作流幂等说明。若您希望跳过幂等行为，例如修改了某一工作流所绑定的媒体处理模板中的配置，想要对同一个 Vid 重新执行相同的工作流，则可以设置此参数。

CallbackArgs String 可选示例值：Example

自定义字段，将在媒体处理任务执行完成事件中透传返回。字段长度最大为 512 字节。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见公共返回参数。

RunId String 示例值：hb:c5cacd4946bd***a5fd9f74159b03ae8

媒体处理任务执行 ID。

示例 1：短剧高光智剪

基于多个 Vid 输入，提交故事线混剪模式的高光智剪任务，并开启精彩前置。

示例 2：小游戏高光智剪

通过单个 Vid 提交小游戏模式的高光智剪任务，并传入游戏相关描述信息。

错误码

本接口无特有的错误码。更多信息请见公共错误码。

服务端 SDK

视频点播为 OpenAPI 提供了配套的服务端 SDK，支持多种编程语言，帮助您实现快速开发。建议使用服务端 SDK 来调用 API。本接口仅 VOD SDK 2.0 支持，详见 V2.0 SDK 介绍与迁移说明。