通过 API 生成解说视频--视频点播-火山引擎

文档中心

导航

通过 API 生成解说视频

最近更新时间：2025.12.08 14:24:14首次发布时间：2025.12.08 10:45:53

本文面向开发者，详细介绍如何通过 API 调用 AI 解说视频生成能力，将解说视频的自动化生产流程无缝集成到您的业务系统中。您只需提供原始短剧视频和创作指令，即可通过 OpenAPI，一键生成带有 AI 配音和解说字幕的全新营销或解说视频。通过本文，您将了解到 API 的核心调用流程、参数配置，并通过丰富的代码示例快速上手。

说明

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

前提条件

已注册火山引擎账号并完成实名认证。
已开通视频点播服务并创建空间。
将待处理的音视频文件上传至点播空间，并获取对应的 Vid（视频 ID）。
开通白名单：使用前请提交工单联系火山引擎技术支持团队申请加入 AI 短剧二创解说的白名单。
开通视频智能处理 Aideo Agent：前往视频点播控制台开通视频智能处理 Aideo Agent 并完成相关授权。

实现流程

以下步骤将指导您以最少的配置，快速生成一个解说视频。我们将使用您自己提供的解说词和系统默认的预置音色。

步骤 1：提交解说视频生成任务

方式 1：分离式调用（先剧本还原，后解说生成）

此模式分为“剧本还原”与“解说生成”两步。您可以先调用 CreateDramaScriptTask 接口对原始视频进行剧本还原，获得 DramaScriptTaskId。后续，通过这个 DramaScriptTaskId 多次调用 CreateDramaRecapTask 接口，使用不同的解说文案或音色生成多个版本的解说视频。

提交剧本还原任务：调用 CreateDramaScriptTask 接口，对您的原始视频发起一次剧情理解分析。调用成功后，您会获得一个剧本还原任务 ID，即 DramaScriptTaskId。轮询 QueryDramaScriptTask 接口，直至该任务状态变为 success，再进行下一步。

调用 HTTP/HTTPS 接口

集成视频点播服务端 SDK

您可以通过直接调用 HTTP/HTTPS 接口来提交任务。API 请求示例：

POST https://vod.volcengineapi.com?Action=CreateDramaScriptTask&Version=2025-03-03

{
  "SpaceName": "your_space_name",
  "Vids": [
    "vid_episode_01",
    "vid_episode_02"
  ]
}

也可集成视频点播服务端 Java SDK 调用，它封装了签名和请求细节，调用更便捷。示例代码：

package com.volcengine.example.vod.drama;

import com.volcengine.service.vod.IVodService;
import com.volcengine.service.vod.impl.VodServiceImpl;
public class VodCreateDramaScriptTaskDemo {

