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

本接口用于提交一个异步的高光片段提取任务，能智能捕捉视频的“情绪波峰”与“关键动作”，输出包含精准时间戳、高光打分、OCR 文本和画面描述的详细信息，供您进行灵活的二次开发或内容分析。本接口支持短剧 Miniseries 和小游戏 Game 两种分析模型。

调用说明

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

开发指南：如需了解完整的使用流程和应用示例，请参阅高光片段提取。

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	描述
video_urls	Array	是	待分析的视频 URL 列表。不同模型对输入视频的数量、时长和内容有不同要求。通用限制：视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, flv, ts, avi, mov, wmv, mkv 等主流视频格式。输入分辨率限制：最高支持 1080p。当用于短剧高光片段提取时：输入配额：单次任务最多支持输入 30 个视频文件，累计总时长建议不超过 45 分钟。输入素材要求：必须同时包含视频流和音频流。视频画面要求：视频画面下半部分（垂直位置 0.5-1.0 范围内）必须包含清晰居中的中文字幕。音频流要求：视频的音频轨道中必须包含清晰可识别的中文对话文本。仅包含 BGM（含歌词）、纯音乐、语气词或无有效语义的声音，将无法准确识别剧情逻辑。当用于小游戏高光片段提取时：数量限制：当前单次任务仅支持输入单个视频文件。如果输入多个视频，会默认选择第一个文件进行分析。时长限制：输入文件的时长不得超过 10 分钟。
model	String	是	分析场景模型，决定了算法的侧重点。 Miniseries：短剧模型，结合故事线理解，智能识别钩子点、反转、亲密、冲突等高光片段。 Game：小游戏模型，精准识别玩法操作片段和击杀、连胜、满血反杀等高光瞬间。
mode	String	是	高光提取模式，取值依赖于 model 参数：当 model 为 Miniseries 时，mode 必须为 StorylineCuts。当 model 为 Game 时，mode 必须为 HighlightExtract。
minigame_info	Object	否	仅当 model 为 Game 时可选填。提供小游戏的相关描述信息，可辅助模型更精准地识别高光内容。详见下文 minigame_info 结构。
client_token	String	否	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考幂等性控制。
callback_args	String	否	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。
callback_url	String	否	用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

minigame_info 结构

当 model 为 Game 时，您可以通过此对象提供额外信息以提升分析准确度。

参数	类型	是否必选	描述
name	String	否	游戏名称，用于标识游戏内容。
play_definition	String	否	游戏的玩法规则或核心特点描述。
highlight_definition	String	否	游戏中的高光时刻或精彩瞬间的定义描述（例如：“一次消除多个方块”、“躲避所有障碍物通关”等）。

请求示例

以下示例演示了如何使用 Game 模型分析一个小游戏视频，并提供了游戏描述信息以辅助识别。

响应说明

任务提交成功响应

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

示例：

异步任务结果

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

参数	类型	描述
duration	Number	输入视频的总时长（单位：秒）。
highlight_info	Array	高光片段元数据列表。详见下文 highlight_info 结构。

highlight_info 结构

参数	类型	描述
source_video_index	Integer	该片段来源于输入视频列表中的索引位置，从 0 开始。
start_time	Number	片段在原始视频中的起始时间（单位：秒）。
end_time	Number	片段在原始视频中的结束时间（单位：秒）。
score	Number	高光分数，范围 [1, 5]。分数越高，代表片段越精彩。
ocr	String	识别出的画面中的字幕/文字内容。
description	String	算法生成的该片段的画面描述信息。

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

错误处理

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

AI MediaKit