POST https://mediakit.cn-beijing.volces.com/api/v1/tools/drama-script

本 API 用于提交一个异步的剧本还原任务，基于大模型视频理解能力，将短剧视频转化为结构化的剧本文本，精准识别并提取场景、人物、对话、情节等核心元素。

请求参数

Header 参数

参数	类型	是否必选	示例值	描述
Authorization	String	是	Bearer {Your_API_Key}	格式为 Bearer {Your_API_Key}。请参考基础概念及准备工作获取 API Key。

Body 参数

参数	类型	是否必选	示例值	描述
video_urls	Array	是	["https://...", "https://..."]	待处理的短剧视频 URL 列表。系统将按数组顺序拼接并进行分析。视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, flv, ts, avi, mov, wmv, mkv 等主流视频格式。暂不支持 HLS（M3U8）格式的视频源。数量限制：单次任务支持传入 1 到 100 个视频文件。视频时长限制：单次任务处理的所有视频累计时长不超过 300 分钟，单个文件时长不超过 120 分钟。内容类型：适用于真人实拍的短剧、长剧、电影等以人物对话和情节发展为核心的视频内容，不适用于动画、纪录片、广告、直播录屏等缺乏连贯真人剧情或人脸识别线索的视频。分辨率限制：提交的多个视频，其分辨率（宽高）必须保持一致。字幕要求：视频必须包含内嵌字幕（硬字幕）。
return_pkg	Boolean	否	false	控制任务结果的输出封装格式。 false：（默认）仅返回核心的剧本数据。任务结果的 result_url 字段将指向一个经过 Gzip 压缩的 JSON 文件 (.json.gz)。 true：将所有任务产物打包成一个压缩包 (.tar.gz) 返回，不仅包含核心的剧本 JSON，还提供了人物名及其图片、场景截图等分析结果。任务结果的 result_url 将指向此压缩包。
voice_language	String	否	en-US	指定视频中的语音语言，用于语音识别 ASR。默认行为：如不填写或为空，工具将自动检测语言。支持自动检测的语种为：中文、英文、上海话、闽南话、四川话、陕西话、粤语。支持的语种包括： zh-CN：简体中文 en-US：英语（美国） ja-JP：日语 id-ID：印度尼西亚语 es-MX：西班牙语（墨西哥） pt-BR：葡萄牙语（巴西） de-DE：德语 fr-FR：法语 ko-KR：韩语 fil-PH：菲律宾语 ms-MY：马来语 th-TH：泰语 ar-SA：阿拉伯语 it-IT：意大利语 bn-BD：孟加拉语 el-GR：希腊语 nl-NL：荷兰语 ru-RU：俄语 tr-TR：土耳其语 vi-VN：越南语 pl-PL：波兰语 ro-RO：罗马尼亚语 ne-NP：尼泊尔语 uk-UA：乌克兰语 yue-CN：粤语其中中文（zh-CN）与英文（en-US）为明确支持语种，其余语种可用但不保证识别效果。
output_language	String	否	en-US	设置输出剧本的语言。如不填写或留空，默认为 zh-CN。支持的语言： zh-CN：简体中文 en-US：英语（美国）
client_token	String	否	your_unique_request_id_135	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考幂等性控制。
callback_args	String	否	your_custom_callback_data	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。
callback_url	String	否	https://example.com/callback	用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

请求示例

以下示例演示了如何对两集短剧视频提交剧本还原任务。

响应说明

调用 API 提交任务后，接口会立即返回一个同步响应，表明任务是否成功进入后台处理队列。

响应参数

参数	类型	描述
success	Boolean	任务是否成功提交。 true：任务已成功提交到后台处理队列。 false：请求存在错误，任务提交失败。请检查 error 字段以获取详细信息。
task_id	String	任务的唯一标识符。仅在 success 为 true 时返回有效值。您可以使用此 ID 来查询任务状态和结果。
request_id	String	本次 API 请求的唯一标识符，可用于问题排查。
error	Object	错误详情对象，仅在 success 为 false 时返回。详见下文 Error 对象。

Error 对象

参数	类型	描述
code	String	具体的错误码。关于各错误码的详细信息，请参阅错误码。
type	String	错误的宏观类型。例如 BadRequest。
message	String	对错误的详细描述，可用于开发调试。
param	String	（可选）指出导致错误的具体参数。

响应示例

成功响应

失败响应

异步任务结果

剧本还原是一个异步任务，任务的执行状态和最终结果不会在提交时同步返回。您可以通过以下两种方式获取任务结果：

方法一（轮询查询）：使用提交任务时获取的 task_id，定期调用查询任务信息 API，直到 status 字段变为 completed 或 failed。

方法二（事件回调）：在 AI MediaKit 控制台预先配置一个接收回调的 URL，或在提交任务时通过 callback_url 参数为单次任务指定回调地址。任务完成后，系统会将包含最终结果的详细信息 POST 到您指定的地址。详情请参阅事件回调。

当任务成功完成后，您获取到的任务信息中的 result 字段将包含以下内容。

参数	类型	示例	描述
result_url	String	https://example.volcvideo.com/result.json.gz?auth_key=...	最终生成的剧本文件下载地址。该地址为公网 URL，有效期为 24 小时，请务必及时保存。
duration	Number	245.5	输入视频的总时长，单位为秒。
drama_script_task_id	String	v02bbbg1006***kbdminbj659kvikr0	剧本还原任务 ID。

以下是一个任务执行完成后的完整任务信息示例：

AI MediaKit