视频点播 AI 剧本还原功能是指基于大模型视频理解，将短剧视频转化为结构化剧本文本。本功能可以精准识别并提取视频中的场景、人物（角色）、对话、情节等核心元素，为内容创作者和数据分析师提供高价值的文本素材。本文指导您通过调用视频点播 OpenAPI，实现短剧剧本还原功能，将视觉化的短剧视频转化为结构化的剧本文本。

功能介绍

通过 AI 剧本还原功能，您可以获得一份包含以下维度的结构化 JSON 数据：

剧情概述：对短剧的整体情节进行精炼总结。

场景分镜：智能切分视频为多个逻辑场景，并提供每个场景的标题、时间范围和剧情描述。

人物信息：识别剧中角色，并提供其姓名、性别、年龄段及人物关系描述。

对话提取：逐句提取所有对白，并附带说话人、精确时间戳及情绪标签。

元数据信息：记录所处理视频的基础信息，如 Vid、时长、分辨率等。

适用场景

辅助内容创作：为编剧和创作者提供现有短剧的剧本结构与对白参考，激发创意，加速内容生产。

提升内容审核与分析效率：将非结构化的视频内容转化为可检索、可分析的文本，便于进行关键词过滤、舆情监控和内容趋势分析。

构建内容索引库：批量处理短剧资源，建立精细化的内容标签与索引，实现高效的媒资管理与检索。

计费说明

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

使用限制

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

视频总时长：单次任务处理的所有视频累计时长不超过 300 分钟，单个文件时长不超过 120 分钟。

内容类型：适用于真人实拍的短剧、长剧、电影等以人物对话和情节发展为核心的视频内容，不适用于动画、纪录片、广告、直播录屏等缺乏连贯真人剧情或人脸识别线索的视频。

分辨率一致性：提交的多个视频，其分辨率（宽高）必须保持一致。

字幕要求：视频必须包含内嵌字幕（硬字幕）。

格式限制：暂不支持 HLS（M3U8）格式的视频源。

存储限制：暂不支持处理挂载在对象存储桶中的视频。

前提条件

已注册火山引擎账号。如果您是首次登录，请先完成实名认证。

已开通视频点播服务。

已创建空间。

开通视频智能处理 Aideo Agent：前往视频点播控制台开通视频智能处理 Aideo Agent 并完成相关授权。

上传视频：通过控制台、客户端上传 SDK、视频点播服务端 SDK 等方式将待处理的短剧视频上传至视频点播服务，并获取到视频的 Vid。具体介绍和操作步骤请见媒资上传概述。

实现流程

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

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

SpaceName：您的点播空间名称。

Vids：包含一个或多个视频 Vid 的数组，系统将按数组顺序对这些视频进行拼接分析。

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

调用 HTTP/HTTPS 接口

集成视频点播服务端 SDK

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

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

步骤 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

配置事件通知：

参考事件通知概述文档，配置一个用于接收回调的服务地址。在订阅事件时，勾选剧本还原任务完成事件。

当任务完成时，您的服务将收到一个 EventType 为 DramaScriptComplete 的 HTTP POST 请求。

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

步骤 3：下载并解析结果

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

剧本 JSON 文件结构示例：

剧本 JSON 文件结构说明：

