POST https://mediakit.cn-beijing.volces.com/api/v1/tools/video-highlights-llm

本 API 用于提交一个异步的大模型高光剪辑任务，从一个或多个输入视频中，按场景预设、评分标准或故事目标智能识别精彩片段，自动挑选、裁剪并拼接成一个或多个指定时长的高光成片。

前提条件

开通火山方舟大模型服务：大模型高光剪辑工具依赖火山方舟大模型。请前往火山方舟控制台开通管理页面，确保您已开通以下模型：

视觉理解模型：doubao-seed-2-0-lite-260428

文本推理模型：请至少开通以下任一模型。当您未在请求中通过 customer_ark_config 参数指定 Endpoint 时，系统将按场景复杂度，自动查找并使用您账号下已开通的模型服务。

doubao-seed-2-0-pro-260215

doubao-seed-2-1-turbo-260628

doubao-seed-2-1-pro-260628

此外，您还需开启 Cache 功能，用于启用模型的上下文缓存 API，若不开启，任务虽不会失败，但可能会影响最终的效果。

进行跨服务授权：首次使用大模型高光剪辑工具前，请前往 AI MediaKit 控制台基础配置 > 授权管理页面，为 AI MediaKit 授予访问您 ARK 火山方舟资源的权限。否则，任务将因无权限访问而失败。

请求参数

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

Body 参数

参数	类型	是否必选	示例值	描述
video_urls	Array	是	["https://example.com/video1.mp4"]	待分析的输入视频 URL 列表。支持传入一个或多个视频，系统将按列表顺序进行分析。视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, flv, ts, avi, mov, wmv, mkv 等主流视频格式。时长限制：单个视频时长不超过 3 小时，全部输入视频累计时长不超过 15 小时。
target_duration	Array	是	[60]	期望生成的多个高光视频的目标时长列表，单位为秒。系统将为列表中的每个时长生成一个独立的成片视频。例如，传入 [30, 60] 会生成两条视频，一条约 30 秒，另一条约 60 秒。列表内最多支持 5 个目标时长，且各时长值不能重复（例如，[30, 30] 是无效的）。每个时长值必须大于等于 1，且小于所有输入视频的总时长。
preset	String	否	football	预设场景。选择一个预设场景后，系统会自动采用针对该场景优化的分析策略和评分标准。preset 与 scoring_prompt 必须提供其中一个。可选值包括： football：足球 basketball：篮球 automotive：汽车 finance：金融财经 product_launch：产品发布 ecommerce：电商 knowledge_share：知识分享
scoring_prompt	String	否	进球、射门、关键扑救和球员庆祝特写	自定义评分标准。通过自然语言描述您认为精彩的片段应具备哪些特征。模型将依据此描述为视频片段打分并筛选。如果未提供此参数，则必须提供 preset。内容长度上限为 5000 字符。
analysis_prompt	String	否	记录画面中出现的实时比分	补充分析指令。通过自然语言指定模型在分析视频时需要额外关注和提取的信息。内容长度上限为 5000 字符。
voice_language	String	否	en-US	指定视频中的语音语言，用于语音识别 ASR。该参数仅在触发 ASR 的处理链路生效，不会强制启用 ASR。默认行为：如不填写或为空，工具将自动检测语言。支持自动检测的语种为：中文、英文、上海话、闽南话、四川话、陕西话、粤语。支持的语种包括： zh-CN：简体中文 en-US：英语（美国） ja-JP：日语 id-ID：印度尼西亚语 es-MX：西班牙语（墨西哥） pt-BR：葡萄牙语（巴西） de-DE：德语 fr-FR：法语 ko-KR：韩语 fil-PH：菲律宾语 ms-MY：马来语 th-TH：泰语 ar-SA：阿拉伯语 it-IT：意大利语 bn-BD：孟加拉语 el-GR：希腊语 nl-NL：荷兰语 ru-RU：俄语 tr-TR：土耳其语 vi-VN：越南语 pl-PL：波兰语 ro-RO：罗马尼亚语 ne-NP：尼泊尔语 uk-UA：乌克兰语 yue-CN：粤语其中中文（zh-CN）与英文（en-US）为明确支持语种，其余语种可用但不保证识别效果。
output_language	String	否	en-US	设置输出结果的语言。该参数影响输出结果中的 segment.title（标题）、segment.summary（摘要）与 segment.reason（选中理由）字段的语言。如不填写或留空，默认为 zh-CN。支持的语言： zh-CN：简体中文 en-US：英语（美国）
skip_video_output	Boolean	否	false	是否跳过最终的视频拼接与生成，仅输出结构化高光数据。 false：（默认）任务完成后，生成并返回高光视频的下载地址 (video_url) 及结构化数据。 true: 任务完成后，仅返回结构化高光数据（如 segments 信息），不进行视频拼接。此时，结果中的 outputs 字段将不包含 video_url。如果您仅需分析结果而无需成片，建议开启此选项以提升处理速度。
time_range	Object	否	{"start_ms": 600000, "end_ms": 1800000}	指定视频的分析时间范围，单位为毫秒，格式为左闭右开区间。设置后，系统将仅在该时间范围内分析和挑选高光片段。此参数仅在 video_urls 列表中仅包含一个视频时生效。详情请参见下文 Time range 对象。
customer_ark_config	Object	否	-	自定义本次任务使用的火山方舟大模型服务节点 Endpoint，用于覆盖默认的模型选择策略。不传入此参数时：系统将按部分描述，自动选用您已开通的推荐模型。传入此参数时：系统将严格使用您在此处指定的 Endpoint。请确保所有指定的 Endpoint 均基于中列出的推荐模型，否则任务可能失败。详情请参见下文 Customer ark config 对象。
media_output_destination	String	否	vod://my-space	指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶。存储至 VOD：设为 vod://<您的空间名> 存储至 TOS：设为 tos://<您的桶名> 不传本参数时，任务结果中的 image_url 返回有效期为 24 小时的临时下载地址。设置本参数后，任务结果中的 url 相关字段将返回形如 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。说明首次使用此功能前，您需要先前往 AI MediaKit 控制台基础配置 > 授权管理页面，授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。更多信息，请参阅开发指南。
client_token	String	否	your_unique_request_id_134	用户请求凭证，用于幂等控制。大小写敏感，不超过 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。详情请参考按项目或 API Key 分账。

