POST https://mediakit.cn-beijing.volces.com/api/v1/tools/add-subtitle-to-video

本接口用于提交一个异步的视频加字幕任务，将指定的字幕文件或文本内容，以自定义样式压制到视频画面中，生成带内嵌字幕的新视频。

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	示例值	描述
video_url	String	是	https://example.com/video.mp4	待添加字幕的视频 URL。视频来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、来源于火山引擎视频点播 (vod://) 和火山引擎对象存储 (tos://) 四种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：mp4, flv, ts, avi, mov, wmv, mkv 等主流视频格式。文件大小：建议输入文件大小不超过 10 GB。输入分辨率限制：输入视频最高支持 4K (3840×2160) 分辨率。
subtitle_url	String	否	https://example.com/sub.srt	字幕文件的 URL。文件来源：仅支持公网可访问的 HTTP/HTTPS URL。支持格式：SRT、VTT、ASS 等常见字幕格式。注意 subtitle_url 和 subtitles 两个参数用于提供字幕内容，必须指定其中一个。当两者都存在时，系统将优先使用 subtitle_url 的内容。
subtitles	Array	否	[{"subtitle_text": "...", "start_time": 0.5, "end_time": 3.0}]	字幕内容列表，由多个字幕对象组成。每个对象包含字幕文本、开始和结束时间，详见下文 Subtitle 对象。注意 subtitle_url 和 subtitles 两个参数用于提供字幕内容，必须指定其中一个。当两者都存在时，系统将优先使用 subtitle_url 的内容。
subtitle_pos_preset	String	否	bottom_center	预设字幕位置。默认值为 bottom_center。 bottom_center: 底部居中 top_center: 顶部居中 center: 画面正中央 lower_third: 偏下三分之一处
subtitle_font_size	Integer	否	50	字幕字体大小，单位为像素 (px)。默认值为 50。
subtitle_font_color	String	否	#FFFFFFFF	字幕字体颜色，采用 RGBA 格式。默认值为 #FFFFFFFF (不透明白色)。
subtitle_text_effect	String	否	vcr://fl10000398	花字效果的资源 ID。默认无花字效果。设置本参数后，subtitle_font_color 参数将不生效。详情请参阅支持的花字。
subtitle_font_type	String	否	sy_black	字幕字体 ID。默认值为 sy_black (思源黑体)。详情请参阅支持的字体。
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_134	用户请求凭证，用于幂等控制。大小写敏感，不超过 64 个 ASCII 码可打印字符。详情请参考幂等性控制。
callback_args	String	否	your_custom_callback_args	自定义回调参数。您提供的内容将在任务完成时，通过事件回调原样返回，方便您关联业务。字段长度最大为 512 字节。
callback_url	String	否	https://example.com/callback	用于接收该任务结果回调的 URL 地址。如果提供此参数，其优先级将高于在控制台配置的全局回调地址。地址必须以 http:// 或 https:// 开头。请参考事件回调了解回调接收机制和回调消息结构。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

Subtitle 对象

参数	类型	是否必选	示例值	描述
subtitle_text	String	是	你好，世界！	单条字幕的文本内容。
start_time	Number	是	0.5	该条字幕的开始显示时间（单位：秒）。
end_time	Number	是	3.0	该条字幕的结束显示时间（单位：秒）。

请求示例

示例 1：使用字幕文件 URL

以下示例演示了如何使用一个 SRT 字幕文件，并自定义字幕样式（思源黑体、48px、底部居中）。

示例 2：使用内嵌字幕文本

以下示例演示了如何直接在请求中提供字幕文本内容列表，并使用“站酷快乐体”字体。

响应说明

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

参数	类型	示例值	描述
video_url	String	https://example.volcvideo.com/output.mp4?auth_key=...	生成的带内嵌字幕的视频文件地址。文件格式为 MP4。地址类型根据请求时是否设置 media_output_destination 而不同：默认情况（未设置 media_output_destination）：返回一个 HTTPS 临时下载链接，有效期为 24 小时，请及时下载保存。设置 media_output_destination 后：返回存储地址，格式为 vod://<空间名>/<媒资ID> 或 tos://<桶名>/<对象Key>。
duration	Number	125.4	输出视频的总时长（单位：秒）。
resolution	String	1080p	输出视频的分辨率。可能的值包括 240p、360p、480p、540p、720p、1080p、2k、4k。

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

附录

支持的字体

字体 ID	字体名称	描述
sy_black	思源黑体	经典无衬线黑体，端正百搭，正文首选。
pm_zhengdao	庞门正道标题体	粗壮有力，硬汉气场，大标题/封面神器。
zhanku_kuaile	站酷快乐体	圆润活泼，带手写感，适合轻松搞笑的 Vlog 氛围。

支持的花字

花字 ID	花字名称	效果示意
vcr://fl10000398	白黑描边
vcr://fl10000397	铁锈红白色描边
vcr://fl10000396	白玫描边
vcr://fl10000395	牛仔蓝描边
vcr://fl10000394	绿色描边
vcr://fl10000393	蓝色描边
vcr://fl10000392	蓝黑描边
vcr://fl10000391	粉白描边
vcr://fl10000390	白粉描边
vcr://fl10000389	黄黑描边
vcr://fl10000388	黑白描边
vcr://fl10000387	立体阴影
vcr://fl10000386	渐变花字
vcr://fl10000385	黑色描边
vcr://fl10000383	纹理花字
vcr://fl10000381	黄白描边

AI MediaKit