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

本接口用于提交一个异步的视频加图片任务，将指定的图片（如 Logo、水印等）叠加到视频画面上。

获取任务结果：任务提交成功后，您需要保存返回的 task_id，并通过轮询查询任务信息 API 或配置事件回调获取最终结果。

开发指南：如需了解完整的使用流程和应用示例，请参阅视频加图片。

请求参数

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) 分辨率。
sub_image_url	String	是	https://example.com/logo.png	待添加的图片 URL。图片来源：仅支持公网可访问的 HTTP/HTTPS URL。支持格式：建议使用 PNG, JPG, JPEG 等常见图片格式。推荐使用带透明通道的 PNG 格式以获得最佳水印效果。
sub_image_width	String	否	"10%"	图片的宽度。支持像素值（如 "100"）或相对于视频宽度的百分比（如 "10%"）。默认值为 "10%"。
sub_image_height	String	否	"5%"	图片的高度。支持像素值（如 "100"）或相对于视频高度的百分比（如 "5%"）。默认值为 "5%"。
sub_image_pos_x	String	否	"85%"	图片左上角在水平方向（X 轴）的位置，以视频左上角为原点 ("0")。支持像素值或百分比。默认值为 "85%"。
sub_image_pos_y	String	否	"90%"	图片左上角在垂直方向（Y 轴）的位置，以视频左上角为原点 ("0")。支持像素值或百分比。默认值为 "90%"。说明默认的 pos_x 和 pos_y 值（"85%" 和 "90%"）会将图片置于视频画面的右下角区域，适合用作水印。
start_time	Number	否	0	图片开始显示的时间（单位：秒）。默认与视频开始时间一致。
end_time	Number	否	15.5	图片结束显示的时间（单位：秒）。默认与视频结束时间一致。注意如果 end_time 超出原始视频时长，输出视频的长度将延长至该 end_time，超出部分将以黑屏形式延续，图片会继续显示在黑屏上。
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_135	用户请求凭证，用于幂等控制。大小写敏感，不超过 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。详情请参考项目与队列管理。

请求示例

以下示例演示了如何在一个视频的右下角添加一个 PNG 图片作为水印，并让它在视频的第 2 秒到第 10 秒之间显示。

响应说明

任务提交成功响应

任务提交成功后，接口会立即返回以下 JSON 对象。

参数	类型	描述
success	Boolean	任务是否提交成功。 true：成功。 false：失败。更多信息请查看下文的错误处理。
task_id	String	任务的唯一标识，用于后续查询任务进度和结果。
request_id	String	本次请求的唯一标识，可用于问题排查。

示例：

异步任务结果

任务处理完成后，通过查询任务信息 API 或事件回调获取的 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	120.0	输出视频的总时长（单位：秒）。
resolution	String	1080p	输出视频的分辨率。可能的值包括 240p、360p、480p、540p、720p、1080p、2k、4k。

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

错误处理

当请求的参数或鉴权信息不正确时，任务将不会被创建，接口会返回一个同步的错误响应。详见错误码。示例如下：

AI MediaKit