文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>图片处理>API 文档>图片盲水印

图片盲水印

最近更新时间：2025-08-08 15:04:31

我的收藏

本页目录：

功能概述

盲水印功能是指将水印以不可见的形式添加到图片中，与常用的明水印相比，盲水印不会破坏图片的内容完整性。
盲水印的使用流程如下图所示：



支持通过以下几种方式添加盲水印：
上传添加：在上传图片时，同步为该图片添加盲水印并存储。
存量图片添加：对 COS 上已存在的图片，通过添加盲水印参数的形式为图片添加盲水印并转存。
下载添加：在下载图片时，同步为该图片添加盲水印。
支持通过以下几种方式提取盲水印：
PUT 请求提取：使用上传图片接口，同步提取该图片中的盲水印，并将提取出的水印图转存；
POST 请求提取：对 COS 上已存在的图片提取盲水印，并将提取出的水印图转存。

版本说明

盲水印功能有多种类型不同的版本，提取和添加盲水印需要使用相同的类型及版本才能成功提取。
水印类型
版本
强度
提取盲水印条件
限制
优势
文字全盲水印（type = 3）
version = 3.0
支持 level ={0,1,2,3}，值越大，抗干扰能力越强
需要相同版本
提取水印与添加水印需要在同账号同一个存储桶内
支持英文、数字、中文等任意 UTF-8编码的字符作为水印内容，长度不可超过256
要求原图宽高大于64 x 64像素
建议原图质量大于90，盲水印效果会更好，也更容易提取
抗裁剪：可裁剪至剩384 x 384像素依然可正常提取
抗缩放：针对缩放图片还原至原图尺寸可大幅提升提取成功率
抗压缩、截屏
对原图画质影响极低
version = 2.0
支持 level ={0,1,2,3}，值越大，抗干扰能力越强，但图片可能会泛黄
需要相同版本
支持英文、数字、中文等任意 UTF-8编码的字符作为水印内容，长度不可超过256
要求原图宽高大于512 x 512像素
建议原图质量大于90，盲水印效果会更好，也更容易提取
可抗裁剪、缩放、压缩
version = 1.0
不支持
需要相同版本
仅支持数字[0 - 9]及英文大小写[A - Z,a - z]作为水印内容
建议原图质量大于90以上，盲水印效果会更好，也更容易提取
可抗裁剪、缩放、压缩
图片全盲水印（type = 2）
version = 2.0
不支持
提取时需要传入水印图
需要相同版本
要求原图宽高均大于水印图的宽高8倍以上
建议原图质量大于90，并选用黑底白色图片作为水印图，盲水印效果会更好，也更容易提取
对原图画质影响较小，不会导致图片泛黄
可抗缩放、压缩
version = 1.0
支持强度 level ={0,1,2,3}，值越大，抗干扰能力越强，高强度下图片可能会泛黄
要求原图宽高均大于水印图的宽高8倍以上
建议原图质量大于90，并选用黑底白色图片作为水印图，盲水印效果会更好，也更容易提取
可能对原图画质有一定影响，添加水印后的图片会泛黄
可抗裁剪、缩放、压缩
图片半盲水印（type = 1）
无版本可选
无强度可选
提取时需要传入原图
要求原图宽高均大于水印图的宽高2倍以上
建议选用黑底白色图片作为水印图，盲水印效果会更好，也更容易提取
可抗缩放、压缩
说明：
盲水印添加后，能否成功提取取决于原图的质量及提取时图片的改变程度，建议通过 质量变换 将图片提升到90以上的质量再添加盲水印，如果提取盲水印时图片被过度缩放或过度压缩会导致无法提取，更多详情请 提交工单 咨询。

授权说明

通过子账号使用时，需要在 授权策略 的 action 中添加对应的权限，数据万象支持的所有操作接口请参见 action。
开通盲水印功能需要授权策略中 action 设置为 ci:SetImageBlindWatermark ，通过不同方式使用盲水印时，授权策略如下：
下载时处理：授权策略中 action 设置为 cos:GetObject。
上传时处理：授权策略中 action 设置为 cos:PutObject。
云上数据处理：授权策略中 action 设置为 cos:GetObject、cos:PutObject。
注意：
GetObject 对应的 resource 为源文件，PutObject 对应的 resource 为转存的文件。

