AI MediaKit 剧情故事线分析工具能够智能理解您输入的单个或多个长视频（如电影、电视剧，长达 3.5 小时），并输出一份结构化的 JSON 数据。该工具将非结构化长视频智能解析为可检索、可运营的结构化剧情故事线，为实现媒资检索、智能预告片生成、播放器章节导航以及基于剧情内容的高级搜索等提供强大助力。

本篇开发指南将引导您：

快速体验通过 API 调用，将长视频解析为结构化的故事线数据。

深入理解返回结果中 storyline_clips 和 storyline_highlights 的区别与使用方法。

学习如何基于分析结果，实现“高光集锦生成”、“只看 TA”等高级功能。

快速入门：实现剧情故事线分析

准备工作

获取访问凭证：在开始之前，访问 AI MediaKit 控制台 API Key 管理页面，创建并获取 AI MediaKit API Key。

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

操作流程

剧情故事线分析是一个异步任务，整体流程如下：

成功调用 POST /api/v1/tools/analyze-video-storyline 后，API 将返回一个任务 ID 。

您可以轮询 GET /api/v1/tasks/{task_id} ，直到任务状态status 变为 completed；或者使用事件回调自动接收任务状态变化。

任务完成后，您从响应的 result 字段中解析结构化的故事线数据。

第 1 步：提交分析任务

您可以直接复制以下 cURL 命令，提交一个分析任务。本示例输入了两个视频文件，并要求为每个剧情片段生成关键帧快照。

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

第 2 步：获取分析结果

故事线分析需要时间，您需要通过轮询查询任务信息 API 来获取最终结果，直到任务状态变为 completed。

任务成功完成后，您将收到包含详细分析结果的响应。result 字段即为结构化的故事线数据。

第 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 筛选出分数高的片段，然后使用音视频裁剪和音视频拼接工具快速生成高光集锦。实现内容精确检索：可以基于每个片段的简介 (clip_summary) 或对白 (clip_dialogue)，让用户搜索视频中的特定情节。
storyline_highlights	AI 提炼的高光故事线信息。这是算法基于 storyline_clips 整理、归纳出的故事线，通过 highlight_clips_index 列表，说明这条故事线是由哪些视频片段（clips）组成的。	可用于实现“只看 TA”或按主题/角色线索观看的功能。例如，您可以根据 highlight_title 找到用户可能感兴趣的故事线，然后通过 highlight_clips_index 获取构成这条线的所有视频片段的索引，最后将这些片段拼接起来，为用户提供一个聚焦于特定角色或情节的连续播放体验。

故事线数据应用示例

获取到结构化的故事线数据后，您可以轻松实现多种高级功能。

示例 1：智能生成预告片或精彩集锦

目标：自动从长视频中筛选精彩片段，快速剪辑生成一段高光集锦或预告片。

实现方式：

遍历 result.storyline_clips 数组。

根据 clip_score 字段对所有剧情片段进行降序排序。

选取评分最高的 Top N 个片段作为高光素材。

提取这些片段的源文件（通过 source_video_index 确定）以及在源文件中的起止时间（clip_start_time 和 clip_end_time）。

调用音视频裁剪工具逐个裁出高光片段，再调用音视频拼接工具将它们合成为一个集锦视频。

示例 2：实现“只看 TA”或按角色/主题线索播放

目标：允许用户只观看与特定角色（如某个演员）、特定主题（如爱情线、事业线）相关的所有剧情片段。

实现方式：

遍历 result.storyline_highlights 数组，将其中的 highlight_title 作为可供用户选择的角色或主题列表。

当用户选择一个主题时（例如，标题为“事业线：从迷茫到坚定”的故事线），获取其 highlight_clips_index 数组（例如 [0, 1, 5, 12]）。

使用这些索引，从 result.storyline_clips 数组中找到所有对应的剧情片段。

将这些片段的起止时间构造成一个播放列表，或使用音视频裁剪和音视频拼接工具将它们拼接成一个新视频，即可实现“只看 TA”的效果。

示例 3：实现互动式播放与内容检索

目标：丰富播放体验，让用户可以在播放器上按章节跳转，或通过关键词精确搜索视频内的情节和对话。

实现方式：

生成视频章节与时间轴标记

遍历 result.storyline_clips 数组。

对于每个片段，使用 clip_start_time 在播放器进度条上创建一个时间标记点（“打点”）。

将 clip_title 作为该标记点的标题，clip_summary 作为简介。

如果请求时设置了 "enable_snapshot": true，则可将 clip_snapshot_url 作为该标记点的预览图。

为每个标记点绑定点击事件，当用户点击时，播放器跳转 (seek) 到对应的 clip_start_time。

实现基于内容的精确搜索

在您的后端，遍历 result.storyline_clips 数组，为每个视频构建一个简单的搜索索引。

将每个片段的 clip_index、clip_title、clip_summary 和 clip_dialogue 存储在可被搜索的数据结构中。

提供一个搜索框，当用户输入关键词（如角色名、地名、台词片段）时，在您构建的索引中进行匹配。

返回匹配到的剧情片段列表（包含标题、简介、时间戳等），用户点击即可跳转到相应位置。

参考信息

核心优势

结构化故事线生成：将视频内容转化为按时间戳排序的剧情片段（Clips），输出包含标题（Title）、摘要（Summary）、对话（Dialogue）、高光打分（Score）和关键帧（Snapshot）的标准 JSON 格式，对 Agent 和大模型理解使用友好。

长视频与多片源理解：支持长达 3.5 小时的长视频处理，并可接收多个视频文件作为输入，一次性完成整部剧集或系列视频的连续性故事线分析。

使用限制与性能

限制项	说明
输入文件限制	文件来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, flv, ts, avi, mov, wmv, mkv 等主流视频格式。数量限制：单次任务最多支持传入 30 个视频文件。时长限制：累计总时长不得超过 210 分钟（即 3.5 小时），单视频文件时长建议不得超过 150 分钟（即 2.5 小时）。输入分辨率限制：最高支持 1080p。
处理耗时	任务处理时长与视频的原始时长相关。视频时长越长，处理耗时越长。平均 RTF（处理耗时/原片时长）为3～5。