You need to enable JavaScript to run this app.
文档中心
文档备案控制台
视频点播

视频点播

请输入
  • 文档首页
    • 视频点播视频 AI 应用短剧高光智剪通过 API 接入短剧高光智剪
复制全文
下载 pdf
我的收藏
短剧高光智剪
通过 API 接入短剧高光智剪
复制全文
下载 pdf
我的收藏
通过 API 接入短剧高光智剪

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

说明

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

能力与限制

在使用本功能前，请确保您的输入视频满足以下条件，否则任务可能会执行失败。

限制类别

具体要求

输入配额

  • 文件数量：单次任务最多支持输入 30 个视频文件。
  • 累计时长：所有输入文件的累计总时长不得超过 45 分钟。

说明

如需提升配额至 100 个文件、总时长 300 分钟，请提交工单联系火山引擎技术支持团队申请。

技术规格

  • 编码格式：仅支持 H.264 和 H.265 编码。
  • 分辨率：不得超过 1080p。
  • 流信息：视频必须同时包含视频流和音频流。

输入素材要求

  • 视频画面要求：视频画面下半部分（垂直位置 0.5-1.0 范围内）必须包含清晰居中的中文字幕。
  • 音频流要求：视频的音频轨道中必须包含清晰可识别的中文对话文本。仅包含 BGM（含歌词）、纯音乐、语气词或无有效语义的声音，将无法准确识别剧情逻辑。

功能适用性

“短剧三要素”（MiniseriesEdit 模式）仅适用于竖屏短剧，暂不支持横屏剧。

前提条件

快速入门（一键生成带“三要素”的短剧混剪）

以下步骤将指导您通过调用 API，快速实现一个最常用的场景：输入多集短剧素材，自动混剪生成一个带有“短剧三要素”（短剧名、角标、提示语）的、可直接投放的营销视频。

步骤 1：提交任务

调用 StartExecution 接口提交一个异步的高光智剪任务。核心请求参数如下：

  • MultiInputs: 传入多个短剧视频的 Vid 列表。
  • Operation.Task.Type: 设置为 Highlight，表示执行高光智剪任务。
  • Operation.Task.Highlight.Mode: 设置为 StorylineCuts（故事线混剪模式）。
  • Operation.Task.Highlight.HighlightCuts: 通过 MinDuration、MaxDuration 和 MaxNumber 参数，控制最终输出高光片段的最小时长、最大时长以及最多片段数。

    注意

    算法最终输出的高光时长会尽量趋近于您设置的 MinDuration 和 MaxDuration 范围，实际时长与设定值可能存在几秒钟的微小误差。

  • Operation.Task.Highlight.Edit.Mode: 设置为 MiniseriesEdit，以启用短剧三要素模板。
  • Operation.Task.Highlight.Edit.MiniseriesEdit: 配置短剧三要素的具体内容。

请求示例

以下示例将分析 3 集短剧，并自动生成 1 个时长在 60-180 秒之间的高光混剪视频。

说明

以下 HTTP 示例仅展示核心的业务参数，省略了 Authorization 请求头中的签名计算等鉴权细节。在实际发起请求前，请参考如何调用 OpenAPI 文档，了解如何在线测试接口、获取可运行的 curl 命令以及完整的 HTTP 请求构造方法与签名机制。

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,
          "MaxNumber": 1
        },
        "Edit": {
          "Mode": "MiniseriesEdit",
          "MiniseriesEdit": {
            "Template": "热门短剧1",
            "Title": "《败给月光》", // 此处可替换短剧名
            "Hint": "影视效果 请勿模仿 无不良价值观引导" // 此处可替换短剧提示语
          }
        }
      }
    }
  }
}

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

步骤 2：获取任务结果

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

  • OpenAPI：间隔一段时间后，调用 GetExecution 接口，并传入步骤 1 中获取的 RunId 来获取高光智剪结果。

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

  • 事件通知：

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

当任务 Status 为 Success 时，表示已成功生成高光视频。您可以在 Output.Task.Highlight.Edits 字段中找到最终剪辑生成的视频产物信息。您需要获取产物的 FileName 或 Vid。

步骤 3：获取产物 URL

获取到高光视频的 FileName 或 Vid 后，您需要将其转换为公网可访问的 URL，以便于播放或下载。

说明

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

方式 1：调用 GetPlayInfo 接口

调用 GetPlayInfo 接口，传入您获取到的 Vid。成功调用后，系统会在响应体 Result.PlayInfoList 中返回播放 URL。

方式 2：基于 FileName 手动拼接

一个基础的访问 URL 由以下部分组成：[Protocol]://[PlaybackDomain]/[FileName]

  • [Protocol]：通常为 https 或 http。取决于您是否配置 SSL 证书。
  • [PlaybackDomain]：您在点播控制台配置的加速域名。
  • [FileName]：您从 GetExecution 结果中获取的产物 FileName。

拼接示例：假设您的加速域名为 play.example.com，获取到的文件 FileName 为 video.mp4，那么拼接后的基础 URL 为：https://play.example.com/video.mp4

说明