    public static void main(String[] args) throws Exception {
        // Create a VOD instance in the specified region.
        // IVodService vodService = VodServiceImpl.getInstance("cn-north-1");
        IVodService vodService = VodServiceImpl.getInstance();

        // Configure your Access Key ID (AK) and Secret Access Key (SK) in the environment variables or in the local ~/.volc/config file. For detailed instructions, see https://www.volcengine.com/docs/4/65641.
        // The SDK will automatically fetch the AK and SK from the environment variables or the ~/.volc/config file as needed.
        // During testing, you may use the following code snippet. However, do not store the AK and SK directly in your project code to prevent potential leakage and safeguard the security of all resources associated with your account.
        // vodService.setAccessKey("your ak");
        // vodService.setSecretKey("your sk");

        try {
            com.volcengine.service.vod.model.request.VodCreateDramaScriptTaskRequest.Builder reqBuilder = com.volcengine.service.vod.model.request.VodCreateDramaScriptTaskRequest.newBuilder();
                        reqBuilder.setSpaceName("your SpaceName");
                        reqBuilder.addVids("your Vids");
                        
            com.volcengine.service.vod.model.response.VodCreateDramaScriptTaskResponse resp = vodService.createDramaScriptTask(reqBuilder.build());
            if (resp.getResponseMetadata().hasError()) {
                System.out.println(resp.getResponseMetadata().getError());
                System.exit(-1);
            }
            System.out.println(resp);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

提交解说视频生成任务：确认剧本还原任务成功后，调用 CreateDramaRecapTask 接口发起解说视频生成。此时，您需要传入上一步获得的 DramaScriptTaskId，以及用于视频生成的解说文案、音色等配置。调用成功后，您可获得一个解说视频生成任务的 TaskId。

调用 HTTP/HTTPS 接口

集成视频点播服务端 SDK

直接调用 HTTP/HTTPS 接口来提交任务。API 请求示例：

POST https://vod.volcengineapi.com?Action=CreateDramaRecapTask&Version=2025-03-03

{
  "SpaceName": "your_space_name",
  "DramaScriptTaskId": "v02bbbg1006***kbdminbj659kvikr10",
  "RecapText": "今天我们来看一个关于错过的故事..."
}

集成视频点播服务端 Java SDK 调用。示例代码：

package com.volcengine.example.vod.drama;

import com.volcengine.service.vod.IVodService;
import com.volcengine.service.vod.impl.VodServiceImpl;
public class VodCreateDramaRecapTaskDemo {

    public static void main(String[] args) throws Exception {
        // Create a VOD instance in the specified region.
        // IVodService vodService = VodServiceImpl.getInstance("cn-north-1");
        IVodService vodService = VodServiceImpl.getInstance();

        // Configure your Access Key ID (AK) and Secret Access Key (SK) in the environment variables or in the local ~/.volc/config file. For detailed instructions, see https://www.volcengine.com/docs/4/65641.
        // The SDK will automatically fetch the AK and SK from the environment variables or the ~/.volc/config file as needed.
        // During testing, you may use the following code snippet. However, do not store the AK and SK directly in your project code to prevent potential leakage and safeguard the security of all resources associated with your account.
        // vodService.setAccessKey("your ak");
        // vodService.setSecretKey("your sk");

        try {
            com.volcengine.service.vod.model.request.VodCreateDramaRecapTaskRequest.Builder reqBuilder = com.volcengine.service.vod.model.request.VodCreateDramaRecapTaskRequest.newBuilder();
                        reqBuilder.setSpaceName("your SpaceName");
                        reqBuilder.setDramaScriptTaskId("your DramaScriptTaskId");
                        reqBuilder.setRecapText("your RecapText");
                        com.volcengine.service.vod.model.business.VodCreateDramaRecapTaskSpeakerConfig.Builder speakerConfigBuilder = com.volcengine.service.vod.model.business.VodCreateDramaRecapTaskSpeakerConfig.newBuilder();
                        reqBuilder.setSpeakerConfig(speakerConfigBuilder);
                        reqBuilder.setIsEraseSubtitle(false);
                        com.volcengine.service.vod.model.business.VodCreateDramaRecapTaskFontconfig.Builder fontConfigBuilder = com.volcengine.service.vod.model.business.VodCreateDramaRecapTaskFontconfig.newBuilder();
                        reqBuilder.setFontConfig(fontConfigBuilder);
                        
            com.volcengine.service.vod.model.response.VodCreateDramaRecapTaskResponse resp = vodService.createDramaRecapTask(reqBuilder.build());
            if (resp.getResponseMetadata().hasError()) {
                System.out.println(resp.getResponseMetadata().getError());
                System.exit(-1);
            }
            System.out.println(resp);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

方式 2：一体化调用（一步完成分析与生成）

此模式将两个步骤合二为一，调用更简单。适用于仅需单次生成解说视频、不考虑复用剧本还原结果的便捷场景。您可直接调用 CreateDramaRecapTask 接口，并在请求中直接传入原始短剧视频的 Vids 列表。系统将在后台隐式地先执行剧本还原，再进行解说合成。请求示例：

POST https://vod.volcengineapi.com?Action=CreateDramaRecapTask&Version=2025-03-03

{
  "SpaceName": "your_space_name",
  "Vids": [
    "vid_episode_01",
    "vid_episode_02"
  ],
  "RecapText": "今天我们来看一个关于错过的故事..."
}

调用成功后，您也会获得一个解说视频生成任务的 TaskId。

步骤 2：获取生成的解说视频

无论您选择哪种方式提交任务，可通过以下方式获取处理结果：

轮询 QueryDramaRecapTask 接口主动获取结果。

调用 HTTP/HTTPS 接口

集成视频点播服务端 Java SDK

直接调用 HTTP/HTTPS 接口来提交任务。API 请求示例：

GET https://vod.volcengineapi.com?Action=QueryDramaRecapTask&Version=2025-03-03&SpaceName=test&TaskId=v02bbbg1006***kbdminbj659kvikr10

集成视频点播服务端 Java SDK 调用。示例代码：

package com.volcengine.example.vod.drama;

import com.volcengine.service.vod.IVodService;
import com.volcengine.service.vod.impl.VodServiceImpl;
public class VodQueryDramaRecapTaskDemo {

    public static void main(String[] args) throws Exception {
        // Create a VOD instance in the specified region.
        // IVodService vodService = VodServiceImpl.getInstance("cn-north-1");
        IVodService vodService = VodServiceImpl.getInstance();

        // Configure your Access Key ID (AK) and Secret Access Key (SK) in the environment variables or in the local ~/.volc/config file. For detailed instructions, see https://www.volcengine.com/docs/4/65641.
        // The SDK will automatically fetch the AK and SK from the environment variables or the ~/.volc/config file as needed.
        // During testing, you may use the following code snippet. However, do not store the AK and SK directly in your project code to prevent potential leakage and safeguard the security of all resources associated with your account.
        // vodService.setAccessKey("your ak");
        // vodService.setSecretKey("your sk");

        try {
            com.volcengine.service.vod.model.request.VodQueryDramaRecapTaskRequest.Builder reqBuilder = com.volcengine.service.vod.model.request.VodQueryDramaRecapTaskRequest.newBuilder();
                        reqBuilder.setSpaceName("your SpaceName");
                        reqBuilder.setTaskId("your TaskId");
                        
            com.volcengine.service.vod.model.response.VodQueryDramaRecapTaskResponse resp = vodService.queryDramaRecapTask(reqBuilder.build());
            if (resp.getResponseMetadata().hasError()) {
                System.out.println(resp.getResponseMetadata().getError());
                System.exit(-1);
            }
            System.out.println(resp);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

配置事件通知：
1. 参考事件通知概述文档，配置一个用于接收回调的服务地址。在订阅事件时，勾选解说视频生成完成事件。
2. 当任务完成时，您的服务将收到一个 EventType 为 DramaRecapComplete 的 HTTP POST 请求。

当返回结果中的 Status 字段值为 success 时，表示任务已成功完成。您将在 Result 中获得最终生成的解说视频 Vid。至此，您已成功生成短剧解说视频，可以利用获取到的 Vid 进行后续的分发和播放。

步骤 3：获取解说视频 URL

在步骤 2 中获取到解说视频的 Vid 后，调用 GetPlayInfo 接口来获取该视频的播放地址。成功调用后，您将从返回结果的 PlayInfoList 中获取到播放 URL，可直接用于播放器或分发。

说明

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

进阶使用

自定义配音音色

默认情况下，如果您不传入 SpeakerConfig，系统将使用系统预置的 Yunxi 音色进行配音。通过配置 SpeakerConfig 参数，您可以选择不同的音色来源。

示例 1：使用其他视频点播预置音色

只需在 VoiceType 中指定音色名称即可。

POST https://vod.volcengineapi.com?Action=CreateDramaRecapTask&Version=2025-03-03
{
  "SpaceName": "your_space_name",
  "Vids": [
    "vid_episode_01",
    "vid_episode_02"
  ],
  "RecapText": "今天我们来看一个关于错过的故事...",
  "SpeakerConfig": {
    "VoiceType": "Yunjian"
  }
  // ... 其他配置已省略
}

预置音色列表：

Yunxi（默认）
Yunjian
Yunfeng
Yunjie
Yunze
Yunye
Xiaohan
Xiaomo

示例 2：使用豆包语音的音色

若需使用更丰富的音色库或您自己的克隆声音，在调用 API 前，您必须完成豆包语音服务的开通与配置，并获取相应的认证与音色信息。具体操作如下：

创建应用并获取 APP ID：请前往豆包语音控制台，创建一个应用，并为该应用开通音频生成大模型。完成后，您将获得 APP ID，这是调用 CreateDramaRecapTask 的必填参数。详细操作步骤，请见豆包语音快速入门。

选择音色模型并获取声音 ID：豆包语音提供两种音频生成大模型，您可以根据业务需求选择其一，并获取对应的 ID：

模型名称	描述	如何获取 ID
语音合成大模型	使用豆包语音提供的多种高质量、多风格的官方预置音色。	您需要获取音色的 VoiceType 字段。请参考官方音色列表进行选择。
声音复刻大模型	使用您自己上传样本并训练生成的专属克隆声音，实现品牌或角色的个性化配音。	您需要获取复刻声音的 speakerid 字段。具体请参考声音复刻文档。

在提交任务时，传入在豆包语音控制台获取的 AppId 和对应的音色 ID。

POST https://vod.volcengineapi.com?Action=CreateDramaRecapTask&Version=2025-03-03
{
  "SpaceName": "your_space_name",
  "Vids": [
    "vid_episode_01",
    "vid_episode_02"
  ],
  "RecapText": "今天我们来看一个关于错过的故事...",
  "SpeakerConfig": {
    "AppId": "YOUR_TTS_APP_ID",
    "VoiceType": "zh_male_magnetic_bigtts" // 此处为豆包语音的音色 ID
  }
  // ... 其他配置已省略
}

AI 自动生成解说词

默认情况下，您必须在 RecapText 字段中提供完整的解说词文本。通过配置 DramaRecapConfig 参数，您可以让 AI 根据视频内容自动创作解说词。

示例：让 AI 生成“悬疑”风格的解说词

设置 AutoGenerateRecapText 为 true，并通过 RecapStyle 给出风格指令。

POST https://vod.volcengineapi.com?Action=CreateDramaRecapTask&Version=2025-03-03
{
  "SpaceName": "your_space_name",
  "Vids": [
    "vid_episode_01",
    "vid_episode_02"
  ],
  "RecapText": "", // 留空，因为将由 AI 自动生成
  "DramaRecapConfig": {
    "AutoGenerateRecapText": true,
    "RecapStyle": "悬疑、反转风格，语言要紧凑，多设包袱",
    "RecapTextSpeed": 1.2,
    "RecapTextLength": 800
  }
  // ... 其他配置（如 SpeakerConfig, FontConfig）已省略
}

自定义硬字幕字体样式

默认情况下，系统会使用“方正雅宋”字体，并根据视频尺寸自动计算字体大小、位置，生成白色字幕。通过配置 FontConfig 参数，您可以修改字幕的视觉样式。

示例：修改字体、大小、颜色和位置

POST https://vod.volcengineapi.com?Action=CreateDramaRecapTask&Version=2025-03-03
{
  "SpaceName": "your_space_name",
  "Vids": [
    "vid_episode_01",
    "vid_episode_02"
  ],
  "RecapText": "今天我们来看一个关于错过的故事...",
  "FontConfig": {
    "FontType": "1525741", // 替换为您想用的字体 ID
    "FontSize": 80,
    "FontColor": "#FFFF00FF", // 设置为不透明的黄色
    "PosX": 100, // 字幕区域左边距
    "PosY": 1700 // 字幕区域上边距
  }
  // ... 其他配置（如 SpeakerConfig）已省略
}

一个任务批量生成多个解说视频

默认情况下，每次调用 CreateDramaRecapTask 接口，系统仅会生成一个解说视频。通过设置 BatchGenerateCount 参数，您可以指示系统基于同一份输入和配置，一次性地生成多个版本的解说视频。

示例：一次性生成 3 个不同版本的解说视频

以下示例将基于相同的视频和 AI 生成指令，一次性创建 3 个解说视频。AI 在每次生成时都会有细微的创作差异，从而产生三个略有不同的版本。

POST https://vod.volcengineapi.com?Action=CreateDramaRecapTask&Version=2025-03-03
{
  "SpaceName": "your_space_name",
  "Vids": [
    "vid_episode_01",
    "vid_episode_02"
  ],
  "DramaRecapConfig": {
    "AutoGenerateRecapText": true,
    "RecapStyle": "悬疑、反转风格"
  },
  "BatchGenerateCount": 3
  // ... 其他配置（如 SpeakerConfig, FontConfig）已省略
}

当您调用 QueryDramaRecapTask 接口查询任务结果时，Result 字段中将包含一个 RecapList 数组，其中列出了所有已生成的解说视频及其各自的 Vid。