AI MediaKit 的视频理解智能策略工具，基于[火山方舟视觉大模型](https://www.volcengine.com/docs/82379/1330310?lang=zh#76df97c8)，接收用户输入的视频和自然语言指令（Prompt），并根据视频时长、指令内容和用户指定的偏好（如成本、质量），自动决策最优的分析链路（包括抽帧策略、是否分析音频、选择哪个模型等），最终输出视频级别的结构化理解结果。该工具可为内容审核、视频检索、智能标签生成、视频摘要等场景提供真正开箱即用的、兼具成本与效果的视频理解能力。本篇开发指南将引导您： * 快速体验向工具提交一个视频并获取分析结果。 * 了解工具的工作原理，理解 `level` 档位、`manual_option` 等参数如何影响分析策略。 * 掌握工具的进阶用法与使用限制。 ## 快速体验：分析一个公网视频本节将演示如何对一个公网视频提交分析任务，并获取结果。 ### 准备工作 1. **获取访问凭证**：访问 AI MediaKit 控制台 [API Key 管理页面](https://console.volcengine.com/imp/ai-mediakit/settings)，创建并获取 AI MediaKit API Key（用于媒体处理功能鉴权）。 2. **开通火山方舟大模型服务**：视频理解智能策略工具依赖火山方舟视觉大模型。请前往[火山方舟控制台在线推理页面](https://console.volcengine.com/ark/region:ark+cn-beijing/endpoint)，确保相关模型（如豆包大模型）已开通并可试用。 3. **进行跨服务授权**：首次使用视频理解智能策略工具前，请前往 AI MediaKit 控制台[基础配置 > 授权管理](https://console.volcengine.com/imp/ai-mediakit/settings?tab=authorization&projectName=default)页面，为 AI MediaKit 授予访问您 **ARK 火山方舟**资源的权限。否则，任务将因无权限访问而失败。 4. **准备视频文件**：准备一个或多个视频文件，并将其上传至公网可访问的服务器或[视频点播服务](https://www.volcengine.com/docs/4/2834?lang=zh)中，以获取可供 API 调用的 URL。 ### 操作流程视频理解智能策略是一个异步任务，完整流程如下： 1. 成功调用 `POST /api/v1/tools/video-understand-router` 提交任务后，您将获得一个任务 ID。 2. 您可以轮询[查询任务信息 API](https://docs.volcengine.com/docs/6448/2278532) 接口，直到任务状态 `status` 变为 `completed`；或者使用[事件回调](https://docs.volcengine.com/docs/6448/2288701)自动接收任务状态变化。 3. 任务完成后，解析响应中的 `result` 字段，即可在 `contents` 数组中获取每段视频的分析结果。 #### 第 1 步：提交任务调用[提交视频理解智能策略任务 API](https://docs.volcengine.com/docs/6448/2552748)。可直接复制以下 cURL 命令，提交一个最小可运行的分析任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/video-understand-router' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_urls": [ "https://example.com/sample_video.mp4" ], "prompt": "请总结视频中的关键事件，并标注每个事件出现的时间段" }' ```

说明

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

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

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

请求成功后，您会收到如下包含 `task_id` 的响应，请保存此 ID 用于后续查询。 ```JSON { "success": true, "task_id": "amk-tool-video-understand-router-123456789", "request_id": "20260624150000ABCDEFG12345" } ``` #### 第 2 步：获取结果通过轮询[查询任务信息 API](https://docs.volcengine.com/docs/6448/2278532)，直到任务状态 `status` 变为 `completed`。 ```Bash curl -X GET 'https://mediakit.cn-beijing.volces.com/api/v1/tasks/{task_id}' \ -H 'Authorization: Bearer {Your_API_Key}' ```

说明

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

任务完成后，您将收到如下响应。`result.contents` 数组的每一项对应 `video_urls` 中同索引视频的分析结果。 ```JSON { "success": true, "task_id": "amk-tool-video-understand-router-123456789", "request_id": "20260624150000ABCDEFG12345", "status": "completed", "result": { "duration": 120.5, "contents": [ "视频时长 120 秒，主要内容为城市街景拍摄。0-30 秒为日间繁忙街道俯拍……" ], "token_usage": { "input_tokens": 850, "output_tokens": 150, "total_tokens": 1000 } }, "expires_at": 1782001650, "created_at": 1781828767, "finished_at": 1781828851 } ``` ## 进阶使用 ### 工作原理为实现在不同场景下的成本、效果和性能平衡，视频理解智能策略工具内置了一套智能路由与决策机制。 #### **核心处理流程** 当您提交一个任务后，系统会依次执行以下步骤来确定最终的分析链路： 1. **候选模型池确认**： * 如果您在请求中指定了 `prefer_endpoints`，系统将优先从您指定的自定义推理接入点列表中选择服务。 * 如果您未指定 `prefer_endpoints` 但指定了 `prefer_models`，则系统从您指定的模型列表中选择。 * 如果两者均未指定，系统将使用您账号下预置的所有可用模型作为候选池。 2. **音频分析检测**：该步骤拥有最高优先级。系统会检测 `prompt` 中是否包含“声音”、“音乐”、“人声”、“对话”等音频关键词。若命中，系统将强制开启音频分析，并选用支持音视频多模态理解的模型（当前为 `doubao-seed-2-0-lite-260428`），此时后续的 `level` 档位对模型选择不再生效。 3. **视频时长分类**：系统根据视频时长将其分为三类： * **短视频**：小于 1 分钟。 * **中视频**：1 分钟至 20 分钟。 * **长视频**：20 分钟至 120 分钟。 4. **抽帧与模型选择**：系统根据模式（自动/手动）、视频时长和 `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 帧，并开启音频分析： ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/video-understand-router' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_urls": ["https://example.com/sample_video.mp4"], "prompt": "这个视频里的背景音乐是什么？", "level": "Balanced", "manual_option": { "max_snapshot_number": 200, "need_audio": true } }' ``` ### 指定分析档位 (`level`) 工具提供 3 种 `level` 档位，用于在速度、成本与结果质量之间取得平衡，默认为 `Economy`。 |档位 |适用场景 | |---|---| |`Economy` |速度和成本优先，适合大批量、对结果详细程度要求较低的内容标注。 | |`Balanced` |速度与质量兼顾，适合常规内容审核与检索场景。 | |`Quality` |结果质量优先，适合需要更精细语义理解、生成高质量摘要等场景。 | #### 示例：使用 `Quality` 档位 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/video-understand-router' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_urls": ["https://example.com/sample_video.mp4"], "prompt": "请详细描述这个视频的每一幕，风格需要正式。", "level": "Quality" }' ``` ## 参考信息 ### 使用限制 |限制项 |说明 | |---|---| |输入视频限制 |* **视频来源**：支持公网 HTTP/HTTPS URL、本地上传 (`mediakit://`)、来源于火山引擎视频点播 (`vod://`) 和火山引擎对象存储 (`tos://`) 四种输入协议。关于各协议的具体说明和使用示例，请参阅[多源媒体输入与本地上传](https://docs.volcengine.com/docs/6448/2536893)。

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

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

* **单视频时长限制**：单个视频时长不超过 2 小时。 | ### 计费说明视频理解智能策略工具的费用包含以下两部分，由 AI MediaKit 和火山方舟根据各自的服务用量分别计费： * **AI MediaKit 视频理解智能策略工具费用**：此费用覆盖视频的拉取、智能抽帧、音频分析（当 `prompt` 命中关键词或手动开启时）等媒体预处理操作，按输入视频的时长进行计费。关于具体的单价，请参见[视频理解智能策略（按输入时长计费）](https://docs.volcengine.com/docs/6448/2486473#c29c0699)。 * **火山方舟大模型调用费**：此费用覆盖视觉大模型对视频内容进行理解、分析和生成结构化文本的核心计算资源，按模型调用过程中实际消耗的 Token 数量计费，包括输入 Token 和输出 Token。任务成功后，您可以在查询任务的 API 响应 `result.token_usage` 字段（详见 [Token usage 对象](https://docs.volcengine.com/docs/6448/2552748#7fc3c2a4)）中获取该任务详细的 Token 消耗数据。关于不同模型的 Token 计费标准，请查阅火山方舟服务的[最新官方定价说明](https://docs.volcengine.com/docs/82379/1544106?lang=zh)。 ## 相关 API 文档 * [提交视频理解智能策略任务 API](https://docs.volcengine.com/docs/6448/2552748) * [查询任务信息 API](https://docs.volcengine.com/docs/6448/2278532) * [事件回调](https://docs.volcengine.com/docs/6448/2288701)