本文将指导您通过调用视频点播 OpenAPI，实现短剧剧本还原功能，将视觉化的短剧视频转化为结构化的剧本文本。

功能介绍

AI 剧本还原是指基于大模型视频理解，将短剧视频转化为结构化剧本文本。本功能可以精准识别并提取视频中的场景、人物（角色）、对话、情节等核心元素，为内容创作者和数据分析师提供高价值的文本素材。通过本功能，您可以获得一份包含以下维度的结构化 JSON 数据：

• 剧情概述：对短剧的整体情节进行精炼总结。
• 场景分镜：智能切分视频为多个逻辑场景，并提供每个场景的标题、时间范围和剧情描述。
• 人物信息：识别剧中角色，并提供其姓名、性别、年龄段及人物关系描述。
• 对话提取：逐句提取所有对白，并附带说话人、精确时间戳及情绪标签。
• 元数据信息：记录所处理视频的基础信息，如 Vid、时长、分辨率等。

适用场景

• 辅助内容创作：为编剧和创作者提供现有短剧的剧本结构与对白参考，激发创意，加速内容生产。
• 提升内容审核与分析效率：将非结构化的视频内容转化为可检索、可分析的文本，便于进行关键词过滤、舆情监控和内容趋势分析。
• 构建内容索引库：批量处理短剧资源，建立精细化的内容标签与索引，实现高效的媒资管理与检索。

计费说明

AI 剧本还原按输入视频时长计费，价格为 3 元/分钟。

使用限制

在开始前，请确保您的视频资源满足以下条件：

• 视频总时长：单次任务处理的所有视频累计时长不超过 90 分钟（约等于一部 45 集的短剧）。
• 内容类型：适用于真人实拍的短剧、长剧、电影等以人物对话和情节发展为核心的视频内容，不适用于动画、纪录片、广告、直播录屏等缺乏连贯真人剧情或人脸识别线索的视频。
• 分辨率一致性：提交的多个视频，其分辨率（宽高）必须保持一致。
• 字幕要求：视频必须包含内嵌字幕（硬字幕）。暂不支持无字幕或外挂字幕的视频。
• 格式限制：暂不支持 HLS（M3U8）格式的视频源。
• 存储限制：暂不支持处理挂载在对象存储桶中的视频。

前提条件

• 已注册火山引擎账号。如果您是首次登录，请先完成实名认证。
• 已开通视频点播服务。
• 已创建空间。
• 开通白名单：使用前请提交工单联系火山引擎技术支持团队申请添加 AI 剧本还原和视频智能处理 Aideo Agent 的白名单。
• 开通视频智能处理 Aideo Agent：前往视频点播控制台开通视频智能处理 Aideo Agent 并完成相关授权。
  
• 上传视频：通过控制台、客户端上传 SDK、视频点播服务端 SDK 等方式将待处理的短剧视频上传至视频点播服务，并获取到视频的 Vid。具体介绍和操作步骤请见媒资上传概述。

实现流程

步骤 1：提交剧本还原任务

调用 CreateDramaScriptTask 接口来创建一个异步的剧本还原任务。请求时，请关注以下参数：

• SpaceName：您的点播空间名称。
• Vids：包含一个或多个视频 Vid 的数组，系统将按数组顺序对这些视频进行拼接分析。

接口调用成功后，会返回一个任务 ID，用于后续查询结果。

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

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

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();
        }
    }
}

步骤 2：获取任务结果

剧本还原是一个异步过程，您可以通过以下方式获取任务结果：

• 在提交任务后，间隔一定时间调用 QueryDramaScriptTask 接口，并传入步骤 1 中获取的 TaskId。

  调用 HTTP/HTTPS 接口

  集成视频点播服务端 SDK

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

  GET https://vod.volcengineapi.com?Action=QueryDramaScriptTask&Version=2025-03-03&SpaceName=your_space_name&TaskId=drama_task_d290f1ee-6c54-4b01-90e6-d701748f0851
  

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

  package com.volcengine.example.vod.drama;
  
  import com.volcengine.service.vod.IVodService;
  import com.volcengine.service.vod.impl.VodServiceImpl;
  public class VodQueryDramaScriptTaskDemo {
  
      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.VodQueryDramaScriptTaskRequest.Builder reqBuilder = com.volcengine.service.vod.model.request.VodQueryDramaScriptTaskRequest.newBuilder();
                          reqBuilder.setSpaceName("your SpaceName");
                          reqBuilder.setTaskId("your TaskId");
                          
              com.volcengine.service.vod.model.response.VodQueryDramaScriptTaskResponse resp = vodService.queryDramaScriptTask(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 为 DramaScriptComplete 的 HTTP POST 请求。

当返回结果中的 Status 字段为 success 时，ResultUrl 字段会包含结果文件的下载地址。成功返回示例：

{
  "ResponseMetadata": {
    "RequestId": "20230604110530****100232280033A42",
    "Action": "QueryDramaScriptTask",
    "Version": "2025-03-03",
    "Service": "vod",
    "Region": "cn-north-1"
  },
  "Result": {
    "Status": "success",
    "ResultUrl": "https://example.volcvideo.com/video_analyze_results/20250926151119.v02cd3g10***3b341365iru9anoh6ug.json.gz"
  }
}

步骤 3：下载并解析结果

当任务状态为 success 后，您可以通过返回的 ResultUrl 下载一个 Gzip 压缩的 JSON 文件。下载并解压后，您将得到一份结构化的剧本数据。以下是其核心数据结构说明：

{
    "Plot": "对所提交视频的整体剧情总结。",
    "Scenes": [{
        "Title": "场景标题",
        "Start": 0, //开始分片序号
        "End": 10, //结束分片序号
        "StartTime": "场景在全局时间线上的开始时间（毫秒）",
        "EndTime": "场景在全局时间线上的结束时间（毫秒）",
        "Plot": "该场景的剧情描述。",
        "Segments": [{
            "Id": 1, //分片序号（按所有视频一起分配，从0开始）
            "Vid": "分片所属视频vid",
            "StartInVideo": "分片在视频中的开始时间",
            "EndInVideo": "分片在视频中的结束时间",
            "Start": "分片在所有视频中的开始时间",
            "End": "分片在所有视频中的结束时间",
            "Plot": "分片剧情"
        }] //构成该场景的更细粒度的分片信息
    }],
    "People": [{
        "Id": "出场人物ID",
        "Name": "出场人物姓名或称谓",
        "Desc": "出场人物描述，如性格、身份、人物关系等",
        "Gender": "出场人物性别：'男', '女', '未知'",
        "Age": "出场人物年龄段：'儿童', '少年', '青年', '中年', '老年', '未知'"
    }],
    "Dialogues": [{
        "Content": "对话文本内容",
        "Start": "对话在全局时间线上的开始时间 (格式: HH:mm:ss.SSS)",
        "End": "对话在全局时间线上的结束时间 (格式: HH:mm:ss.SSS)",
        "People": "说话人姓名",
        "PeopleId": "说话人ID",
        "Emotion": "对话所带的情绪标签，如'平静'、'激动'等。",
        "EmotionId": "情绪ID，参考：https://www.volcengine.com/docs/6561/1257544"
    }],
    "Videos": [{
        "Vid": "视频vid",
        "DurationInMillis": 1800, //视频总长度，毫秒
        "Width": 1280, //视频宽
        "Height": 720, //视频高
        "StoreUri":"tos-vod-cn-v-f345***42fbf5462/系统001.mp4" //存储路径
    }] //您提交的原始视频列表及其元数据
}