文档中心

AI MediaKit

大模型处理工具

视频理解智能策略

AI MediaKit 的视频理解智能策略工具，基于火山方舟视觉大模型，接收用户输入的视频和自然语言指令（Prompt），并根据视频时长、指令内容和用户指定的偏好（如成本、质量），自动决策最优的分析链路（包括抽帧策略、是否分析音频、选择哪个模型等），最终输出视频级别的结构化理解结果。该工具可为内容审核、视频检索、智能标签生成、视频摘要等场景提供真正开箱即用的、兼具成本与效果的视频理解能力。

本篇开发指南将引导您：

快速体验向工具提交一个视频并获取分析结果。

了解工具的工作原理，理解 level 档位、manual_option 等参数如何影响分析策略。

掌握工具的进阶用法与使用限制。

快速体验：分析一个公网视频

本节将演示如何对一个公网视频提交分析任务，并获取结果。

准备工作

获取访问凭证：访问 AI MediaKit 控制台 API Key 管理页面，创建并获取 AI MediaKit API Key（用于媒体处理功能鉴权）。

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

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

准备视频文件：准备一个或多个视频文件，并将其上传至公网可访问的服务器或视频点播服务中，以获取可供 API 调用的 URL。

操作流程

视频理解智能策略是一个异步任务，完整流程如下：

成功调用 POST /api/v1/tools/video-understand-router 提交任务后，您将获得一个任务 ID。

您可以轮询查询任务信息 API 接口，直到任务状态 status 变为 completed；或者使用事件回调自动接收任务状态变化。

任务完成后，解析响应中的 result 字段，即可在 contents 数组中获取每段视频的分析结果。

第 1 步：提交任务

调用提交视频理解智能策略任务 API。可直接复制以下 cURL 命令，提交一个最小可运行的分析任务。

说明

将 {Your_API_Key} 替换为您的有效 API Key。

将 video_urls 列表中的 URL 替换为您真实的视频地址。

prompt 用于指导大模型输出，您可以根据业务场景自定义。

请求成功后，您会收到如下包含 task_id 的响应，请保存此 ID 用于后续查询。

第 2 步：获取结果

通过轮询查询任务信息 API，直到任务状态 status 变为 completed。

说明

将 URL 末尾的 {task_id} 替换为第 1 步返回的任务 ID。

任务完成后，您将收到如下响应。result.contents 数组的每一项对应 video_urls 中同索引视频的分析结果。

进阶使用

工作原理

为实现在不同场景下的成本、效果和性能平衡，视频理解智能策略工具内置了一套智能路由与决策机制。

核心处理流程

当您提交一个任务后，系统会依次执行以下步骤来确定最终的分析链路：

候选模型池确认：

如果您在请求中指定了 prefer_endpoints，系统将优先从您指定的自定义推理接入点列表中选择服务。

如果您未指定 prefer_endpoints 但指定了 prefer_models，则系统从您指定的模型列表中选择。

如果两者均未指定，系统将使用您账号下预置的所有可用模型作为候选池。

音频分析检测：该步骤拥有最高优先级。系统会检测 prompt 中是否包含“声音”、“音乐”、“人声”、“对话”等音频关键词。若命中，系统将强制开启音频分析，并选用支持音视频多模态理解的模型（当前为 doubao-seed-2-0-lite-260428），此时后续的 level 档位对模型选择不再生效。

视频时长分类：系统根据视频时长将其分为三类：

短视频：小于 1 分钟。

中视频：1 分钟至 20 分钟。

长视频：20 分钟至 120 分钟。

抽帧与模型选择：系统根据模式（自动/手动）、视频时长和 level 档位，选择最终的抽帧策略和分析模型。

自动模式

当您不传入 manual_option 参数时，任务将进入自动模式。该模式下，系统会根据 level 档位和视频时长自动选择最优策略。