服务开通

使用该功能需提前 绑定存储桶，开通数据万象服务。
使用该功能需提前通过 控制台 开通盲水印功能。
注意：
数据万象绑定后，如果您手动对存储桶进行数据万象的解绑操作，将无法继续使用该功能。

使用限制

使用该接口时，请先确认相关限制条件。详情请参见 使用限制。

费用说明

盲水印为付费功能，详细计费说明请参见 盲水印费用。
如果采用下载时处理的方式，且通过外网进行下载，调用会产生 万象流量费用。

添加盲水印-接口示例

方式一：上传时添加盲水印

在上传图片时添加盲水印的请求包与 PUT Object 接口一致，只需在请求包头部增加图片处理参数 Pic-Operations 并使用盲水印参数即可。

请求示例

PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Pic-Operations: 
{
  "is_pic_info": 1,
  "rules": [{
      "fileid": "exampleobject.jpg",
      "rule": "watermark/3/type/<type>
                          /image/<encodedURL>
                          /text/<TextBase64>
                    	  /level/<level>
                    	  /version/<version>"
  }]
}

方式二：对 COS 上的图片添加盲水印

通过 API 能够对已存储在 COS 的图片进行添加盲水印的操作，并将添加好盲水印的图片转存回 COS。

请求示例

POST /<ObjectKey>?image_process HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Pic-Operations: 
{
  "is_pic_info": 1,
  "rules": [{
      "fileid": "exampleobject.jpg",
      "rule": "watermark/3/type/<type>/image/<encodedURL>
                                      /text/<TextBase64>
                    	              /level/<level>
                    	              /version/<version>"
  }]
}

方式三：下载时添加盲水印

在下载图片时添加盲水印，与添加普通水印操作类似，只需在图片访问链接后使用盲水印参数 watermark/3即可。

请求示例

GET /<ObjectKey>?watermark/3/type/<type>/image/<imageUrl>/text/<text>/version/<version> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
说明：
Authorization: 携带鉴权信息，用于验证请求的合法性的请求头，Pic-Operations 头部需签入签名信息中，详情请参见 请求签名 文档。
Pic-Operations 为 json 格式的字符串，具体参数信息请参见 图片处理机制介绍。
当 fileid 与 ObjectKey 相同时，处理后的图片将覆盖原图存储；不相同时将分别存储原图和处理后图片。
fileid 的值需要经过 URLEncode。

处理参数说明

操作参数：watermark/3，表示当前处理操作为添加盲水印。
示例参数说明如下：
参数名称
描述
类型
是否必选
ObjectKey
对象文件名，例如 folder/sample.jpg。
String
是
type
盲水印类型，有效值：
1：表示图片半盲水印
2：表示图片全盲水印
3：表示文字盲水印
不同盲水印类型的区别，请参见 版本说明。
Int
是
image
需要添加的水印图地址，需要经过 URL 安全的 Base64编码。 当 type 为1或2时必填，type 为3时无效。指定的水印图片必须同时满足如下条件：
水印图与原图必须存储在同一个账号下的 COS 存储桶中，且两者所在的存储桶必须位于同一个地域内
URL 需使用 COS 域名（不能使用 CDN 加速域名，例如 examplebucket-1250000000.file.myqcloud.com/shuiyin_2.png 不可用），且需保证水印图可访问（如果水印图读取权限为私有，则需要携带有效签名）
URL 必须以 http:// 开始，不能省略 http 头，也不能填 https 头，例如以下地址为非法水印地址：
examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/watermark.png
https://examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/watermark.png
String
否
text
盲水印文字，需要经过 URL 安全的 Base64编码。当 type 为3时必填，type 为1或2时无效
String
否
version
盲水印的版本，默认值为1.0，可选值包括：1.0、2.0、3.0，推荐使用3.0版本，不同版本的区别请参见 版本说明，提取时需使用相同的版本，否则会提取失败。
注意：3.0版本仅支持文字盲水印。
String
否
level
盲水印的强度，默认值为1，可选值包括：0、1、2、3，level 的值越大抗干扰能力越强，同时对画质的影响也越大。不同强度的区别请参见 版本说明。
Int
否

