POST https://mediakit.cn-beijing.volces.com/api/v1/tools/generate-highlights-microdrama

本 API 用于提交一个异步的短剧高光智剪任务，按照对输入剧集的角色和剧情故事线理解，提取高光片段并按照剪辑要求（时长范围、产出个数、顺剪/跳剪等剪辑手法等）生成高光混剪、单集预告等多种混剪视频。

获取任务结果：任务提交成功后，您需要保存返回的 task_id，并通过轮询查询任务信息 API 或配置事件回调获取最终结果。

开发指南：如需了解完整的使用流程和应用示例，请参阅高光智剪-短剧。

请求参数

Header 参数

参数	类型	是否必选	示例值	描述
Authorization	String	是	Bearer {Your_API_Key}	格式为 Bearer {Your_API_Key}。请参考基础概念及准备工作获取 API Key。

Body 参数

参数	类型	是否必选	示例值	描述
video_urls	Array	是	["https://example.com/video1.mp4", "https://example.com/video2.mp4"]	待处理的短剧原片视频 URL 列表。视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, flv, ts, avi, mov, wmv, mkv 等主流视频格式。数量限制：单次任务最多支持传入 30 个视频文件。累计时长：所有输入文件的累计总时长不得超过 45 分钟。输入分辨率限制：最高支持 1080p。输入素材要求：必须同时包含视频流和音频流。视频画面要求：视频画面下半部分（垂直位置 0.5-1.0 范围内）必须包含清晰居中的中文字幕。音频流要求：视频的音频轨道中必须包含清晰可识别的中文对话文本。仅包含 BGM（含歌词）、纯音乐、语气词或无有效语义的声音，将无法准确识别剧情逻辑。
mode	String	是	StorylineCuts	短剧高光智剪模式。当前版本固定为 StorylineCuts（故事线混剪模式）。
enable_generate_video	Boolean	否	true	是否生成高光混剪视频。默认为 true。 true：生成并输出高光混剪视频。 false：不生成高光混剪视频。此时，您传入的 edit_param 将被忽略。
enable_return_poster	Boolean	否	true	是否在任务结果中返回混剪视频的封面图 URL。默认为 false。 true：在任务结果中返回混剪视频的封面图 URL（ poster_url）。 false：不返回封面图。
edit_param	Object	否	-	高光视频剪辑配置，用于控制最终输出视频的视觉风格。如果 enable_generate_video 为 false，此参数将被忽略。通过此参数，您可以选择是仅进行基础剪辑，还是应用包含剧名、角标等元素的“短剧三要素”视觉模板。如果留空，则默认使用基础剪辑模式。详见下文 edit_param 结构。
highlight_cuts_param	Object	否	-	高光智剪参数配置，用于控制最终输出视频的时长与个数。通过此参数，您可以定义输出视频的总时长和个数、剪辑模式（顺剪或混剪），以及是否需要输出详细的分镜信息。如果留空，则默认使用热门短剧1模板。详见下文 highlight_cuts_param 结构。
opening_hook_param	Object	否	-	精彩前置（开场钩子）功能参数配置，用于控制是否在视频开头添加一个极具吸引力的“钩子”片段来留住观众。您可以通过此参数开启或关闭该功能，并设置钩子片段的时长及筛选标准。如果留空，则默认在视频开头添加精彩前置片段。详见下文 opening_hook_param 结构。
video_ending_mode	String	否	SmartSelect	高光智剪视频结尾选取模式。可选值： ReuseMainEnding：（默认）优先复用正片剧集结尾。 SmartSelect：智能选取模式。
enable_segment_tag	Boolean	否	true	是否在任务结果中为高光片段和分镜返回标签。默认为 false。 true：在 result.mixvideo_info.clips 与 result.storyboard_info 中额外返回 tags 字段，可用于内容盘点、投放分组、素材检索等下游场景。 false：不返回 tags 字段。
media_output_destination	String	否	vod://my-space	指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶。存储至 VOD：设为 vod://<您的空间名> 存储至 TOS：设为 tos://<您的桶名> 设置本参数后，任务结果中的 url 相关字段将返回形如 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。说明首次使用此功能前，您需要先前往 AI MediaKit 控制台基础配置 > 授权管理页面，授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。更多信息，请参阅开发指南处理产物存储至 VOD 或 TOS。
client_token	String	否	your_unique_request_id_131	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考幂等性控制。
callback_args	String	否	your_unique_callback_args	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。
callback_url	String	否	https://example.com/callback	用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

