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

本 API 用于提交一个异步的解说视频生成（短剧行业模型）任务，基于对输入短剧剧集的角色和剧情故事线理解（剧本还原），自动提取高光片段，并按您的要求生成全新的解说视频。支持以下两种核心模式：

文字解说视频：原片高光混剪 + 屏幕文字解说。

旁白解说视频：原片高光混剪 + AI 语音解说 + BGM。

此外，您还可以通过参数配置成片剪辑效果，例如套用短剧三要素（剧名、角标、提示语）的视觉模板。

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	示例值	描述
video_urls	Array	是	["https://example.com/video1.mp4", "https://example.com/video2.mp4"]	待处理的短剧原片视频源 URL 列表。视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, flv, ts, avi, mov, wmv, mkv 等主流视频格式。数量限制：单次任务支持传入 1 到 30 个视频文件。时长限制：单次任务处理的所有视频累计时长不得超过 120 分钟（2 小时）。输入分辨率限制：当前仅支持 1080p。输入素材需保持分辨率一致，否则会有兼容性问题。输入内容要求：视频必须同时包含视频流和音频流音频流要求：音频轨道中必须包含清晰可识别的中文对话文本，仅含 BGM/纯音乐/语气词的片段无法准确还原剧情。画面字幕：建议视频画面下半部分包含清晰居中的中文字幕，可显著提升文字解说定位与剧情理解准确度。
mode	String	否	narrate	解说视频生成模式，默认为 text。 narrate：旁白解说模式。 text：文字解说模式。
narrate_bgm_url	String	否	https://example.com/audio.mp3	旁白解说模式下使用的背景音乐音频 URL。如不传，则生成的解说视频不添加背景音乐。生效条件：仅当 mode 为 narrate 且 narrate_options.enable_narrate_bgm 为 true 时生效。音频来源：仅支持公网可访问的 HTTP/HTTPS URL。支持格式：mp3, m4a, wav 等主流音频格式。
max_count	Integer	否	2	单次任务期望生成的解说视频数量上限。默认为 3，取值范围为 [1, 100]。建议结合输入的片源时长和目标输出视频的时长范围合理设置生产解说视频个数上限。
min_duration	Number	否	50	每个解说视频的时长下限，单位为秒。默认为 30，取值范围为 [1, 7200]。
max_duration	Number	否	150	每个解说视频的时长上限，单位为秒。默认为 180，取值范围为 [1, 7200]。
opening_hook	String	否	force	精彩片段前置策略，默认为 auto。 auto：智能判断是否将最精彩的片段前置到视频开头。 force：强制开启精彩前置。 disable：关闭精彩前置。
enable_return_poster	Boolean	否	true	是否在任务结果中返回解说视频的封面图 URL。默认为 false。 true：在任务结果中返回解说视频的封面图 URL（ poster_url）。 false：不返回封面图。
narrate_options	Object	否	-	旁白解说模式的参数配置，仅当 mode 为 narrate 时生效。详见下文 Narrate options 对象。
text_options	Object	否	-	文字解说模式的文字样式配置，仅当 mode 为 text 时生效。详见下文 Text options 对象。
edit_param	Object	否	-	成片剪辑参数配置，narrate 和 text 模式均可使用。详见下文 Edit param 对象。
media_output_destination	String	否	vod://my-space	指定处理产物的目标存储位置。AI MediaKit 支持将处理产物存储至您的火山引擎视频点播（VOD）空间或对象存储（TOS）桶。存储至 VOD：设为 vod://<您的空间名> 存储至 TOS：设为 tos://<您的桶名> 设置本参数后，任务结果中的 url 相关字段将返回形如 vod:// 或 tos:// 格式的资源地址，不再返回临时下载地址。说明首次使用此功能前，您需要先前往 AI MediaKit 控制台基础配置 > 授权管理页面，授权 AI MediaKit 将文件写入您的 VOD 空间或 TOS 桶。更多信息，请参阅开发指南处理产物存储至 VOD 或 TOS。
client_token	String	否	your_unique_request_id_131	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考幂等性控制。
callback_args	String	否	your_unique_callback_args	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。
callback_url	String	否	https://example.com/callback	用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

Narrate options 对象

旁白解说模式的参数配置，仅当 mode 为 narrate 时生效。

