AI MediaKit 剧情故事线分析工具能够智能理解您输入的**单个或多个**长视频（如电影、电视剧，**长达 3.5 小时**），并输出一份结构化的 JSON 数据。该工具将非结构化长视频智能解析为可检索、可运营的结构化剧情故事线，为实现媒资检索、智能预告片生成、播放器章节导航以及基于剧情内容的高级搜索等提供强大助力。本篇开发指南将引导您： * 快速体验通过 API 调用，将长视频解析为结构化的故事线数据。 * 深入理解返回结果中 `storyline_clips` 和 `storyline_highlights` 的区别与使用方法。 * 学习如何基于分析结果，实现“高光集锦生成”、“只看 TA”等高级功能。 ## 快速入门：实现剧情故事线分析 ### 准备工作 1. **获取访问凭证**：在开始之前，访问 AI MediaKit 控制台 [API Key 管理页面](https://console.volcengine.com/imp/ai-mediakit/settings)，创建并获取 **AI MediaKit API Key**。 2. **准备视频文件**：准备一个或多个待分析的视频文件，并将其上传至公网可访问的服务器或[视频点播服务](https://www.volcengine.com/docs/4/2834?lang=zh)中，以获取可供 API 调用的 URL。 ### 操作流程剧情故事线分析是一个异步任务，整体流程如下： 1. 成功调用 `POST /api/v1/tools/analyze-video-storyline` 后，API 将返回一个任务 ID 。 2. 您可以轮询 `GET /api/v1/tasks/{task_id}` ，直到任务状态`status` 变为 `completed`；或者使用[事件回调](https://www.volcengine.com/docs/6448/2288701)自动接收任务状态变化。 3. 任务完成后，您从响应的 `result` 字段中解析结构化的故事线数据。 #### 第 1 步：提交分析任务您可以直接复制以下 cURL 命令，提交一个分析任务。本示例输入了两个视频文件，并要求为每个剧情片段生成关键帧快照。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools/analyze-video-storyline' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "video_urls": [ "https://example.com/movie_part1.mp4", "https://example.com/movie_part2.mp4" ], "enable_snapshot": true }' ```

说明

需替换参数：

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

将 video_urls 列表中的 URL 替换为您自己的视频文件地址。

