CreateDramaRecapTask - 创建解说视频生成任务--视频点播-火山引擎

文档中心

立即注册

视频点播

AI 解说生成

CreateDramaRecapTask - 创建解说视频生成任务

调用 CreateDramaRecapTask 接口创建短剧解说视频生成任务。

使用说明

通过调用此接口，您可以提交一个异步任务，基于一部完整的短剧智能地生成为带有 AI 配音和解说字幕的“二创”解说视频。

输入：您需要提供短剧的原始视频列表 (Vids)，以及一份解说词文本 (RecapText)。您也可以选择让 AI 自动生成解说词。
输出：任务完成后，系统将生成新的解说视频，并存储在您的点播空间中。

本接口为异步接口，调用成功后会返回一个任务 ID。您可通过以下方式获取处理结果：

调用 QueryDramaRecapTask 接口主动查询。
配置解说视频生成完成事件。

注意事项

开通白名单：该接口仅支持白名单用户调用。使用前请提交工单联系火山引擎技术支持团队申请开通。
QPS 限制：本接口的单用户 QPS 限制为 10 次/秒。超过限制，API 调用会被限流，这可能会影响您的业务，请合理调用。更多信息，请参见 QPS 限制。
输入短剧视频限制：
- 视频总时长：单次任务处理的所有视频累计时长不超过 90 分钟（约等于一部 45 集的短剧）。
- 分辨率一致性：提交的多个视频，其分辨率（宽高）必须保持一致。
- 字幕要求：视频必须包含内嵌字幕（硬字幕）。暂不支持无字幕或外挂字幕的视频。
- 格式限制：暂不支持 HLS（M3U8）格式的视频。
- 存储限制：暂不支持处理挂载在对象存储桶中的视频。

请求说明

请求方式：POST
请求地址：https://vod.volcengineapi.com?Action=CreateDramaRecapTask&Version=2025-03-03

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共请求参数。

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`CreateDramaRecapTask`	接口名称。当前 API 的名称为 `CreateDramaRecapTask`。
Version	String	是	`2025-03-03`	接口版本。当前 API 的版本为 `2025-03-03`。

Body