Time range 对象

参数	类型	是否必选	描述
start_ms	Integer	是	时间范围的起始点，单位为毫秒。必须大于或等于 0。
end_ms	Integer	是	时间范围的结束点，单位为毫秒。必须大于 start_ms 且不超过输入视频的总时长。

Customer ark config 对象

参数	类型	是否必选	描述
video_understanding_endpoints	Array<String>	是	指定用于视觉理解模型的 Endpoint ID（以 ep- 开头）列表。系统将按列表顺序（从高到低）依次尝试调用。为提高任务稳定性，建议提供 1-3 个处于运行状态的 Endpoint ID 作为备选。注意：Endpoint 必须基于中指定的视觉理解模型。
text_reasoning_endpoints	Array<String>	是	指定用于文本推理模型的 Endpoint ID（以 ep- 开头）列表。系统将按列表顺序（从高到低）依次尝试调用。为提高任务稳定性，建议提供 1-3 个处于运行状态的 Endpoint ID 作为备选。注意：Endpoint 必须基于中指定的任一文本推理模型。

请求示例

以下示例演示了如何提交一个基于场景预设的高光剪辑任务，并使用自有方舟 Endpoint。

响应说明

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

响应参数

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

Error 对象

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

响应示例

成功响应

失败响应

异步任务结果

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

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

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

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

参数	类型	描述
duration	Number	所有输出成片（outputs）的实际总时长，单位为秒。
input_duration	Number	所有输入视频的总时长，单位为秒。
outputs	Array of Object	高光成片输出列表，顺序与请求参数 target_duration 中的顺序一致。详见下文 Output 对象。
token_usage	Object	本任务实际发生的全部大模型调用用量统计。详见下文 Token usage 对象。

Output 对象

参数	类型	描述
index	Integer	输出序号，从 0 开始。
target_duration	Number	该条输出在请求时设定的目标时长，单位为秒。
video_url	String	该条高光成片的地址。如果请求时 skip_video_output 设置为 true，则不返回此字段。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
duration	Number	该条输出成片的实际时长，单位为秒。
segments	Array of Object	组成该条成片的所有高光片段的详细信息列表。详见下文 Segment 对象。

Segment 对象

参数	类型	描述
video_index	Integer	该片段来源于请求中 video_urls 列表的第几个视频，从 0 开始。
segment_index	Integer	该片段在当前成片中的顺序号，从 0 开始。
source	String	来源视频的 URL 或标识。
title	String	模型为该片段生成的标题。
summary	String	模型为该片段生成的内容摘要。
reason	String	模型解释为何该片段被选为高光片段的理由。
spans	Array of Object	该片段在来源视频中的具体时间区间。详见下文 Span 对象。

Span 对象

参数	类型	描述
source_start_ms	Number	片段在来源视频中的起始时间，单位为毫秒。
source_end_ms	Number	片段在来源视频中的结束时间，单位为毫秒。

Token usage 对象

参数	类型	描述
total_input_tokens	Integer	任务消耗的所有输入 Token 总数（包括文本、图像、音频）。
total_output_tokens	Integer	任务生成的所有输出 Token 总数。
total_cached_tokens	Integer	输入 Token 中命中上下文缓存的总数。
total_audio_tokens	Integer	音频输入的 Token 总数。
total_audio_cached_tokens	Integer	命中缓存的音频输入 Token 总数。
total_think_tokens	Integer	模型思考过程消耗的 Token 总数，若模型不支持则为 0。
endpoint_token_usages	Array of Object	按本次任务实际调用的方舟 Endpoint 聚合的详细用量列表。详见下文 Endpoint token usage 对象。

Endpoint token usage 对象

参数	类型	描述
endpoint	String	实际调用的火山方舟模型服务 Endpoint ID。
model	String	该 Endpoint 对应的模型名称。
input_tokens	Number	该 Endpoint 消耗的输入 Token 数。
output_tokens	Number	该 Endpoint 生成的输出 Token 数。
cached_tokens	Number	该 Endpoint 消耗的输入 Token 中命中缓存的数量。
audio_tokens	Number	该 Endpoint 消耗的音频 Token 数。
audio_cached_tokens	Number	该 Endpoint 消耗的音频 Token 中命中缓存的数量。
think_tokens	Number	该 Endpoint 在思考过程中消耗的 Token 数。

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

AI MediaKit