视频点播剧情故事线分析功能能够深入理解您输入的单个或多个长视频（如电影、电视剧，单文件时长不超过 2.5 小时），然后输出一份结构化的 JSON 故事线。这份故事线由一系列按时间排列的剧情片段 Clips 组成，每个片段都包含标题、梗概、高光评分和关键帧快照。这使您能够将非结构化的视频内容数据化，为媒资的自动化运营和深度检索提供强大支持。该功能是实现智能预告片生成、播放器章节导航以及基于剧情内容的高级搜索等应用的核心。

本文档将指导您如何通过调用视频点播 OpenAPI 实现剧情故事线分析。

适用场景 #

• 智能预告片/集锦生成：基于故事线分析结果，快速定位高光或关键剧情片段，自动化生成引人入胜的预告片或集锦视频。
• 扩充视频元数据：为媒资库中的长视频自动生成结构化的章节、看点和剧情标签，极大提升内容检索和管理的效率。
• 互动式播放：便于开发“剧情跳转”、“角色视角”等高级播放器功能，让观众可根据故事线快速定位到感兴趣的情节。
• 精准内容定位：实现基于剧情内容的深度搜索（例如“搜索男主角表白的片段”），并根据用户偏好推荐相关的剧情片段。

能力与限制 #

计费说明 #

使用剧情故事线分析功能会产生以下费用：

• 故事线分析费用：按输入片源时长计费，价格为 1 元/分钟。
• 媒资存储费用：您上传用于处理的原始视频文件需要存储在视频点播空间中。这将根据存储量和存储时长产生费用，详见媒资存储计费。

前提条件 #

• 已注册火山引擎账号并完成实名认证。
• 已开通视频点播服务并创建空间。
• 已将待处理的音视频文件上传至点播空间，并获取 Vid 或 FileName。

实现流程 #

步骤 1：提交剧情故事线分析任务 #

调用 StartExecution 接口，提交一个异步的故事线分析任务。以下为任务的核心参数配置。

• MultiInputs: 用于指定一个或多个输入视频文件，传入一个包含多个 Input 对象的数组。
  • Type: 设置为 Vid 或 DirectUrl。
  • Vid / DirectUrl: 提供待处理文件的 Vid 或 FileName 信息。
• Operation.Task: 定义要执行的任务。
  • Type: 必须设置为 Storyline。
  • Storyline.WithSnapshot: 建议设置为 true，以便为每个剧情片段生成关键帧快照。

以下示例展示了如何为 3 个视频文件（剧集的前三集）提交一个故事线分析任务。

POST https://vod.volcengineapi.com?Action=StartExecution&Version=2025-01-01
{
  "MultiInputs": [
    {
      "Type": "Vid",
      "Vid": "v0ccfeg7007acsg***episode01"
    },
    {
      "Type": "Vid",
      "Vid": "v0ccfeg7007acsg***episode02"
    },
    {
      "Type": "Vid",
      "Vid": "v0ccfeg7007acsg***episode03"
    }
  ],
  "Operation": {
    "Type": "Task",
    "Task": {
      "Type": "Storyline",
      "Storyline": {
        "WithSnapshot": true
      }
    }
  }
}

成功提交后，您将从响应中获得任务的唯一标识 RunId。请务必保存此 ID，用于后续查询任务结果。

步骤 2：获取任务结果 #

任务提交后，系统将在后台进行异步处理。您可以通过以下任一方式获取结果：

• 主动查询：调用 GetExecution 接口，并传入步骤 1 中获取的 RunId 来获取任务结果。

  GET https://vod.volcengineapi.com?Action=GetExecution&Version=2025-01-01&RunId=hb:ebd05bee1f3873***f7316c742b5f
  

• 事件通知：

  1. 参考事件通知概述文档，配置一个用于接收回调的服务地址。在订阅事件时，勾选媒体处理任务执行完成事件。
  2. 当任务完成时，您的服务将收到一个 EventType 为 ExecutionComplete 的 HTTP POST 请求。

当返回结果中的 Status 字段值为 Success 时，表示任务已成功完成。您可以在 Output.Task.Storyline 字段中找到分析后的故事线数据。以下为 Clips 数组中每个对象的字段说明。关于完整的响应参数结构，请参见 OutputTaskStoryline。

成功响应示例：

{
  "ResponseMetadata": {
    // ... 省略通用元数据
  },
  "Result": {
    "RunId": "hb:c5cacd4946bd***a5fd9f74159b03ae8",
    "Status": "Success",
    // ... 省略任务元数据、输入、操作等信息
    "Output": {
      "Type": "Task",
      "Task": {
        "Type": "Storyline",
        "Storyline": {
          "Clips": [
            {
              "VideoIndex": 0,
              "Title": "雨夜初遇",
              "Summary": "主角李明在雨夜中首次登场，回忆起童年的往事，为故事埋下伏笔。",
              "Snapshot": "storyline/snapshots/a1b2c3d4.jpg",
              "Score": 4.5,
              "Dialogue": "“这么大的雨，也不知道什么时候能停。”",
              "Start": 25.5,
              "End": 88.0
            },
            {
              "VideoIndex": 0,
              "Title": "咖啡馆的邂逅",
              "Summary": "李明与女主角王静在咖啡馆偶然相遇，两人因一本共同喜爱的书而产生交集。",
              "Snapshot": "storyline/snapshots/e5f6g7h8.jpg",
              "Score": 4.8,
              "Dialogue": "“原来你也喜欢这本书？” “是啊，这是我最喜欢的作家。”",
              "Start": 150.2,
              "End": 235.8
            }
            // ... 更多剧情片段
          ]
        }
      }
    }
  }
}

步骤 3：应用故事线数据 #

获取到结构化的故事线数据后，您可以进行丰富的二次开发和应用，例如：

• 实现视频章节跳转：使用 Title、Start 和 End，在您的播放器上生成带有标题的章节列表或时间轴标记点，允许用户快速跳转。
• 构建内容摘要页面：提取 Title、Summary 和拼接后的快照 URL，自动生成图文并茂的剧情摘要页面。

相关 API 文档 #

• 提交剧情故事线分析 API
• 获取媒体处理任务执行结果 API
• 媒体处理任务执行完成事件