参数	类型	是否必选	示例值	描述
SpaceName	String	是	`test`	待处理文件所在点播空间的名称。您需要在调用本接口前创建空间，并在此处传入空间名称。
Vids	String[]	否	`["v02b69g10000***eldb8vjafvmg"]`	待处理的视频 ID 列表，支持传入多个视频 ID 进行批量处理。若传入该字段，系统会先进行剧本还原，再进行解说视频生成。说明 `DramaScriptTaskId` 与 `Vids` 参数互斥，只能填写其中一个。
DramaScriptTaskId	String	否	`v02bbbg1006***kbdminbj659kvikr10`	剧情分析任务 ID。若传入该字段，系统会参考该任务 ID 对应的剧本还原结果进行解说视频生成。说明 `DramaScriptTaskId` 与 `Vids` 参数互斥，只能填写其中一个。请确保 `DramaScriptTaskId` 对应的剧本还原任务状态为成功，否则本次请求会失败。
RecapText	String	否	`这是一部关于都市爱情的短剧，讲述了两位年轻人在繁华都市中相遇、相知、相爱的故事。剧情紧凑，情感真挚，展现了现代年轻人对爱情的追求与坚持。`	自定义的解说词文本。当您希望使用自己的文案进行配音时，请设置此字段。注意当 `DramaRecapConfig.AutoGenerateRecapText` 为 `false`（默认）时，此字段为必填。
IsEraseSubtitle	Boolean	否	`true`	是否擦除原视频中的字幕。 `true`：系统会在生成解说视频时移除原有字幕。 `false`：（默认）系统会在生成解说视频时保留原有字幕。
SpeakerConfig	Object	否	`-`	AI 配音的音色配置。
AppId	String	否	`1574***863`	豆包语音的 APP ID。若您希望使用豆包语音的高级音色或声音复刻能力，请传入此 ID。具体请见豆包语音快速入门。注意传入此字段后，`VoiceType` 必须设置为豆包语音对应的音色 ID。
Cluster	String	否	`volcano_tts`	固定值为 `volcano_tts`。
VoiceType	String	否	`zh_female_vv_uranus_bigtts`	音色名称或 ID。预置音色：即不传 `AppId`，支持以下取值： `Yunxi`（默认） `Yunjian` `Yunfeng` `Yunyi` `Yunjie` `Yunze` `Yunye` `Xiaoxiao` `Xiaochen` `Xiaohan` `Xiaomo` 使用豆包语音：即传入 `AppId`。必须设置为豆包语音对应的音色 ID。若您使用语音合成大模型，对应 `voice_type` 字段。详见音色列表。若您使用声音复刻大模型，对应 `speakerid` 字段。具体请参考声音复刻文档。
FontConfig	Object	否	`-`	字幕样式配置，用于自定义新生成的解说字幕的字体、位置、颜色等。
NoSubtitle	Boolean	否	`true`	是否在生成的解说视频中不添加硬字幕。 `true`：生成的解说视频中将不包含硬字幕。 `false`：（默认）根据解说词生成新的硬字幕。
PosX	Integer	否	`360`	字幕区域左上角 X 坐标（单位：pixel），即字幕区域左上角相对于输出视频左上角在 X 轴上的位移。默认自动居中显示，计算方式为 `(视频宽度 - 字幕区域宽度) / 2`。
PosY	Integer	否	`720`	字幕区域左上角 Y 坐标（单位：pixel），即字幕区域左上角相对于输出视频左上角在 Y 轴上的位移。默认值根据输入视频的高度和横竖屏状态动态计算，通常位于画面底部。竖屏视频：`视频高度 - (5.5 * FontSize)` 横屏视频：`视频高度 * 0.85`
Alpha	Double	否	`1`	字体透明度，取值范围 [0,1]。0 为透明。默认为 1。
Width	Integer	否	`1080`	字幕区域的宽度（单位：pixel）。默认值根据输入视频的宽度动态计算。竖屏视频：`视频宽度 * 0.9`。宽高相等的视频按竖屏处理。横屏视频：`视频宽度 * 0.75`
Height	Integer	否	`720`	字幕区域的高度（单位：pixel）。默认值根据最终的字体大小动态计算，通常为 `FontSize * 3`。
TextRes	String	否	`1179437`	花字 ID。默认为空字符串。
FontSize	Integer	否	`75`	字体大小（单位：pixel）。默认值根据输入视频的尺寸动态计算。竖屏视频：`min(视频宽, 视频高) * 0.065`。宽高相等的视频按竖屏处理。横屏视频：`min(视频宽, 视频高) * 0.06`
FontType	String	否	`1525741`	字体 ID。默认字体为方正雅宋。
AlignType	Integer	否	`1`	文本对齐方式。默认值为 1。需和 `Typesetting` 参数配合使用。当文字横排时，支持的取值如下所示。 `0`：左对齐； `1`：居中对齐； `2`：右对齐。当文字竖排时，支持的取值如下所示。 `1`：居中对齐； `3`：上对齐； `4`：下对齐。
FontColor	String	否	`#FFCC66FF`	字体颜色。RGBA 类型。如果没有使用花字，颜色默认为白色。说明只支持基础文字，不支持花字。
BorderColor	String	否	`#FF0000FF`	字幕的描边颜色，使用 RGBA 格式表示。默认值为 `#00000000`（透明）。说明只支持基础文字，不支持花字。
BorderWidth	Integer	否	`2`	字幕的描边宽度，单位为 pixel。最小值为 `1`，最大值不能超过 `FontSize` 的 `0.1` 倍。
Typesetting	Integer	否	`1`	文字排列方向： `0`: （默认）文字横排。 `1`: 文字竖排。
LineMaxWidth	Double	否	`1`	自动换行宽度。默认值为 1，和 `Width` 保持一致。可设为 0 到 1 之前的一个数字，表示自动换行宽度的占比。如果 `Typesetting` 参数取值为 `0` ，基准是 `Width` 大小。如果 `Typesetting` 参数取值为 `1` ，基准是 `Height` 大小。
BackgroundColor	String	否	`#00000080`	字幕的背景颜色，使用 RGBA 格式表示。默认值为 `#00000000`。说明仅覆盖文字，如果是多行文字，则以最长的一行为准。只支持基础文字，不支持花字。
BackgroundBorderSize	Double	否	`0`	字体背景边框大小。默认值为 `0`。背景颜色仅仅跟随文字。
BatchGenerateCount	Integer	否	`1`	批量生成的解说视频数量。允许您基于同一份输入，一次性生成多个版本的解说视频。默认值为 `1`，最大支持 `100`。
DramaRecapConfig	Object	否	`-`	解说视频生成配置。用于控制解说词的生成方式、风格、语速等核心创作参数。
AutoGenerateRecapText	Boolean	否	`true`	是否由 AI 自动生成解说词： `true`：系统将根据视频内容自动创作解说文案。此时您不能设置 `RecapText` 字段。 `false`：（默认）使用您提供的文案。此时 `RecapText` 字段为必填。
RecapStyle	String	否	`搞笑`	AI 生成解说词的风格指令。您可以输入一些关键词来引导 AI 的创作风格，例如“悬疑”、“轻松“等。内容不超过 500 个 UTF-8 字符。
RecapTextSpeed	Double	否	`1.2`	期望的解说词语速。取值范围为 `[0.5, 2.0]`，数值越大语速越快。默认值为 `1.0`（标准语速）。为达到更好的听感，推荐设置为 `1.2` 或 `1.3`。
RecapTextLength	Integer	否	`800`	期望 AI 生成的解说词长度（UTF-8 字符数），最大值为 `5000`。请注意，为保证解说内容的自然流畅，算法最终输出的文本长度可能不会严格等于此值，但会尽量趋近。
PauseTime	Integer	否	`1`	AI 配音时句间停顿的时长，单位为毫秒。默认值为 `120`，取值范围为 `[1, 1000]`。通过调整此参数，您可以控制解说配音的节奏感。较大的值会使句子之间的停顿更明显，节奏更舒缓；较小的值则节奏更紧凑。
AllowRepeatMatch	Boolean	否	`true`	是否允许解说词匹配重复的视频画面。 `false`：（默认）严格匹配模式，确保每个视频片段只被使用一次，成片重复度更低但耗时可能更长。 `true`：宽松匹配模式，允许视频片段被重复使用，可以提升生成速度和成功率，但可能导致成片出现少量重复画面。
MiniseriesEdit	Object	否	`-`	短剧剪辑配置。使用预设的视觉模板，为解说视频一键添加“短剧三要素”（剧名、角标、提示语）。注意 “短剧三要素”仅适用于竖屏短剧，暂不支持横屏剧。
Template	String	否	`热门短剧1`	“短剧三要素”视觉模板名称。不同的模板决定了剧名、角标、提示语的位置和样式。支持的取值如下： `热门短剧1` `热门短剧2` `热门短剧3` `热门短剧4` `热门短剧5` 说明具体效果，请见短剧三要素视觉模板。
Title	String	否	`《短剧名称》`	短剧名称。在解说视频画面上展示剧名，用于品牌识别和引导用户搜索。不得超过 15 个字。
Hint	String	否	`影视效果请勿模仿`	短剧提示语。画面左右两侧的一行文字，可以是概括视频核心冲突或亮点的引导性文字，也可以是类似“影视效果请勿模仿无不良价值观引导”的免责声明。不得超过 20 个字。