实际案例

以上传时添加盲水印为例，上传一个名为 exampleobject.jpg 的图片，并以图片半盲水印的方式将水印图添加到 exampleobject.jpg 中，水印图链接为：http://examples-1251000004.picsh.myqcloud.com/shuiyin.jpg。
请求
PUT /exampleobject.jpg HTTP/1.1
Host: examplebucket-1250000000.cos.ap-shanghai.myqcloud.com
Date: Tue, 03 Apr 2018 09:06:15 GMT
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1586511305;1586518505&q-key-time=1586511305;1586518505&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=&q-signature=****************************************

Pic-Operations:
{
    "is_pic_info": 1,
    "rules": [{
        "fileid": "exampleobject.jpg",
        "rule": "watermark/3/type/1/image/aHR0cDovL2V4YW1wbGVzLTEyNTEwMDAwMDQucGljc2gubXlxY2xvdWQuY29tL3NodWl5aW4uanBn"
    }]
}
Content-Length: 64

[Object Content]
响应
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 645
Date: Tue, 03 Apr 2018 09:06:16 GMT
Status: 200 OK
x-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****

<UploadResult>
	<OriginalInfo>
		<Key>exampleobject.jpg</Key>
		<Location>examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/exampleobject.jpg</Location>
		<ETag>&quot;27aede38eb761b573fc96404ecc986fd&quot;</ETag>
		<VersionId>MTg0NDQ5OTI4MDM2MjgyNTkzMzE</VersionId>
		<ImageInfo>
			<Md5>27aede38eb761b573fc96404ecc986fd</Md5>
			<Format>JPEG</Format>
			<Width>3840</Width>
			<Height>2280</Height>
			<Quality>70</Quality>
			<Ave>0x000</Ave>
			<FrameCount>1</FrameCount>
			<BitDepth>8</BitDepth>
		</ImageInfo>
	</OriginalInfo>
	<ProcessResults>
		<Object>
			<Key>exampleobject.jpg</Key>
			<Location>examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/exampleobject.jpg</Location>
			<Format>jpeg</Format>
			<Md5>874c684feb1153f071dca2afc6221ac5</Md5>
			<Width>3840</Width>
			<Height>2280</Height>
			<Size>727940</Size>
			<Quality>70</Quality>
			<FrameCount>1</FrameCount>
			<BitDepth>8</BitDepth>
			<ETag>&quot;874c684feb1153f071dca2afc6221ac5&quot;</ETag>
			<VersionId>MTg0NDQ5OTI4MDM2MjgyMzI4NjU</VersionId>
		</Object>
	</ProcessResults>
</UploadResult>
注意：
请求体的[Object Content]字段为原图的图片内容(二进制字符串)，请求头 Pic-Operations 的 rule 字段中，imageUrl 为水印图片的地址。
响应体参数说明请参见 图片处理机制说明 > 上传时处理返回内容。

提取盲水印-接口示例

对已添加了盲水印的图片，需要使用提取盲水印接口才能提取到盲水印，不论是图片盲水印还是文字盲水印，最终提取出来都是以水印图片的形式返回。

方式一：使用 PUT 请求提取盲水印

请求示例

通过 PUT 请求提取盲水印的请求包与 PUT Object 接口一致，只需在请求包头部增加图片处理参数 Pic-Operations 并使用提取盲水印参数（watermark/4）即可。
PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Pic-Operations: 
{
  "is_pic_info": 1,
  "rules": [{
      "fileid": "exampleobject.jpg",
      "rule": "watermark/4/type/<type>/image/<encodedURL>/version/<version>"
  }]
}

方式二：使用 POST 请求提取盲水印

请求示例

通过 POST 请求提取盲水印的请求包与 云上数据处理 接口一致，只需在请求包头部增加图片处理参数 Pic-Operations 并使用提取盲水印参数（watermark/4）即可。
POST /<ObjectKey>?image_process HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Pic-Operations: 
{
  "is_pic_info": 1,
  "rules": [{
      "fileid": "exampleobject.jpg",
      "rule": "watermark/4/type/<type>/image/<encodedURL>/version/<version>"
  }]
}
说明：
Authorization: 携带鉴权信息，用于验证请求的合法性的请求头，Pic-Operations 头部需签入签名信息中，详情请参见 请求签名 文档。
Pic-Operations 为 json 格式的字符串，具体参数信息请参见 图片处理机制介绍。
当 fileid 与 ObjectKey 相同时，处理后的图片将覆盖原图存储；不相同时将分别存储原图和处理后图片。
fileid 的值需要经过 URLEncode。