edit_param 结构

参数	类型	是否必选	示例值	描述
mode	String	否	TemplateEdit	成片剪辑模式，决定是否使用视觉模板。默认为 BasicEdit。 BasicEdit：基础剪辑，不添加额外视觉元素。 TemplateEdit：模板剪辑，使用指定的“短剧三要素”视觉模板。
template_edit	Object	否	-	短剧模板剪辑参数。当 mode 为 TemplateEdit 时，此参数为必填项。详见下文 template_edit 结构。

template_edit 结构

参数	类型	是否必选	描述
template	String	否	“短剧三要素”视觉模板名称，决定剧名、角标、提示语的样式和位置。默认为热门短剧1。支持取值：热门短剧1 热门短剧2 热门短剧3 热门短剧4 热门短剧5 说明视觉效果请见使用“短剧三要素”视觉模板。
title	String	否	短剧名称，将显示在视频画面中。不超过 22 个字符。
hint	String	否	短剧提示语，将显示在画面左侧或右侧。不超过 20 个字符。

highlight_cuts_param 结构

参数	类型	是否必选	描述
enable_storyboard	Boolean	否	是否在任务结果中输出详细的分镜信息（storyboard_info）。默认为 false。
min_duration	Number	否	期望输出高光视频的最小时长（单位：秒）。默认为 30。注意算法最终输出的高光时长会尽量趋近于您设置的 min_duration 和 max_duration 范围，实际时长与设定值可能存在几秒钟的微小误差。
max_duration	Number	否	期望输出高光视频的最大时长（单位：秒）。默认为 180。
max_number	Integer	否	最多输出的高光视频数量。默认为 6。
cut_mode	String	否	剪辑模式。默认为 Mixed。 Mixed：混剪，打乱高光片段的原始顺序。 Sequential：顺剪，保持高光片段的原始时间顺序。
highlight_segment_prompt	String	否	高光片段选取标准。仅在混剪模式（cut_mode 为 Mixed）下生效。你可以用自然语言描述偏好，具体使用方式可参阅精细化引导混剪模式的高光选取。
highlight_start_prompt	String	否	高光混剪开头起播点选取标准。仅在混剪模式（cut_mode 为 Mixed）下生效。你可以用自然语言描述偏好，具体使用方式可参阅精细化引导混剪模式的高光选取。
highlight_ending_prompt	String	否	高光混剪结尾钩子选取标准。仅在混剪模式（cut_mode 为 Mixed）下生效。你可以用自然语言描述偏好，具体使用方式可参阅精细化引导混剪模式的高光选取。
user_preferred_segments	Array	否	用户期望优先选用的原片内容或片段。仅在混剪模式（cut_mode 为 Mixed）下生效。支持填写多个。详见下文 user_preferred_segments 结构。例如 user_preferred_segments 为 {"episode": 4, "start_time": 0, "end_time": 10} 表示优先选用输入第 5 个视频中的 0-10 秒的片段。具体使用方式可参阅精细化引导混剪模式的高光选取。

opening_hook_param 结构

参数	类型	是否必选	描述
enable_opening_hook	Boolean	否	是否启用精彩前置（开场钩子）功能。默认为 true。
min_duration	Number	否	开场钩子片段的最小时长（单位：秒）。默认为 5。
max_duration	Number	否	开场钩子片段的最大时长（单位：秒）。默认为 15。
min_clip_duration	Number	否	构成开场钩子的单个高光片段的最小持续时长（单位：秒）。默认为 5。
min_score	Number	否	构成开场钩子的单个高光片段所需达到的最低高光分。范围 [1, 5]，默认为 3。
opening_hook_prompt	String	否	精彩前置片段选取标准，用自然语言描述开头钩子的筛选偏好。具体使用方式可参阅示例：通过 opening_hook_prompt 精细化引导钩子选取。