请求成功后，您会收到如下包含 `task_id` 的响应，请保存此 ID 用于后续查询。 ```JSON { "success": true, "task_id": "amk-tool-analyze-video-storyline-123456789", "request_id": "20240522100000ABCDEFG12345" } ``` #### 第 2 步：获取分析结果故事线分析需要时间，您需要通过轮询[查询任务信息 API](https://www.volcengine.com/docs/6448/2278532) 来获取最终结果，直到任务状态变为 `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` 字段即为结构化的故事线数据。 ```JSON { "success": true, "task_id": "amk-tool-analyze-video-storyline-47695264770", "status": "completed", "result": { "duration": 342.36, "source_video_info": [ { "source_video_index": 0, "source_video_url": "https://.../1.mp4?...", "source_video_title": "少年识破荐股骗局，支开舅舅操作炒股放大收益", "source_video_summary": "男子接到荐股老师电话，被怂恿投二百万买垃圾股，对话被身旁少年全程听到。少年发现对方冒用自己的名言，还查出该股是空壳公司...", "source_video_tag": ["荐股骗局", "股票投资", "机智应对", "亲情守护", "金融理财"] }, { "source_video_index": 1, "source_video_url": "https://.../2.mp4?...", "source_video_title": "小孩乱动舅舅炒股电脑遭斥责，两百万购股惊呆舅舅", "source_video_summary": "小远乱动舅舅专门用来炒股的电脑，被舅妈厉声斥责，还连带被骂母子俩都是麻烦精，小远母亲连忙道歉并要求孩子赔罪...", "source_video_tag":["炒股","家庭矛盾","孩童调皮","意外操作","震惊"] }, { "source_video_index": 2, "source_video_url": "https://.../3.mp4?...", "source_video_title": "小孩擅用两百万买垃圾股被骂，股价暴涨惊呆众人", "source_video_summary": "居家场景中，小远将账户里的两百万全部买入濒临退市的垃圾股，家人得知后震怒，打算抛售止损时被小远阻拦...", "source_video_tag":["股票投资","家庭冲突","反转剧情","意外惊喜","亲子矛盾"] } ], "storyline_clips": [ { "clip_index": 0, "source_video_index": 0, "clip_start_time": 9.12, "clip_end_time": 43.28, "clip_title": "男子咨询购股建议，被怂恿投入二百万购买八三零六股票", "clip_summary": "故事发生在居家室内场景，男子坐在书桌前打电话向吴老师确认是否购入八三零六股票...", "clip_dialogue": "吴老师。我按您所说的，那个，买八三零六这支股票，对吧？你听我的，把所有的存款全投进去...", "clip_score": 3.5, "clip_snapshot_url": "https://.../a6265e892dcb404fb9253e442ab06614?..." }, // ... 此处省略其余 8 个剧情片段 ... ], "storyline_highlights": [ { "highlight_index": 0, "highlight_clips_index": [0, 1, 2], "highlight_title": "男子轻信荐股要投全部积蓄，少年得知隐患打算帮忙", "highlight_summary": "男子接到荐股老师电话，对方怂恿他把二百万存款全买股票8306，还借股神名言劝他抓住机会。少年听到对话后查询得知该股是空壳公司，担心家人受损决心出手帮忙。" }, // ... 此处省略其余 2 个高光故事线 ... ] }, "created_at": 1778834568, "finished_at": 1778835452, "expires_at": 1778921851 } ``` #### 第 3 步：解读分析结果剧情故事线分析任务返回结果中的 `result` 字段包含以下三个关键部分： |**字段** |**这是什么？** |**有什么用？** | |---|---|---| |`source_video_info` |**您输入的原始视频文件的基本信息列表**。如果您一次性提交了 3 个视频文件进行分析，那么这个列表里就会有 3 个对象，分别对应这 3 个文件的信息（如原始 URL、AI 生成的标题和简介等）。 |可用于**追溯来源**。`storyline_clips` 中的每个片段都会标明它来自哪个源视频。当您需要知道某个片段具体出自您输入的哪个文件时，可以使用索引找到源文件的详细信息。 | |`storyline_clips` |**AI 整理的视频片段信息**。AI 将整个长视频（或多个视频拼接后）的故事，按剧情发展智能切分成一个个按时间顺序排列的基础视频片段。每个片段都包含标题、简介、在源视频中的起止时间以及精彩度评分。 |* **生成视频章节或时间轴**：直接利用每个片段的时间戳 (`clip_start_time`, `clip_end_time`) 和标题 (`clip_title`)，在播放器上生成时间锚点，方便用户快速跳转到感兴趣的剧情。