处理参数说明

操作参数：watermark/4，表示当前处理操作为提取盲水印。
示例参数说明如下：
参数名称
描述
类型
是否必选
ObjectKey
对象文件名，例如 folder/sample.jpg。
String
是
type
盲水印类型，有效值：
1：表示图片半盲水印
2：表示图片全盲水印
3：表示文字盲水印
注意：提取时必须跟添加盲水印时的 type 类型一致。
Int
是
image
图片地址，根据 type 值填写：
当 type 为1，则 image 必填，且为原图图片地址
当 type 为2，则 image 必填，且为水印图地址
当 type 为3，则 image 无需填写（无效）
image 需要经过 URL 安全的 Base64编码，指定的图片必须同时满足如下条件：
水印图与原图必须存储在同一个账号下的 COS 存储桶中，且两者所在的存储桶必须位于同一个地域内
URL 需使用 COS 域名（不能使用 CDN 加速域名，例如 examplebucket-1250000000.file.myqcloud.com/shuiyin_2.png 不可用），且需保证水印图可访问（如果水印图读取权限为私有，则需要携带有效签名）。
URL 必须以 http:// 开始，不能省略 http 头，也不能填 https 头，例如以下地址为非法水印地址：
examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/watermark.png
https://examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/watermark.png
String
否
version
盲水印的版本，默认值为1.0，可选值包括：1.0、2.0、3.0。
注意：提取时必须跟添加盲水印时的 version 版本号一致。
String
否

响应

响应头

此接口仅返回公共响应头部，详情请参见 公共响应头部 文档。

响应体

<UploadResult>
	<OriginalInfo>
		<Key>filename.jpg</Key>
		<Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/filename.jpg</Location>
		<ETag>&quot;27aede38eb761b573fc96404ecc986fd&quot;</ETag>
		<VersionId>MTg0NDQ5OTI4MDI4NTQwMDg2NjQ</VersionId>
		<ImageInfo>
			<Md5>27aede38eb761b573fc96404ecc986fd</Md5>
			<Format>JPG</Format>
			<Width>3840</Width>
			<Height>2280</Height>
			<Quality>70</Quality>
			<Ave>0x000</Ave>
			<FrameCount>1</FrameCount>
			<BitDepth>8</BitDepth>
		</ImageInfo>
	</OriginalInfo>
	<ProcessResults>
		<Object>
			<Key>exampleobject.jpg</Key>
			<Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/exampleobject.jpg</Location>
			<Format>jpg</Format>
			<Md5>977c29ccb8c269aeb26709ca44f9efd7</Md5>
			<Width>1920</Width>
			<Height>1152</Height>
			<Size>309380</Size>
			<Quality>70</Quality>
			<FrameCount>1</FrameCount>
			<BitDepth>8</BitDepth>
            <VerticalDpi>37</VerticalDpi>
            <HorizontalDpi>37</HorizontalDpi>
			<ETag>&quot;977c29ccb8c269aeb26709ca44f9efd7&quot;</ETag>
			<VersionId>MTg0NDQ5OTI4MDIzNjYzNzQyMzc</VersionId>
		</Object>
	</ProcessResults>
</UploadResult>

响应体参数说明