参数	类型	是否必选	描述
narrate_ratio	Number	否	解说浓度，用于控制旁白解说时长占生成视频的时长的比例。默认为 0.3，取值范围为 [0, 1]，值越大解说越密集，建议不要超过 0.5。
enable_narrate_bgm	Boolean	否	是否在旁白解说视频中添加背景音乐，默认为 true。 true：启用 BGM，使用 narrate_bgm_url 指定的音频。 false：关闭背景音乐。
erase_subtitle_mode	String	否	原片字幕擦除模式，默认为 mosaic。 mosaic：字幕打码。直接对字幕区域进行高斯模糊遮盖，处理效率最高，适合对画面完整性要求不高、仅需快速遮挡文字信息的场景。 standard：标准版字幕擦除。平衡擦除效果与处理效率，对纯色或简单背景擦除效果良好；但在复杂纹理或剧烈运动的背景下，可能会残留轻微的涂抹痕迹。

Text options 对象

文字解说模式的文字样式配置，仅当 mode 为 text 时生效。

参数	类型	是否必选	描述
font_type	String	否	文字字体类型。可选值： SY_Bold：（默认值）思源粗体 SY_Black：思源黑体
font_size	Integer	否	文字字号，单位 px。不传时将根据视频分辨率自动计算（短边 / 24，例如 720p 默认 30，1080p 默认 45）。不得小于 1。
font_color	String	否	文字颜色，格式为 #RRGGBBAA。默认值为 #FFFFF290。
align_type	String	否	文字对齐方式。可选值： left：左对齐（默认值） middle：居中对齐 right：右对齐
is_bold	Boolean	否	文字是否加粗。默认值为 false。 true：加粗 false：不加粗
is_italic	Boolean	否	文字是否斜体。默认值为 true。 true：斜体 false：不斜体
is_underline	Boolean	否	文字是否添加下划线。默认值为 false。 true：添加下划线 false：不添加下划线
shadow_color	String	否	文字阴影颜色，格式为 #RRGGBBAA。默认值为 #00000080。
border_width	Integer	否	文字描边宽度，单位 px，建议不超过字号的 0.1 倍。默认值为 2。
border_color	String	否	文字描边颜色，格式为 #RRGGBBAA。默认值为 #00000080。
inner_padding	Integer	否	文字内边距，单位 px。默认值为 1。

Edit param 对象

成片剪辑参数配置，适用于所有 mode。

参数	类型	是否必选	描述
mode	String	否	成片剪辑模式。默认为 BasicEdit。 BasicEdit：基础剪辑，仅对高光片段进行拼接。 TemplateEdit：模板剪辑，在基础剪辑上套用短剧三要素视觉模板。
template_edit	Object	否	短剧模板剪辑参数，当 edit_param.mode 为 TemplateEdit 时生效。详见下文 template_edit 结构。

Template edit 对象

参数	类型	是否必选	描述
template	String	否	“短剧三要素”视觉模板名称，决定了剧名、角标、提示语的位置和样式。支持的取值如下：热门短剧1（默认）热门短剧2 热门短剧3 热门短剧4 热门短剧5 具体效果，请见生成带“短剧三要素”的解说视频。
title	String	否	短剧名称。在解说视频画面上展示剧名，用于品牌识别和引导用户搜索。不得超过 22 个字。
hint	String	否	短剧提示语。画面左右两侧的一行文字，可以是概括视频核心冲突或亮点的引导性文字，也可以是类似“影视效果请勿模仿无不良价值观引导”的免责声明。不得超过 20 个字。

请求示例

以下示例演示了如何提交一个“旁白解说”视频生成任务。任务将使用两段原片，生成最多 5 条时长不超过 90 秒的解说视频，并强制开启精彩前置、添加自定义背景音乐。

响应说明

调用 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 字段将包含以下内容。

参数	类型	描述
input_duration	Number	输入视频的总时长，单位为秒。
output_duration	Number	输出的所有解说视频的总时长，单位为秒。
mode	String	解说视频生成模式： narrate：旁白解说模式。 text：文字解说模式。
video_urls	Array	所有生成的解说视频的地址列表。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
video_infos	Array	每个解说视频的详细信息列表，与 video_urls 顺序一致。详见下文Video info 对象。

Video info 对象

参数	类型	描述
duration	Number	该条解说视频的时长，单位为秒。
size	Integer	该条解说视频的文件大小，单位为字节。
poster_url	String	该条解说视频对应的封面图 URL。如果未生成或请求时 enable_return_poster 为 false，则此字段为空字符串。
video_url	String	该条解说视频的地址。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。

最终的完整任务信息示例：

AI MediaKit