字段路径	数据类型	示例值	说明
Plot	String	"视频以时月的旁白开场..."	对所有输入视频内容的整体剧情概述。
Scenes	Array	[...]	场景分镜列表。智能将视频切分为数个具有逻辑连贯性的核心场景。
Scenes[].Id	Integer	0	场景序号，从 0 开始递增。
Scenes[].Title	String	"大学相恋与提出分手"	该分镜场景的概括性标题。
Scenes[].Start	Integer	0	该场景包含的第一个切片（Segment）在 Segments 列表中的索引。
Scenes[].End	Integer	2	该场景包含的最后一个切片（Segment）在 Segments 列表中的索引。
Scenes[].Desc	String	"开场是大学时期的室内..."	该场景的视觉环境描述。
Scenes[].Plot	String	"时月以旁白的形式回忆..."	该场景发生的具体剧情发展及行为总结。
Scenes[].StartTime	Integer	0	该场景在全局时间线上的开始绝对时间，单位：毫秒。
Scenes[].EndTime	Integer	24200	该场景在全局时间线上的结束绝对时间，单位：毫秒。
Scenes[].Segments	Array	[...]	构成该核心场景的更细粒度视频切片（分片）信息列表。
Scenes[].Segments[].Id	Integer	0	切片在该场景内的序号，从 0 开始。
Scenes[].Segments[].StartInVideo	Integer	0	切片在其所属原始视频中的开始时间，单位：毫秒。
Scenes[].Segments[].EndInVideo	Integer	3666	切片在其所属原始视频中的结束时间，单位：毫秒。
Scenes[].Segments[].Start	Integer	0	切片在全局时间轴的开始时间，单位：毫秒。
Scenes[].Segments[].End	Integer	3666	切片在全局时间轴的结束时间，单位：毫秒。
Scenes[].Segments[].AudioDesc	String	"背景伴随轻柔舒缓..."	该切片的环境音效描述。
Scenes[].Segments[].Camera	Object		该切片的运镜参数，包含角度、景别、运镜方式等。
.Scenes[].Segments[].Camera.Angle	String	"平视"	拍摄角度。
.Scenes[].Segments[].Camera.Height	String	"平角度"	拍摄高度。
.Scenes[].Segments[].Camera.Direction	String	"斜侧"	拍摄方向。
.Scenes[].Segments[].Camera.LensFocalLength	String	"标准"	镜头焦距。
.Scenes[].Segments[].Camera.ShotSize	String	"中景"	景别。
.Scenes[].Segments[].Camera.Movement	String	"固定镜头"	运镜方式。
Scenes[].Segments[].Visual	Object		该切片的视觉风格参数，包含色调、光线、风格等。
Scenes[].Segments[].Visual.BackgroundBlur	String	"轻微虚化"	背景虚化程度。
Scenes[].Segments[].Visual.ColorTone	String	"写实"	色调风格。
Scenes[].Segments[].Visual.Style	String	"暖调"	视觉美学。
Scenes[].Segments[].Visual.Lighting	String	"柔光"	打光方式。
People	Array	[...]	出场人物角色信息列表。
People[].Id	String	"人物101"	出场人物的唯一标识符。
People[].Name	String	"时月"	出场人物的常用姓名或核心称谓。
People[].Looks	String	"大学时期：深色盘发..."	人物视觉特征描述。
Dialogues	Array	[...]	对白列表，逐句提取视频中的语音对白信息。
Dialogues[].Id	Integer	0	对白序号。
Dialogues[].Start	String	"00:00:00.440"	该句对白在全局时间轴的开始时间码，格式：HH:mm:ss.SSS。
Dialogues[].End	String	"00:00:02.840"	该句对白在全局时间轴的结束时间码，格式：HH:mm:ss.SSS。
Dialogues[].StartInMillis	Integer	440	该句对白在全局时间轴的开始时间，单位：毫秒。
Dialogues[].EndInMillis	Integer	2840	该句对白在全局时间轴的结束时间，单位：毫秒。
Dialogues[].StartInVideoMillis	Integer	440	该句对白在其所属原始视频中的开始时间，单位：毫秒。
Dialogues[].EndInVideoMillis	Integer	2840	该句对白在其所属原始视频中的结束时间，单位：毫秒。
Dialogues[].VoiceDesc	String	"青年女性近距离说话..."	对说话人声音特征（如音色、语气）的描述。
Dialogues[].PeopleId	String	"人物101"	说话人的唯一角色 ID，对应 People[].Id。
Videos	Array	[...]	输入源视频元数据列表。
Videos[].SpeechAudioFile	String	"..._audiospeech.mp3"	该视频分离出的人声音频文件名。
Videos[].BackgroundAudioFile	String	"..._background.mp3"	该视频分离出的背景音音频文件名。