* **制作“精彩集锦”** ：通过 `clip_score` 筛选出分数高的片段，然后使用[音视频裁剪](https://www.volcengine.com/docs/6448/2279960)和[音视频拼接](https://www.volcengine.com/docs/6448/2279956)工具快速生成高光集锦。

* **实现内容精确检索**：可以基于每个片段的简介 (`clip_summary`) 或对白 (`clip_dialogue`)，让用户搜索视频中的特定情节。 | |`storyline_highlights` |**AI 提炼的高光故事线信息**。这是算法基于 `storyline_clips` 整理、归纳出的故事线，通过 `highlight_clips_index` 列表，说明这条故事线是由哪些视频片段（clips）组成的。 |可用于实现“**只看 TA**”或**按主题/角色线索观看**的功能。例如，您可以根据 `highlight_title` 找到用户可能感兴趣的故事线，然后通过 `highlight_clips_index` 获取构成这条线的所有视频片段的索引，最后将这些片段拼接起来，为用户提供一个聚焦于特定角色或情节的连续播放体验。 | ## 故事线数据应用示例获取到结构化的故事线数据后，您可以轻松实现多种高级功能。 ### 示例 1：智能生成预告片或精彩集锦 * **目标**：自动从长视频中筛选精彩片段，快速剪辑生成一段高光集锦或预告片。 * **实现方式**： 1. 遍历 `result.storyline_clips` 数组。 2. 根据 `clip_score` 字段对所有剧情片段进行降序排序。 3. 选取评分最高的 Top N 个片段作为高光素材。 4. 提取这些片段的源文件（通过 `source_video_index` 确定）以及在源文件中的起止时间（`clip_start_time` 和 `clip_end_time`）。 5. 调用[音视频裁剪](https://www.volcengine.com/docs/6448/2279960)工具逐个裁出高光片段，再调用[音视频拼接](https://www.volcengine.com/docs/6448/2279956)工具将它们合成为一个集锦视频。 ### 示例 2：实现“只看 TA”或按角色/主题线索播放 * **目标**：允许用户只观看与特定角色（如某个演员）、特定主题（如爱情线、事业线）相关的所有剧情片段。 * **实现方式**： 1. 遍历 `result.storyline_highlights` 数组，将其中的 `highlight_title` 作为可供用户选择的角色或主题列表。 2. 当用户选择一个主题时（例如，标题为“事业线：从迷茫到坚定”的故事线），获取其 `highlight_clips_index` 数组（例如 [0, 1, 5, 12]）。 3. 使用这些索引，从 `result.storyline_clips` 数组中找到所有对应的剧情片段。 4. 将这些片段的起止时间构造成一个播放列表，或使用[音视频裁剪](https://www.volcengine.com/docs/6448/2279960)和[音视频拼接](https://www.volcengine.com/docs/6448/2279956)工具将它们拼接成一个新视频，即可实现“只看 TA”的效果。 ### 示例 3：实现互动式播放与内容检索 * **目标**：丰富播放体验，让用户可以在播放器上按章节跳转，或通过关键词精确搜索视频内的情节和对话。 * **实现方式**： * **生成视频章节与时间轴标记** 1. 遍历 `result.storyline_clips` 数组。 2. 对于每个片段，使用 `clip_start_time` 在播放器进度条上创建一个时间标记点（“打点”）。 3. 将 `clip_title` 作为该标记点的标题，`clip_summary` 作为简介。 4. 如果请求时设置了 `"enable_snapshot": true`，则可将 `clip_snapshot_url` 作为该标记点的预览图。 5. 为每个标记点绑定点击事件，当用户点击时，播放器跳转 (seek) 到对应的 `clip_start_time`。 * **实现基于内容的精确搜索** 1. 在您的后端，遍历 `result.storyline_clips` 数组，为每个视频构建一个简单的搜索索引。 2. 将每个片段的 `clip_index`、`clip_title`、`clip_summary` 和 `clip_dialogue` 存储在可被搜索的数据结构中。 3. 提供一个搜索框，当用户输入关键词（如角色名、地名、台词片段）时，在您构建的索引中进行匹配。 4. 返回匹配到的剧情片段列表（包含标题、简介、时间戳等），用户点击即可跳转到相应位置。 ## 参考信息 ### 核心优势 * **结构化故事线生成**：将视频内容转化为按时间戳排序的剧情片段（Clips），输出包含标题（Title）、摘要（Summary）、对话（Dialogue）、高光打分（Score）和关键帧（Snapshot）的标准 JSON 格式，对 Agent 和大模型理解使用友好。 * **长视频与多片源理解**：支持长达 3.5 小时的长视频处理，并可接收多个视频文件作为输入，一次性完成整部剧集或系列视频的连续性故事线分析。 ### 使用限制与性能 |**限制项** |**说明** | |---|---| |**输入文件限制** |* **文件来源**：仅支持公网可访问的 HTTP/HTTPS URL。

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

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

* **时长限制**：累计总时长不得超过 210 分钟（即 3.5 小时），单视频文件时长建议不得超过 150 分钟（即 2.5 小时）。

* **输入分辨率限制**：最高支持 1080p。 | |**并发限制** |单个账号默认支持同时处理 20 个任务，超出部分将自动进入队列排队。 | |**处理耗时** |任务处理时长与视频的原始时长相关。视频时长越长，处理耗时越长。平均 RTF（处理耗时/原片时长）为3～5。 | ## 相关 API 文档 * [提交剧情故事线分析任务 API](https://www.volcengine.com/docs/6448/2464616) * [查询任务信息 API](https://www.volcengine.com/docs/6448/2278532) * [事件回调](https://www.volcengine.com/docs/6448/2288701)

智能处理