文档中心

AI MediaKit

视频工具

剧本还原

AI MediaKit 剧本还原工具基于强大的视频理解能力，能够将真人实拍的短剧转化为结构化剧本文本。本工具可以精准识别并提取视频中的场景、人物（角色）、对话、情节等核心元素，为您提供一份格式清晰、内容完整的剧本文件，极大地提升了内容分析、二次创作和检索的效率。

本篇开发指南将引导您：

快速体验通过 API 调用，将剧集视频还原为结构化的剧本文本。

理解并使用剧本还原的异步任务流程。

了解剧本还原工具的适用场景与输入要求。

快速入门：实现剧本还原

准备工作

获取访问凭证：在开始之前，访问 AI MediaKit 控制台 API Key 管理页面，创建并获取 AI MediaKit API Key。

准备视频文件：准备一个或多个待分析的剧集视频文件，并将其上传至公网可访问的服务器或视频点播服务中，以获取可供 API 调用的 URL。为方便您快速测试，本文后续步骤的示例代码中提供了两个可直接使用的演示视频 URL。

操作流程

剧本还原是一个异步任务，完整的调用流程如下：

成功调用 POST /api/v1/tools/drama-script 提交任务后，API 将返回一个任务 ID。

您可以轮询 GET /api/v1/tasks/{task_id} 接口查询任务状态，直到状态 status 变为 completed；或者使用事件回调自动接收任务状态变化。

任务完成后，从响应的 result 字段中获取剧本文件下载地址 (result_url)，并下载最终的 JSON 文件。

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

您需要调用提交剧本还原任务 API。可直接复制以下 cURL 命令，提交一个剧本还原任务。本示例输入了两个剧集视频文件。

说明

需替换参数：

将 {Your_API_Key} 替换为您的有效 API Key。

video_urls：示例中已提供可直接用于测试的演示视频 URL。您也可以将其替换为您自己的视频地址。

请求成功后，您会收到如下包含 task_id 的响应，请保存此 ID 用于后续查询。

第 2 步：获取任务结果

剧本还原需要一定处理时间，您需要通过轮询查询任务信息 API 来获取最终结果，直到任务状态变为 completed。

说明

需替换参数：将 URL 末尾的 {task_id} 替换为第 1 步返回的任务 ID。

任务成功完成后，您将收到包含剧本文件下载地址的响应。result.result_url 即是最终生成的剧本文件下载链接。该 URL 有效期为 24 小时，请务必及时保存。

第 3 步：下载并使用剧本数据

访问第 2 步中获取的 result_url，即可下载一个 Gzip 压缩的 JSON 文件。根据您在提交任务时 return_pkg 参数的设置，产物格式会有所不同。

默认情况 (return_pkg=false)：获取核心剧本数据

默认情况下，您将下载一个 Gzip 压缩的 JSON 文件 (result.json.gz)。解压后，即可得到一份包含完整结构化剧本数据的 JSON 文件。

完整包情况 (return_pkg=true)：获取全部解析资产

如果您在提交任务时设置了 return_pkg: true，下载的将是一个包含所有分析产物的压缩包 (.tar.gz)。这对于深度二次开发非常有用。解压后的文件结构如下：

剧本 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"	该视频分离出的背景音音频文件名。

参考信息

使用限制

为确保最佳还原效果，请注意以下输入限制：

限制项	说明
内容类型	适用于真人实拍的短剧、长剧、电影等以人物对话和情节发展为核心的视频内容。不适用于动画、纪录片、广告、直播录屏等缺乏连贯真人剧情或人脸识别线索的视频。
字幕要求	视频必须包含清晰的内嵌字幕（硬字幕）。
分辨率	提交的多个视频，其分辨率（宽高）必须保持一致。
数量与时长	单次任务支持传入 1 到 100 个视频文件。单个文件时长不超过 120 分钟。所有视频累计总时长不超过 300 分钟。
视频格式	支持 mp4, mov, mkv 等主流视频格式，暂不支持 HLS (M3U8) 格式。