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

本 API 用于提交一个同步的图文水印（明水印）添加任务。支持文字水印和图片水印两种模式，并支持配置水印位置、旋转角度、透明度、字号颜色、铺满密度等参数，适用于版权标识与素材分发防盗链场景。

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	示例值	描述
image_url	String	是	https://example.com/source.jpg	待处理的图片 URL。图像来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、火山引擎对象存储 (tos://) 三种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。文件大小：建议单张图片不超过 35 MB。支持格式：支持 .png、.jpg、.jpeg、.webp 等主流图像格式。仅支持处理静图。输入分辨率限制：宽和高均不得超过 10000 像素。
watermark_type	String	否	text	水印类型，默认为 text。 text：文字水印。 image：图片水印。
output_format	String	否	jpeg	输出图片的格式，默认为 original。 original：保持与原图一致的格式。 png jpeg webp
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。
文字水印参数（当 watermark_type 为 text 时生效）
watermark_text	String	否	© MyBrand	水印文字内容。当 watermark_type 为 text 时必填。不得超过 64 个字符。
watermark_text_font	String	否	zcool_kuaileti.ttf	文字字体，默认为 SourceHanSans-Regular.ttf（思源黑体）。支持思源黑体、思源宋体、站酷、方正兰亭黑等系列字体，具体字体文件名请参考支持字体。
watermark_text_font_size	Integer	否	24	文字字号，单位为像素，默认为 30。取值范围为 [1, 200]。
watermark_text_color	String	否	#FF0000	文字颜色，支持十六进制（如 #FF0000）、RGB 等格式，默认为 #FFFFFF (白色)。
watermark_text_opacity	Integer	否	50	文字水印的不透明度，取值范围 [0, 100]。值越小越透明，默认为 30。
图片水印参数（当 watermark_type 为 image 时生效）
watermark_image_url	String	否	https://example.com/logo.png	图片水印的 URL。当 watermark_type 为 image 时必填。图像来源：必须为公网可访问的 HTTP 或 HTTPS URL。文件大小：建议不超过 5 MB。支持格式：支持 .jpg, .jpeg, .webp 等常见图像格式。
watermark_image_opacity	Integer	否	50	图片水印的不透明度，取值范围为 [0,100]。值越小越透明，默认 100。
通用布局参数
enable_tile	Boolean	否	true	是否启用铺满水印效果，默认为 false。开启后，水印将以固定的间距重复平铺在整个图片上。对于文字水印，会额外应用逆时针 30 度的旋转。对于图片水印，仅进行平铺，不应用旋转。
watermark_position	String	否	bottom_right	水印在图片上的九宫格布局位置，默认为 bottom_right（右下角）。可选值如下： top_left：左上角 top_center：中上 top_right：右上角 left_center：左中 center：正中 right_center：右中 bottom_left：左下角 bottom_center：中下 bottom_right：右下角注意：当使用包含 center 的值（top_center, left_center, center, right_center, bottom_center）时，偏移量参数（watermark_position_offset_x 和 watermark_position_offset_y）将不生效。
watermark_position_offset_x	Integer	否	20	水平偏移量，即水印在 watermark_position 基础上沿 X 轴的微调距离，单位为像素。默认为 0。不得小于 0。注意：该参数仅在 watermark_position 取值不包含 center 时生效。
watermark_position_offset_y	Integer	否	20	垂直偏移量，即水印在 watermark_position 基础上沿 Y 轴的微调距离，单位为像素。默认为 0。不得小于 0。注意：该参数仅在 watermark_position 取值不包含 center 时生效。

请求示例

示例 1：添加文字水印

以下示例演示了如何在图片右下角添加红色的文字水印“© MyBrand”，并设置偏移量。

示例 2：添加图片水印

以下示例演示了如何将一个 Logo 图片作为水印添加到左上角，并设置其为半透明。

响应说明

这是一个同步接口，处理结果将直接在本接口的响应体中返回。

响应参数

参数	类型	描述
success	Boolean	任务是否成功。 true：成功。请查看 result 字段以获取任务结果。 false：失败。请查看 error 字段以获取详细错误信息。
result	Object	包含图像处理结果的对象，仅在 success 为 true 时返回。详见下文 Result 对象。
error	Object	错误详情对象，仅在 success 为 false 时返回。详见下文 Error 结构。
task_id	String	任务的唯一标识。
task_type	String	任务类型。
request_id	String	本次 API 请求的唯一标识，可用于问题排查。
expires_at	Integer	任务结果的过期时间戳（Unix Time，单位：秒）。仅当任务成功且有结果时返回。
queue_id	String	任务提交的目标队列 ID。

Result 对象

参数	类型	描述
image_url	String	处理后的图片文件下载地址。该地址的有效期为 24 小时，请务必及时保存产物。
image_size	Integer	生成图像的大小，单位为字节。
image_format	String	生成图像的格式，例如：webp。
image_width	Integer	生成图像的宽度，单位为 px。
image_height	Integer	生成图像的高度，单位为 px。

Error 对象

参数	类型	描述
code	String	具体的错误码，用于程序化识别错误类型。例如：InvalidParameter。关于各错误码的详细信息，请参阅错误码。
type	String	错误的宏观类型。例如：BadRequest。
message	String	对错误的详细描述，可用于开发调试。

响应示例

成功响应示例：

失败响应示例：

附录

支持字体

中文字体名	英文字体名
思源黑体系列
思源黑体	SourceHanSans-Regular.ttf
思源黑体-Bold	SourceHanSans-Bold.ttf
思源黑体-ExtraLight	SourceHanSans-ExtraLight.ttf
思源黑体-Heavy	SourceHanSans-Heavy.ttf
思源黑体-Light	SourceHanSans-Light.ttf
思源黑体-Medium	SourceHanSans-Medium.ttf
思源黑体-Normal	SourceHanSans-Normal.ttf
思源宋体系列
思源宋体	SourceHanSerifCN-Regular.ttf
思源宋体-Bold	SourceHanSerifCN-Bold.ttf
思源宋体-ExtraLight	SourceHanSerifCN-ExtraLight.ttf
思源宋体-Heavy	SourceHanSerifCN-Heavy.ttf
思源宋体-Light	SourceHanSerifCN-Light.ttf
思源宋体-SemiBold	SourceHanSerifCN-SemiBold.ttf
站酷字体系列
站酷酷黑体	zcool-heiti.ttf
站酷高端黑	zcool_gaoduanhei.ttf
站酷快乐体	zcool_kuaileti.ttf
站酷庆科黄油体	zcool_huangyou.ttf
方正字体系列
方正兰亭黑	FZLTHK.TTF

AI MediaKit