为了防止资源被盗链，视频点播支持 URL 鉴权功能。如果您在视频点播控制台开启了 URL 鉴权，仅拼接基础 URL 还无法直接访问，您必须为其附加一个动态计算的鉴权参数（如 auth_key）。

  • 如何生成鉴权参数：URL 鉴权需要遵循一套严格的签名算法。详细的计算方法和不同语言的实现示例，请参见 URL 鉴权概述。
  • 附带鉴权的完整 URL 示例：https://play.example.com/video.mp4?auth_key=1732529334-0-0-a1b2c3d4e5f6...

进阶使用

切换“短剧三要素”视觉模板

“短剧三要素”是经过市场验证的、能有效提升营销视频吸引力的三种关键视觉元素：

  • 短剧名：在画面上展示剧名，用于品牌识别和引导用户搜索。
  • 角标：通常位于角落，带有“热门短剧”、“爆款推荐”等文字的标签，用于营造“这部剧很受欢迎，值得一看”的心理暗示，吸引用户点击。
  • 提示语：画面左右两侧的一行文字，可以是概括视频核心冲突或亮点的引导性文字，也可以是类似“影视效果 请勿模仿 无不良价值观引导”的免责声明。

上文“快速入门”的示例中使用了 "热门短剧1" 视觉模板。视频点播提供以下 5 个预设的视觉模板，您可以根据视频内容或投放渠道的风格，选择不同的模板来改变“短剧三要素”的呈现样式。
Image

顺剪 vs. 混剪

默认情况下，高光智剪任务采用混剪模式，即打乱原始视频片段的时序，以达到最佳的戏剧冲突效果。如果您希望剪辑出的视频能基本保持原始剧情的时间顺序（仅去除片头片尾等非正片内容），可以通过 MiniseriesOption.CutMode 参数将剪辑模式设置为 Sequential（顺剪）。

{
    "Input": { ... },
    "Operation": {
        "Type": "Task",
        "Task": {
            "Type": "Highlight",
            "Highlight": {
                "Mode": "StorylineCuts",
                "HighlightCuts": {
                    "MiniseriesOption": {
                        "CutMode": "Sequential" // 设置为顺剪模式
                    }
                },
                "Edit": { "Mode": "HighlightClips" }
            }
        }
    }
}

开启智能精彩前置

您可以通过 OpeningHook.WithOpeningHook 参数开启智能精彩前置功能。系统默认会将视频中最精彩的 5-15 秒片段前置到素材片头，且前置片段本身也由不短于 5 秒的子片段构成。这一配置旨在快速抓住用户眼球，是提升广告转化率的有效手段。

{
    "Input": { ... },
    "Operation": {
        "Type": "Task",
        "Task": {
            "Type": "Highlight",
            "Highlight": {
                "Mode": "StorylineCuts",
                "OpeningHook": {
                    "WithOpeningHook": true // 开启精彩前置
                },
                "Edit": { "Mode": "HighlightClips" }
            }
        }
    }
}

自定义剪辑参数

如果您不想使用 MiniseriesEdit 的模板化样式，或者想对输出视频的编码、分辨率等进行更精细的控制，可以使用 CustomEdit 模式。您需要设置 Edit.Mode 为 CustomEdit，并在 CustomEdit 对象中定义画布、编码等参数。

{
    "Input": { ... },
    "Operation": {
        "Type": "Task",
        "Task": {
            "Type": "Highlight",
            "Highlight": {
                "Mode": "StorylineCuts",
                "Edit": {
                    "Mode": "CustomEdit",
                    "CustomEdit": {
                        "Canvas": { "Width": 1080, "Height": 1920 },
                        "Output": {
                            "Format": "mp4",
                            "Codec": { "VideoCodec": "h264", "Crf": 25 }
                        }
                    }
                }
            }
        }
    }
}

获取详细 AI 分镜信息

默认情况，系统仅返回最终剪辑生成的视频产物 Edits 和构成该产物的高光片段列表 HighlightCuts.Cuts。如果您除了需要最终成片，还希望获得 AI 在分析过程中产出的所有分镜信息（包括那些未被最终剪辑选中的片段），以便进行更深入的数据分析或二次开发，您可以在 HighlightCuts 参数中，将 WithStoryboard 设置为 true。

{
    "Input": { ... },
    "Operation": {
        "Type": "Task",
        "Task": {
            "Type": "Highlight",
            "Highlight": {
                "Mode": "StorylineCuts",
                "HighlightCuts": {
                    "WithStoryboard": true // 开启分镜信息输出
                },
                "Edit": { "Mode": "HighlightClips" }
            }
        }
    }
}

任务成功后，返回结果中会新增一个 Storyboard 数组，包含算法从原始视频中基于分镜理解提取出的视频片段信息。每个片段都包含起止时间、高光打分、字幕信息、剧情描述以及片段源自哪个输入视频等信息。

{
  "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": [ // 核心产物：自动剪辑生成的视频列表
            {
              "FileName": "ed8e37546d214727b6fb5d22beec****.mp4",
              "Size": "66761331"
            },
            {
              "FileName": "d8f463efb8f3****ff9a8d10296.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
            ]
          }
        }
      }
    }
  }
}

相关 API 文档

参考信息

短剧高光剪辑参数配置最佳实践

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

  • 输入视频：建议选取短剧的前 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 秒的子片段构成。这一配置旨在快速抓住用户眼球，是提升广告转化率的有效手段。
最近更新时间：2026.04.20 19:47:46
这个页面对您有帮助吗？
有用
有用
无用
无用