通过 API 接入--视频点播-火山引擎

文档中心

立即注册

导航

通过 API 接入

最近更新时间：2025.11.27 15:30:59首次发布时间：2025.11.27 15:30:59

本文面向开发者，详细介绍如何通过 API 调用短剧高光智剪能力，将短剧素材的自动化生产流程无缝集成到您的业务系统中。您将了解到 API 的核心调用流程、参数配置，并通过丰富的代码示例快速上手。

说明

在开始之前，建议您先阅读短剧高光智剪的快速开始指南，了解其核心功能、应用场景和计费规则，并通过控制台操作体验短剧高光智剪的实际效果。

前提条件

已开通视频点播服务并创建空间。
将待处理的音视频文件上传至点播空间，并获取对应的 Vid（视频 ID）。

实现流程

步骤 1：提交高光智剪任务

调用 StartExecution 接口提交高光智剪任务。支持输入单个或多个短剧视频进行高光分析。您需要关注以下核心参数：

参数	说明
`MultiInputs.Type`	设置为 `Vid` 或 `DirectUrl`，指定输入视频的来源类型。若选择 `Vid` 模式，需设置 `MultiInputs.Vid` 参数为视频 Vid。若选择 `DirectUrl` 模式，需设置 `MultiInputs.DirectUrl` 参数为视频 FileName。
`Operation.Type`	设置为 `Task`，表示执行单任务。
`Operation.Task.Type`	设置为 `Highlight`，表示执行高光分析任务。
`Operation.Task.Highlight.Mode`	设置为 `StorylineCuts`（故事线混剪模式）。
`Operation.Task.Highlight.HighlightCuts`	配置参数：通过`WithStoryboard`参数选择是否输出算法基于分镜理解得出的视频片段信息。通过 `MinDuration`、`MaxDuration` 和 `MaxNumber` 参数限制输出高光片段的最小时长、最大时长以及最多片段数。注意在实际高光分析过程中，为确保剧情的连贯性并保留“钩子”剧情，算法所输出高光视频的时长可能不会与您所设置的 `MinDuration` 和 `MaxDuration` 严格相符。
`Operation.Task.Highlight.OpeningHook`	（可选）通过该参数开启并配置智能精彩前置功能。系统将自动分析并提取视频中最精彩的片段，将其置于视频开头，以吸引观众。
`Operation.Task.Highlight.Edit`	配置剪辑成片。支持`HighlightClips`（使用默认参数快速剪辑）或`CustomEdit`（自定义输出参数）。

说明

为了帮助您高效生成用于广告投放的高转化率素材，我们根据短剧行业的投放经验，提供以下参数配置最佳实践：

输入视频：建议选取短剧的前 10-20 集免费剧集作为高光分析的输入源。这些剧集是吸引新用户的关键，将其中的强冲突、高能反转片段进行混剪，能有效提升广告素材的点击和转化率。
目标生成时长：广告投放素材通常有固定的时长范围。您可以通过 MinDuration 和 MaxDuration 参数来控制生成的高光集锦总时长：
- 1-3 分钟素材：设置 MinDuration 为 60，MaxDuration 为 180。
- 3-5 分钟素材：设置 MinDuration 为 180，MaxDuration 为 300。
- 5-7 分钟素材：设置 MinDuration 为 300，MaxDuration 为 420。
智能精彩前置：建议开启智能精彩前置功能，并使用系统默认配置。系统默认会将视频中最精彩的 5-15 秒片段前置到素材片头，且前置片段本身也由不短于 5 秒的子片段构成。这一配置旨在快速抓住用户眼球，是提升广告转化率的有效手段。

以下示例分别演示了如何使用一键剪辑 HighlightClips 和自定义剪辑 CustomEdit 两种模式来提交任务。

一键剪辑

自定义剪辑

此模式下，您无需关心具体的剪辑参数。系统将自动应用一套默认的剪辑配置，快速生成高光集锦视频。以下示例演示了如何提交一个任务，用于分析多个短剧视频，并自动剪辑生成一个时长在 60-180 秒、带精彩前置的高光视频。