视频类型	level 档位	抽帧策略	分析模型（无音频时）
短视频（< 1 分钟）	忽略此参数	按 fps=1 均匀抽帧	doubao-seed-2-0-mini-260428
中长视频（≥ 1 分钟）	Economy（经济）	智能抽帧，目标帧数约为原视频按 1fps 抽帧总数的 30%	doubao-seed-2-0-mini-260428
		Balanced（均衡）	智能抽帧，目标帧数约为原视频按 1fps 抽帧总数的 60%	doubao-seed-2-0-pro-260215
		Quality（质量）	按 fps=1 均匀抽帧	doubao-seed-2-0-pro-260215

说明

关键机制说明

智能抽帧：一种基于图像-文本相似度计算的自适应关键帧选择算法，旨在用更少的帧数捕获视频核心内容，有效降低长视频分析成本。

1000 帧上限：为保证处理性能，所有抽帧策略（包括均匀抽帧和智能抽帧）最终提取的帧数上限为 1000 帧。如果按策略计算出的帧数超过 1000，系统将自动调整为在该视频总时长内等间隔抽取 1000 帧。

音频优先原则：如果 prompt 命中音频关键词，上述表格中的模型选择逻辑将被覆盖，系统会强制使用支持音频分析的模型。

手动模式

当您在请求中传入 manual_option 对象时，即进入手动模式，覆盖自动模式中的部分策略。

manual_option.max_snapshot_number:

作用：直接指定用于分析的最大截图（帧）数量，取值范围 [0, 1000]。

行为：该值会覆盖 level 档位决定的抽帧策略。例如，即使 level 为 Quality，若您设置 max_snapshot_number: 100，系统也仅会等间隔抽取 100 帧进行分析。

manual_option.fps:

作用：直接指定抽帧的帧率，取值范围 [0.2, 5.0]，默认值为 1.0。

行为：系统将按照您指定的帧率进行均匀抽帧。

manual_option.need_audio:

作用：布尔值，开启或关闭音频分析。

行为：

设为 true 时，系统会从候选模型池中选择支持音频分析的模型（目前为 doubao-seed-2-0-lite-260428 和 doubao-seed-2-0-mini-260428）。若候选模型池中无此类模型，请求将报错。

设为 false 时，系统将仅进行视频画面的分析。

以下请求示例强制将截图数限制为 200 帧，并开启音频分析：

指定分析档位 (level)

工具提供 3 种 level 档位，用于在速度、成本与结果质量之间取得平衡，默认为 Economy。

档位	适用场景
Economy	速度和成本优先，适合大批量、对结果详细程度要求较低的内容标注。
Balanced	速度与质量兼顾，适合常规内容审核与检索场景。
Quality	结果质量优先，适合需要更精细语义理解、生成高质量摘要等场景。

示例：使用 Quality 档位

参考信息

使用限制

限制项

说明

输入视频限制

视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。

支持格式：mp4, flv, ts, avi, mov, wmv, mkv 等主流视频格式。

数量限制：单次任务最多支持传入 10 个视频文件。

单视频时长限制：单个视频时长不超过 2 小时。

计费说明

视频理解智能策略工具的费用包含以下两部分，由 AI MediaKit 和火山方舟根据各自的服务用量分别计费：

AI MediaKit 视频理解智能策略工具费用：此费用覆盖视频的拉取、智能抽帧、音频分析（当 prompt 命中关键词或手动开启时）等媒体预处理操作，按输入视频的时长进行计费。关于具体的单价，请参见视频理解智能策略（按输入时长计费）。

火山方舟大模型调用费：此费用覆盖视觉大模型对视频内容进行理解、分析和生成结构化文本的核心计算资源，按模型调用过程中实际消耗的 Token 数量计费，包括输入 Token 和输出 Token。任务成功后，您可以在查询任务的 API 响应 result.token_usage 字段（详见 Token usage 对象）中获取该任务详细的 Token 消耗数据。关于不同模型的 Token 计费标准，请查阅火山方舟服务的最新官方定价说明。