UploadResult 节点内容：
参数名称
类型
描述
OriginalInfo
Container
待提取水印的图片信息
ProcessResults
Container
提取出的水印信息
OriginalInfo 节点内容：
节点名称
类型
描述
Key
String
待提取水印的图片名
Location
String
待提取水印的图片路径
ETag
String
待提取水印的图片的 ETag 信息
VersionId
String
待提取水印的图片的版本信息
ImageInfo
Container
待提取水印的图片信息
ImageInfo 节点内容：
节点名称
类型
描述
Md5
String
图片的 Md5值
Format
String
图片格式
Width
Int
图片宽度
Height
Int
图片高度
Quality
Int
图片质量
Ave
String
图片主色调，格式为：0xRRGGBB （RR、GG、BB 都是十六进制数，表示红、绿、蓝三种颜色）
FrameCount
Int
图片的帧数。静态图为1，动图为对应的帧数.
BitDepth
Int
图片的位深度
ProcessResults 节点内容：
节点名称
类型
描述
Object
Container
当水印类型为图片半盲水印、图片盲水印时，该节点表示提取出来的水印图
当水印类型为文字盲水印，且 version 版本号为1.0或2.0时，提取的水印文字信息会以图片形式返回，该节点表示提取出来的文字水印图
当水印类型为文字盲水印，且 version 版本号为3.0时，提取的水印文字信息不通过该节点返回，该节点表示原图信息
Text
String
仅当水印类型为文字盲水印，且 version 版本号为3.0时返回该节点，表示嵌入的文字水印，例如：数据万象
WatermarkStatusCode
Int
仅当水印类型为文字盲水印，且 version 版本号为3.0时返回该节点，表示是否提取到盲水印。取值如下：
0：表示未提取到盲水印
1：表示成功提取到盲水印，水印信息为 Text 节点内容
ProcessResults.Object 节点内容：
节点名称
类型
描述
Key
String
提取出来的水印图名称，对应请求中的 fileid
Location
String
水印图的路径
Format
String
水印图的格式
Md5
String
水印图的 Md5值
Width
Int
水印图的宽度
Height
Int
水印图的高度
Size
Int
水印图的大小
Quality
Int
水印图的质量
FrameCount
Int
水印图的帧数，固定为1
BitDepth
Int
水印图的位深度
VerticalDpi
Int
水印图的垂直分辨率
HorizontalDpi
Int
水印图的水平分辨率
ETag
String
水印图的 ETag 信息
VersionId
String
水印图的版本信息
WatermarkStatus
Int
仅当水印类型为图片全盲水印（type = 2） 时返回该字段，表示提取到全盲水印的可信度。
75—100分：表示确定有盲水印
60-75分：表示疑似有盲水印
60以下：可认为未提取到盲水印

实际案例

以 PUT 请求提取盲水印为例，现在需要对一个名为 exampleobject.jpg 的图片进行盲水印的提取，以图片全盲水印的方式进行提取，水印图链接为：http://examples-1251000004.picsh.myqcloud.com/filename.jpeg 。

请求

PUT /exampleobject.jpg HTTP/1.1
Host: examplebucket-1250000000.cos.ap-shanghai.myqcloud.com
Date: Tue, 03 Apr 2018 09:06:15 GMT
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1586511305;1586518505&q-key-time=1586511305;1586518505&q-header-list=content-length;content-md5;content-type;date;host&q-url-param-list=&q-signature=****************************************
Pic-Operations:
{
    "is_pic_info": 1,
    "rules": [{
        "fileid": "exampleobject2.jpg",
        "rule": "watermark/4/type/2/image/aHR0cDovL2V4YW1wbGVzLTEyNTEwMDAwMDQucGljc2gubXlxY2xvdWQuY29tL2ZpbGVuYW1lLmpwZWc="
    }]
}
Content-Length: 64

[Object Content]

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 645
Date: Tue, 03 Apr 2018 09:06:16 GMT
Status: 200 OK
x-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****

<UploadResult>
      <OriginalInfo>
          <Key>exampleobject.jpg</Key>
          <Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/exampleobject.jpg</Location>
          <ImageInfo>
                <Format>JPEG</Format>
                <Width>640</Width>
                <Height>427</Height>
                <Quality>100</Quality>
                <Ave>0xa18454</Ave>
                <Orientation>1</Orientation>
                <FrameCount>1</FrameCount>
          </ImageInfo>
      </OriginalInfo>
      <ProcessResults>
          <Object>
                <Key>exampleobject2</Key>
                <Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/exampleobject2</Location>
                <Format>jpg</Format>
                <Width>640</Width>
                <Height>427</Height>
                <Size>463092</Size>
                <Quality>100</Quality>
                <FrameCount>1</FrameCount>
                <WatermarkStatus>86</WatermarkStatus>
          </Object>
      </ProcessResults>
</UploadResult>
中国站
目录