POST https://vod.volcengineapi.com?Action=StartExecution&Version=2025-01-01
{
  "MultiInputs": [
    { "Type": "Vid", "Vid": "your_drama_vid_1" },
    { "Type": "Vid", "Vid": "your_drama_vid_2" },
    { "Type": "Vid", "Vid": "your_drama_vid_3" }
  ],
  "Operation": {
    "Type": "Task",
    "Task": {
      "Type": "Highlight",
      "Highlight": {
        "Mode": "StorylineCuts",
        "HighlightCuts": {
          "WithStoryboard": true,
          "MinDuration": 60,
          "MaxDuration": 180,
          "MaxNumber": 1
        },
        "OpeningHook": {
          "WithOpeningHook": true
        },
        "Edit": {
          "Mode": "HighlightClips" 
        }
      }
    }
  }
}

此模式下，您可以通过 CustomEdit 对象，详细自定义最终输出视频的画布尺寸、编码格式、码率等参数，以满足特定的业务需求。

POST https://vod.volcengineapi.com?Action=StartExecution&Version=2025-01-01
{
  "MultiInputs": [
    { "Type": "Vid", "Vid": "your_drama_vid_1" },
    { "Type": "Vid", "Vid": "your_drama_vid_2" },
    { "Type": "Vid", "Vid": "your_drama_vid_3" }
  ],
  "Operation": {
    "Type": "Task",
    "Task": {
      "Type": "Highlight",
      "Highlight": {
        "Mode": "StorylineCuts",
        "HighlightCuts": {
          "MinDuration": 60,
          "MaxDuration": 180
        },
        "OpeningHook": {
          "WithOpeningHook": true
        },
        "Edit": {
          "Mode": "CustomEdit",
          "CustomEdit": {
            "Canvas": {
              "Width": 1080,
              "Height": 1920
            },
            "Output": {
              "Format": "mp4",
              "Codec": {
                "VideoCodec": "h264",
                "Crf": 25
              }
            }
          }
        }
      }
    }
  }
}

成功提交后，系统将返回任务的唯一标识 RunId，用于后续查询结果。

步骤 2：获取任务结果

通过以下方式获取高光分析结果：

OpenAPI：任务提交后，系统会在后台进行异步处理。您可以间隔一段时间后，调用 GetExecution 接口，并传入步骤 1 中获取的 RunId 来获取高光分析结果。当返回结果中的 Status 字段值为 Success 时，表示任务已成功完成。
```
GET https://vod.volcengineapi.com?Action=GetExecution&Version=2025-01-01&RunId=hb:ebd05bee1f3873***f7316c742b5f
```
事件通知：
1. 参考事件通知概述文档，配置一个用于接收回调的服务地址。在订阅事件时，勾选媒体处理任务执行完成事件。
2. 当任务完成时，您的服务将收到一个 EventType 为 ExecutionComplete 的 HTTP POST 请求。可从回调结果中 OutputTaskHighlight 获取高光分析结果。

高光分析结果具体说明如下：

Output.Task.Highlight.Edits：自动剪辑生成的视频产物的信息，包含 Vid、FileName。
Output.Task.Highlight.HighlightCuts.Cuts：算法根据 StartExecution 接口请求参数 HighlightCuts 中输入的条件限制提取高光片段信息。片段分为 HighlightClip（普通高光片段）和 OpeningHook（视频前置精彩片段）两种类型。
Output.Task.Highlight.HighlightCuts.Storyboard：算法基于分镜理解得出的视频片段信息。每个片段涵盖片段开始时间、结束时间、高光打分、字幕信息、剧情描述以及片段源自哪个输入视频等信息。

详细参数介绍，请见 OutputTaskHighlightCuts。

