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

本 API 用于提交一个异步的解说视频生成任务。您需要提供一个已完成的剧本还原任务 ID，并可自定义解说词或让 AI 自动生成解说词，然后一键生成带有 AI 配音和解说字幕的全新营销或解说视频。您可以对音色、字幕样式、原文字幕擦除等进行灵活配置。

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	示例值	描述
drama_script_task_id	String	是	v02bbbg1006***kbdminbj659kvikr0	已成功完成的剧本还原任务的 task_id。详见提交剧本还原任务 API。传入该字段后，系统会参考该任务 ID 对应的剧本还原结果进行解说视频生成。
recap_text	String	否	生成解说	用户自定义的解说词文本，最多 5000 字符。当 drama_recap_config.auto_generate_recap 为 false（默认）时，此项必填。
batch_count	Integer	否	5	批量生成的解说视频数量。允许您基于同一份输入，一次性生成多个版本的解说视频。默认为 1，最大为 100。
erase_subtitle	Boolean	否	true	是否擦除原视频中的字幕。 true：系统会在生成解说视频时移除原有字幕。 false：（默认）系统会在生成解说视频时保留原有字幕。
erase_mode	String	否	standard	字幕擦除模式，仅当 erase_subtitle 为 true 时生效。支持取值如下： standard：（默认）标准版字幕擦除。该模式平衡擦除效果和处理效率，会残留轻微的涂抹痕迹。
speaker_config	Object	否	-	AI 配音配置。详见下文 speaker_config 结构（AI 配音配置）。
drama_recap_config	Object	否	-	解说词配置，用于控制解说词的生成方式、风格、语速等核心创作参数。详见下文 drama_recap_config 结构（解说词配置）。
subtitle_config	Object	否	-	解说字幕配置，用于自定义新生成的解说字幕的字体、位置、颜色等。详见下文 subtitle_config 结构（解说字幕配置）。
miniseries_edit	Object	否	-	（仅竖屏）短剧三要素配置。使用预设的视觉模板，为解说视频一键添加“短剧三要素”（剧名、角标、提示语）。详见下文 miniseries_edit 结构（短剧三要素配置）。
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。详情请参考项目与队列管理。

speaker_config 结构（AI 配音配置）

参数	类型	是否必选	描述
voice_type	String	否	配音的音色名称。默认为 Yunxi。支持的预置音色包括： Yunxi Yunjian Yunfeng Yunyi Yunjie Yunze Yunye Xiaoxiao Xiaochen Xiaohan Xiaomo

drama_recap_config 结构（解说词配置）

参数	类型	是否必选	描述
auto_generate_recap	Boolean	否	是否由 AI 自动生成解说词： true：系统将根据视频内容自动创作解说文案。此时您不可传入 recap_text。 false：（默认）使用您提供的文案。此时 recap_text 字段为必填。
style	String	否	AI 生成解说词的风格指令，如“悬疑”、“搞笑”、“轻松”等。仅在 auto_generate_recap 为 true 时生效。
text_speed	Number	否	期望的解说词语速。取值范围为 [0.5, 2.0]，数值越大语速越快。默认值为 1.0（标准语速）。为达到更好的听感，推荐设置为 1.2 或 1.3。
text_length	Integer	否	AI 生成解说词的期望长度（UTF-8 字符数）。仅在 auto_generate_recap 为 true 时生效。最大值为 5000。请注意，为保证解说内容的自然流畅，算法最终输出的文本长度可能不会严格等于此值，但会尽量趋近。
pause_time	Integer	否	AI 配音的句间停顿时长，单位为毫秒。默认为 120。取值范围 [1, 1000]。通过调整此参数，您可以控制解说配音的节奏感。较大的值会使句子之间的停顿更明显，节奏更舒缓；较小的值则节奏更紧凑。
prefer_speed	Boolean	否	是否优先保障生成速度，默认值为 false。 true ：系统会使用更少的模型尝试次数，生成耗时更短。 false：生成结果整体更稳定，耗时较长。
enable_repeat_match	Boolean	否	是否允许解说词匹配重复的视频画面。 false：（默认）严格匹配模式，确保每个视频片段只被使用一次，成片重复度更低但耗时可能更长。 true：宽松匹配模式，允许视频片段被重复使用，可以提升生成速度和成功率，但可能导致成片出现少量重复画面。

subtitle_config 结构（解说字幕配置）

参数	类型	是否必选	描述
disable_subtitle	Boolean	否	是否不在生成的解说视频中添加新的解说字幕。默认为 false，即在生成的解说视频中添加新的解说字幕。
font_type	String	否	字幕字体。默认为 sy_black。支持取值如下： sy_black：思源黑体 ali_puhui：阿里巴巴普惠体 pm_zhengdao：庞门正道标题体
font_size	Integer	否	字幕字体大小，单位为 px。
font_color	String	否	字幕字体颜色，RGBA 格式，如 "#FFCC66FF"。默认为 "#FFFFFFFF"（白色）。
top_left_x	Integer	否	字幕矩形区域左上角的 X 坐标，单位为像素（px）。
top_left_y	Integer	否	字幕矩形区域左上角的 Y 坐标，单位为像素（px）。
bottom_right_x	Integer	否	字幕矩形区域右下角的 X 坐标，单位为像素（px）。需大于 top_left_x。
bottom_right_y	Integer	否	字幕矩形区域右下角的 Y 坐标，单位为像素（px）。需大于 top_left_y。
alpha	Number	否	字幕字体透明度。默认为 1。取值范围 [0, 1]。
align_type	Integer	否	文本对齐方式。默认为 1（居中）。横排： 0：左对齐 1：居中 2：右对齐竖排： 1：居中 3：上对齐 4：下对齐
border_color	String	否	字幕描边颜色，RGBA 格式。默认为 "#00000000"（透明）。
border_width	Integer	否	字幕描边宽度，单位为 px。
typesetting	Integer	否	文字排列方向。 0：横排（默认） 1：竖排
line_max_width	Number	否	自动换行宽度占字幕区域的比例。默认为 1。取值范围 [0, 1]。
background_color	String	否	字幕背景颜色，RGBA 格式。默认为 "#00000000"（透明）。
background_border_size	Number	否	字幕背景边框大小。默认为 0。

miniseries_edit 结构（短剧三要素配置）

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

请求示例

以下示例演示了如何提交一个解说视频生成任务：使用已有的剧本还原任务 ID，让 AI 自动生成“悬疑”风格的解说词，配音选择“Yunfeng”音色，擦除原视频字幕，并套用“热门短剧1”视觉模板。

响应说明

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

响应参数

参数	类型	描述
success	Boolean	任务是否提交成功。 true：任务已成功提交到后台处理队列。 false：请求存在错误，任务提交失败。请检查 error 字段以获取详细信息。
task_id	String	任务的唯一标识。仅在 success 为 true 时返回有效值，用于后续查询任务进度和结果。
request_id	String	本次请求的唯一标识，可用于问题排查。
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 字段将包含以下内容。

参数	类型	示例	描述
video_url	String	"https://..."	当 batch_count 为 1 （只生成一个解说视频）时，这里会提供解说视频的地址。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
video_urls	Array	["https://..."]	当您使用 batch_count 参数批量生成多个视频时，这里会以数组形式提供所有视频的地址。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
duration	Number	89.5	所有输出结束视频的总时长，单位为秒。
total_count	Integer	3	批量生成的总任务数。
success_count	Integer	3	成功生成的视频数量。
failed_count	Integer	0	生成失败的视频数量。
error	Object	null	如果任务失败，此字段将包含错误码和错误信息。

最终的完整任务信息示例（批量生成）：

AI MediaKit