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

本 API 用于提交一个同步的图像暗水印添加任务，在不明显破坏图片完整性与画质的前提下，将一段自定义文本信息隐藏式地嵌入图片中，可用于版权保护、AIGC 生图合规、传播追踪与搬运取证等场景。您需要显式指定暗水印模型版本（tool_version），后续提取时使用同一版本。

请求参数

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

Body 参数

参数	类型	是否必选	示例值	描述
image_url	String	是	https://example.com/source_image.jpg	待添加暗水印的图片 URL。图像来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、火山引擎对象存储 (tos://) 三种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。支持格式：支持 .png、.jpg、.jpeg、.webp 等常见主流图像格式。
tool_version	String	是	adapt	暗水印模型版本。支持取值如下： adapt：文本嵌入模型（适用于 AIGC 场景）。该模型版本在画质影响与鲁棒性之间取得了良好平衡，可以抵抗一定程度的分辨率缩放、裁剪及压缩等攻击，建议在为 AIGC 生成的彩色图片添加暗水印时使用。 adapt_resize：文本嵌入模型（适用于搬运取证场景）。此模型能更有效地抵抗图片缩放和压缩攻击，适合用于大规模图片搬运的取证工作。注意：请记录此参数取值，后续调用提交图像暗水印提取任务 API 时必须使用同一版本。
watermark_content	String	是	my-copyright-info	自定义暗水印文本内容，最长 128 字符。如果均为中文文字，建议不超过 42 个字。
strength_level	String	否	medium	暗水印强度。强度越高，抵抗攻击（缩放、压缩、转码等处理）的性能越强，但对原始画面的潜在影响也相对越大。 low：低强度。适用于纯色图场景以及对图像质量要求较高的场景。 medium：（默认值）中强度。在画质与抗攻击性之间取得平衡，适用于大多数场景。 strong：高强度。适合图像纹理丰富时使用，抗攻击性最强。
output_format	String	否	png	输出图片格式，默认为 png。支持 png、jpeg、webp。
output_quality	Integer	否	90	输出图片质量参数，取值范围 [75, 100]，值越小，压缩率越高，画质越差。默认为 90。建议根据所选的模型版本 (tool_version) 和输出格式 (output_format) 设置此参数：当模型版本为 adapt 时：输出格式为 png：建议 output_quality ≥ 75。输出格式为 jpeg：建议 output_quality ≥ 78。输出格式为 webp：建议 output_quality ≥ 90。当模型版本为 adapt_resize 时：建议 output_quality ≥ 75。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

请求示例

以下示例演示了如何为一张图片添加 adapt 版本的暗水印，并写入文本 my-copyright-info。

响应说明

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

响应参数

参数	类型	描述
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，单位：秒）。仅当任务成功且有结果时返回。

Result 对象

参数	类型	描述
image_url	String	添加暗水印后的图片下载 URL，有效期为 24 小时，请务必及时保存。
image_size	Integer	生成图像的大小，单位为字节。
image_format	String	生成图像的格式。
image_width	Integer	生成图像的宽度，单位为 px。
image_height	Integer	生成图像的高度，单位为 px。

Error 对象

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

响应示例

成功响应示例：

失败响应示例：

AI MediaKit