{
  "ResponseMetadata": {
    "RequestId": "20251119192326ABCDE****FGHIJ",
    "Action": "GetExecution",
    ...
  },
  "Result": {
    "RunId": "hb:7672d353e4f3a3718724654b8ce****",
    "Status": "Success",
    // --- 省略 Meta, MultiInputs, Operation 等回显信息 ---
    "Output": {
      "Type": "Task",
      "Task": {
        "Type": "Highlight",
        "Highlight": {
          "Duration": 350.26,
          "Edits": [ // 核心产物：自动剪辑生成的视频列表
            {
              "Vid": "v02399g10001d4eok5iljht0rkc****",
              "FileName": "ed8e37546d214727b6fb5d22beec8f26.mp4",
              "Size": "66761331"
            },
            {
              "Vid": "v02399g10001d4eokaaljht5a1nqcdd0",
              "FileName": "d8f463efb8f34491a1ec8ff9a8d10296.mp4",
              "Size": "87322441"
            }
            // ... more edited videos
          ],
          "HighlightCuts": { // 补充的分析数据：最终选用的片段信息
            "Cuts": [
              {
                "Clips": [
                  {
                    "Type": "HighlightClip",
                    "Score": 4.5,
                    "Start": 9.467,
                    "End": 13.333,
                    "VideoIndex": 0,
                    "CutStart": 0.0,
                    "CutEnd": 3.866
                  },
                  {
                    "Type": "HighlightClip",
                    "Score": 4.4,
                    "Start": 24.2,
                    "End": 38.567,
                    "VideoIndex": 0,
                    "CutStart": 3.866,
                    "CutEnd": 18.233
                  },
                  {
                    "Type": "HighlightClip",
                    "Score": 4.3,
                    "Start": 15.833,
                    "End": 24.2,
                    "VideoIndex": 0,
                    "CutStart": 18.233,
                    "CutEnd": 26.6
                  }
                  // ... more clips in this cut
                ]
              }
              // ... more cuts
            ],
            "Storyboard": [ // 补充的分析数据：所有识别出的分镜信息
              {
                "VideoIndex": 0,
                "Start": 9.467,
                "End": 13.333,
                "Score": 4.5,
                "Ocr": "陆斯年，我们分手吧！",
                "Description": "视频展示了一对情侣在户外散步的场景..."
              },
              {
                "VideoIndex": 0,
                "Start": 15.833,
                "End": 24.2,
                "Score": 4.3,
                "Ocr": "怎么了？是我哪里惹你，不高兴了吗？...",
                "Description": "视频中，一位穿着白色连衣裙的女性与一位穿着浅色外套的男性在夜晚的户外场景中对话..."
              },
              {
                "VideoIndex": 0,
                "Start": 24.2,
                "End": 38.567,
                "Score": 4.4,
                "Ocr": "求你放过我们家斯年吧！...",
                "Description": "视频展示了一位女性在不同场景下的对话..."
              }
              // ... more storyboards
            ]
          }
        }
      }
    }
  }
}

步骤 3：基于 Vid 或 FileName 获取高光视频 URL

在步骤 2：获取高光视频结果中，您已经获取到了高光视频的 Vid 和 FileName。您需要将这些内部标识转换为公网可播放的 URL。

说明

前提条件：在获取 URL 前，您必须为产物所在的点播空间添加并配置加速域名。所有 URL 都将基于此域名生成。

完成域名配置后，您可通过以下两种方式来获取播放地址。

方式一：服务端调用 GetPlayInfo 接口，传入您在步骤 2 中获取到的 Vid，通过返回参数 PlayInfoList 获取播放地址。
方式二：通过自行拼接的方式获取 URL ，拼接方式如下：
- 拼接规则：Protocol://PlaybackDomain/FileName?auth_key=xxx
- 拼接示例：
  - 假设您配置的点播加速域名 PlaybackDomain 为 play.vod.com
  - 您在步骤 2 中获取到的 FileName 为 highlight_output/autocut_video.mp4。
  - 则该视频的播放地址为 https://play.example.com/highlight_output/autocut_video.mp4。

说明

如果您在视频点播控制台开启了 URL 鉴权，则还需根据鉴权类型计算签名 auth_key，具体请见 URL 鉴权概述。