返回参数

下表仅列出本接口特有的返回参数。更多信息请见公共返回参数。

参数	类型	示例值	描述
TaskId	String	`v02bbbg1006***kbdminbj659kvikr10`	解说视频生成任务 ID。
DramaScriptTaskId	String	`v02bbbg1006***kbdminbj659kvikr0g`	剧本还原任务 ID。

请求示例

POST https://vod.volcengineapi.com?Action=CreateDramaRecapTask&Version=2025-03-03
{
  "SpaceName": "test",
  "Vids": [
    "v02b69g10000***eldb8vjafvmg"
  ],
  "DramaScriptTaskId": "v02bbbg1006***kbdminbj659kvikr10",
  "RecapText": "这是一部关于都市爱情的短剧，讲述了两位年轻人在繁华都市中相遇、相知、相爱的故事。剧情紧凑，情感真挚，展现了现代年轻人对爱情的追求与坚持。",
  "SpeakerConfig": {
    "AppId": "1574***863",
    "Cluster": "volcano_tts",
    "VoiceType": "zh_female_vv_uranus_bigtts"
  },
  "IsEraseSubtitle": true,
  "FontConfig": {}
}

返回示例

{
  "ResponseMetadata": {
    "Action": "CreateDramaRecapTask",
    "Region": "cn-north-1",
    "Service": "vod",
    "Version": "2025-03-03",
    "RequestId": "20230604110420****100232280022D31"
  },
  "Result": {
    "TaskId": "v02bbbg10064d3kbdminbj659kvikr10",
    "DramaScriptTaskId": "v02bbbg10064d3kbdminbj659kvikr0g"
  }
}

错误码

本接口无特有的错误码。更多信息请见公共错误码。

最近更新时间：2025.12.30 16:14:12

这个页面对您有帮助吗？

有用

无用

视频点播

使用说明 #

注意事项 #

请求说明 #

调试 #

请求参数 #

Query #

Body #

返回参数 #

请求示例 #

返回示例 #

错误码 #