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

本 API 用于提交一个异步的高光智剪（影视拆条）任务，依托长视频理解算法，针对电影、电视剧等长视频内容，自动识别并去除景色铺垫、缓慢运镜、片头片尾曲等低密度信息，按照剧情故事线智能拆分出多段指定时长（如 2-3 分钟）的高光拆条片段。每段拆条均自带"高光前置开场"与"结尾钩子"设计，输出可直接用于影视合集分发的短视频素材，是长视频"短剧化"内容生产的核心能力。

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	示例值	描述
video_url	String	是	https://example.com/video.mp4	待处理的影视视频源 URL。视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, flv, ts, avi, mov, wmv, mkv 等主流视频格式。数量限制：当前单次任务仅支持输入单个视频文件。时长限制：单文件时长不超过 180 分钟。输入分辨率限制：最高支持 1080p。输入素材要求：视频必须同时包含视频流和音频流。适用于电影（更优）、电视剧等长视频内容；不建议用于纯综艺、纪录片、广告或纯 BGM 视频。音频流要求：建议视频音频轨道中包含清晰可识别的中文对话文本，以便算法准确理解剧情逻辑。
enable_generate_video	Boolean	否	true	是否生成并输出可用于下载的拆条视频文件 URL，默认为 true。 true：生成拆条视频文件，并在任务结果中返回 video_urls。 false：仅输出拆条片段元信息（时间戳、评分、标题等），不生成实际视频文件，可用于自定义二次剪辑。当此参数设为 false 时，您必须将 highlight_cuts_param.enable_detailed_info 设为 true，以确保任务能返回有效的元信息。
highlight_cuts_param	Object	否	-	拆条片段配置。用于控制每段拆条片段的目标时长范围，以及是否返回详细的片段时间线信息。如果留空，则默认生成 90-180 秒的拆条片段。详见下文 highlight_cuts_param 结构。
opening_hook_param	Object	否	-	高光前置开场配置。用于控制是否在每个拆条片段的开头拼接一段最精彩的“钩子”片段。如果留空，则默认添加 5-15 秒的高光前置。详见下文 opening_hook_param 结构。
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_132	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考幂等性控制。
callback_args	String	否	your_custom_callback_data	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。
callback_url	String	否	https://example.com/callback	用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

highlight_cuts_param 结构

参数	类型	是否必选	示例值	描述
min_duration	Number	否	90	单个拆条片段的最短时长（单位：秒），建议 90 秒起步以保证剧情完整度。默认值为 90，取值范围 [1, 600]。
max_duration	Number	否	180	单个拆条片段的最大时长（单位：秒），建议不超过 180 秒（3 分钟）以贴合短视频平台分发节奏。默认值为 180，取值范围 [1, 600]。
enable_detailed_info	Boolean	否	false	是否在任务结果中输出每段拆条的详细分镜与片段信息（如片段类型、评分、原始视频中的起止时间、在拆条视频中的起止时间等），对应返回结果中的 clips 字段。默认值为 false。

opening_hook_param 结构

参数	类型	是否必选	默认值	描述
is_enabled	Boolean	否	true	是否启用高光前置开场。默认值为 true。 true：系统自动提取最精彩片段置于拆条视频开头。 false：按原始剧情顺序输出拆条视频。
min_duration	Number	否	5	高光前置片段的最短总时长（单位：秒）。取值范围 [0, 60]。默认值为 5。
max_duration	Number	否	15	高光前置片段的最大总时长（单位：秒）。取值范围 [0, 60]。默认值为 15。
min_clip_duration	Number	否	5	构成高光前置片段的单个片段的最短时长（单位：秒），用于避免拼接过多碎片段造成频闪。取值范围 [0, 60]。默认值为 5。
min_score	Number	否	4	用于筛选高光前置片段的最低评分。取值范围 [0, 5]，数值越高代表筛选标准越严格。默认值为 4。

请求示例

以下示例演示了如何对一部电影进行拆条，要求拆条时长在 100-200 秒之间，并关闭高光前置功能。

响应说明

调用 API 提交任务后，接口会立即返回一个同步响应，表明任务是否成功进入后台处理队列。

响应参数

参数	类型	描述
success	Boolean	任务是否提交成功。 true：任务已成功提交到后台处理队列。 false：请求存在错误，任务提交失败。请检查 error 字段以获取详细信息。
task_id	String	任务的唯一标识。仅在 success 为 true 时返回有效值，用于后续查询任务状态和结果。
request_id	String	本次请求的唯一标识，可用于问题排查。
error	Object	错误详情对象，仅在 success 为 false 时返回。详见下文 Error 对象。

Error 对象

参数	类型	描述
code	String	具体的错误码。关于各错误码的详细信息，请参阅错误码。
type	String	错误的宏观类型。例如 BadRequest。
message	String	对错误的详细描述，可用于开发调试。
param	String	（可选）指出导致错误的具体参数。

响应示例

成功响应

失败响应

异步任务结果

高光智剪（影视拆条）是一个异步任务，任务的执行状态和最终结果不会在提交时同步返回。您可以通过以下两种方式获取任务结果：

方法一（轮询查询）：使用提交任务时获取的 task_id，定期调用查询任务信息 API，直到 status 字段变为 completed 或 failed。

方法二（事件回调）：在 AI MediaKit 控制台预先配置一个接收回调的 URL，或在提交任务时通过 callback_url 参数为单次任务指定回调地址。任务完成后，系统会将包含最终结果的详细信息 POST 到您指定的地址。详情请参阅事件回调。

当任务成功完成后，您获取到的任务信息中的 result 字段将包含以下内容。

参数	类型	描述
input_duration	Number	输入视频的总时长（单位：秒）。
video_urls	Array	影视拆条结果视频的地址列表。如果请求中 enable_generate_video 为 false 或算法未能成功生成视频，此列表为空。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
result_cuts_info	Array	每条影视拆条片段的详细信息列表，顺序与 video_urls 一致。详见下文 clips 结构。

result_cuts_info 结构

参数	类型	描述
title	String	算法基于剧情为该片段自动生成的标题或内容简述。
duration	Number	该拆条视频的实际时长（单位：秒）。
size	Integer	该拆条视频的文件大小（单位：字节）。
video_url	String	该拆条片段对应的视频下载 URL。如果未生成视频，则为空字符串。该地址的有效期为 24 小时，请务必及时保存产物。
clips	Array	组成该拆条的原始片段信息列表。仅当请求中 highlight_cuts_param.enable_detailed_info 为 true 时返回。详见下文 clips 结构。

clips 结构

参数	类型	描述
type	String	片段类型。取值：OpeningHook (高光前置) 或 HighlightClip (高光主体)。
score	Number	该片段的高光评分，范围 [1, 5]。
source_start_time	Number	该片段在原始视频中的起始时间点（单位：秒）。
source_end_time	Number	该片段在原始视频中的结束时间点（单位：秒）。
cut_start_time	Number	该片段在最终生成的拆条视频中的起始时间点（单位：秒）。
cut_end_time	Number	该片段在最终生成的拆条视频中的结束时间点（单位：秒）。

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

AI MediaKit