user_preferred_segments 结构

参数	类型	是否必选	描述
episode	Integer	是	优先选用的输入视频序号，从 0 开始计数。仅含 episode 表示整集优先。
start_time	Number	否	优先片段在该输入视频中的起始时间（单位：秒）。与 end_time 一并提供时，表示该集指定时间区间优先。
end_time	Number	否	优先片段在该输入视频中的结束时间（单位：秒）。

请求示例

以下示例演示了如何对两集短剧视频进行高光智剪，使用“热门短剧1”模板，并要求返回分镜信息。

响应说明

任务提交成功响应

参数	类型	描述
success	Boolean	任务是否提交成功。 • true：成功。 • false：失败。更多信息请查看错误处理。
task_id	String	任务的唯一标识，用于后续查询任务状态和结果。
request_id	String	本次请求的唯一标识，可用于问题排查。

示例：

异步任务结果

任务处理完成后，通过查询任务信息 API 或事件回调获取的 result 字段将包含以下内容。

参数	类型	描述
duration	Number	输入视频的总时长（单位：秒）。
video_urls	Array	最终生成的混剪视频地址列表。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
mixvideo_info	Array	高光片段（Clip）的详细信息列表。详见下文mixvideo_info 结构。
storyboard_info	Array	详细的分镜信息列表。仅当请求中 enable_storyboard 为 true 时返回。详见下文 storyboard_info 结构。

mixvideo_info 结构

参数	类型	描述
mixvideo_index	Integer	混剪视频的索引，与 video_urls 数组中的位置一一对应，从 0 开始。
duration	Number	该混剪视频的时长，单位为秒。
size	Integer	该混剪视频的文件大小，单位为字节。
poster_url	String	该混剪视频对应的封面图 URL。仅当请求中 enable_return_poster 为 true 且算法成功生成封面时返回。
video_url	String	该项对应的混剪视频地址。如果 enable_generate_video 为 false 或底层未产生成片，此字段为空。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
clips	Array	构成该混剪视频的高光片段列表。详见下文 clip 结构。

clip 结构

参数	类型	描述
clip_type	String	片段类型。取值如下： HighlightClip：普通高光片段 OpeningHook：前置精彩片段
score	Number	高光分数，范围 [1, 5]。
source_video_index	Integer	该片段来源于输入视频列表中的索引位置，从 0 开始。
source_start_time	Number	片段在原始视频中的起始时间（单位：秒）。
source_end_time	Number	片段在原始视频中的结束时间（单位：秒）。
cut_start_time	Number	片段在最终混剪视频中的起始时间（单位：秒）。
cut_end_time	Number	片段在最终混剪视频中的结束时间（单位：秒）。
tags	Array	高光片段的标签，例如 ["争吵", "暴力冲突"]。仅当请求中 enable_segment_tag 为 true 时返回。标签可用于内容检索与推荐、Agent/开发者基于片段标签灵活进行二次创编等场景。

storyboard_info 结构

参数	类型	描述
source_video_index	Integer	该分镜来源于输入视频列表中的索引位置，从 0 开始。
start_time	Number	分镜在原始视频中的起始时间（单位：秒）。
end_time	Number	分镜在原始视频中的结束时间（单位：秒）。
score	Number	分镜的高光分数，范围 [1, 5]。
ocr	String	识别出的画面字幕文本。
description	String	算法生成的画面描述信息。
tags	Array	分镜的标签，例如 ["争吵", "威胁"]。仅当请求中 enable_segment_tag 为 true 时返回。标签可用于内容检索与推荐、Agent/开发者基于片段标签灵活进行二次创编等场景。

最终的完整任务信息示例：

错误处理

当请求的参数或鉴权信息不正确时，任务将不会被创建，接口会返回一个同步的错误响应。详见错误码。示例如下：

AI MediaKit