POST https://mediakit.cn-beijing.volces.com/api/v1/tools/video-understand-router

本 API 用于提交一个异步的视频理解智能策略任务，基于视觉大模型，对输入的视频 URL 列表进行通用视频内容分析，输出视频级别的结构化理解结果，适用于内容审核、视频检索、标签生成等场景。

前提条件

开通火山方舟大模型服务：视频理解智能策略工具依赖火山方舟大模型。请前往火山方舟控制台在线推理页面，确保您已开通并可使用相关模型服务。

通用视频分析场景：默认情况下，任务需要依赖视觉理解大模型，请确保您账号下有可用的视觉理解大模型。

创作剪辑场景（scene 取值为 editing）：使用此场景时，系统需要结合视觉理解与文本推理能力，请确保您已开通并可使用以下模型：

doubao-seed-2-0-lite-260428（必需）

doubao-seed-2-1-turbo-260628、doubao-seed-2-1-pro-260628（二选一）

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

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	示例值	描述
video_urls	Array of String	是	["https://example.com/video1.mp4", "https://example.com/video2.mp4"]	待处理的视频 URL 列表。视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, flv, ts, avi, mov, wmv, mkv 等主流视频格式。数量限制：单次任务最多支持传入 10 个视频文件。单视频时长限制：单个视频时长不超过 2 小时。
prompt	String	是	请总结视频中的关键事件，并标注每个事件出现的时间段	提示词，用于指导大模型对视频内容进行分析的自然语言描述。最小长度为 1。
level	String	否	Balanced	分析档位。该参数会决定任务的默认抽帧策略与模型选择，以在成本、速度和质量之间取得平衡。详细的决策逻辑，请参阅工作原理。取值如下： Economy：（默认）经济档位，速度优先，适合大批量、对结果详细程度要求较低的内容标注。 Balanced：均衡档位，速度与质量兼顾，适合常规内容审核与检索场景。 Quality：质量档位，结果优先，适合需要更精细语义理解的场景。
scene	String	否	editing	分析场景，用于系统优化处理策略。如不传，表示通用场景。指定场景后，系统会自动决策使用该场景的最佳策略： editing：创作剪辑场景。指定此场景后，模型会侧重于理解并输出带有精确时间戳的详细分镜信息，适用于分镜理解、智能剪辑、二次 AIGC 创作等下游任务。
prefer_models	Array of String	否	["doubao-seed-2-0-lite-260428"]	优先使用的模型 ID (Model ID) 列表，最多 10 个。系统将从您指定的模型中结合策略选择最终模型。您可以在火山方舟控制台在线推理页面查看可用的模型 ID。
prefer_endpoints	Array of String	否	["ep-m-20260703202744-q8tcb"]	优先使用的推理接入点 ID (Endpoint ID) 列表，最多 10 个。系统将从您指定的推理接入点中结合策略选择最终模型。您可以在火山方舟控制台在线推理页面创建和管理推理接入点。注意：此参数优先级高于 prefer_models。
manual_option	Object	否	-	手动模式相关参数。详见下文 Manual option 对象。该字段未传时表示完全使用 level 档位策略，不进行手动覆盖。
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。详情请参考项目与队列管理。

Manual option 对象

参数	类型	是否必选	示例值	描述
max_snapshot_number	Integer	否	100	最大抽帧帧数，取值范围 [0, 1000]，默认 0。设为 0 时由 level 档位决定截图数量；显式设置时会覆盖档位策略。
fps	Number	否	1.0	抽帧帧率。设置后，系统将按照您指定的帧率进行均匀抽帧。取值范围 [0.2, 5.0]，默认值为 1.0。
need_audio	Boolean	否	false	是否开启或关闭音频分析，默认为 false。 true：开启音频分析，系统将选用支持音视频多模态的模型，分析音频内容（语音、台词、声音特征等）。 false：关闭音频分析，仅分析视频画面。注意：即使此参数为 false 或未提供，如果 prompt 中包含“声音”、“音乐”等音频相关关键词，系统可能也会自动触发音频分析。

请求示例

以下示例演示了如何对一个公网视频进行内容分析，要求对视频内容做总结。

响应说明

调用 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，定期调用查询任务信息 API，直到 status 字段变为 completed 或 failed。

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

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

参数	类型	描述
duration	Number	输入视频总时长，单位为秒，为所有输入视频时长的总和。
contents	Array of String	视频内容分析结果列表。每一项对应 video_urls 中同索引视频的分析结果文本。
token_usage	Object	大模型推理过程中的 Token 使用量统计。详见下文 Token usage 对象。

Token usage 对象

参数	类型	描述
input_tokens	Integer	输入 Token 数量。
output_tokens	Integer	输出 Token 数量。
total_tokens	Integer	总 Token 数量。

以下是一个任务执行完成后的完整任务信息示例：

AI MediaKit