功能概述
盲水印功能是指将水印以不可见的形式添加到图片中,与常用的明水印相比,盲水印不会破坏图片的内容完整性。
盲水印的使用流程如下图所示:
支持通过以下几种方式添加盲水印:
上传添加:在上传图片时,同步为该图片添加盲水印并存储。
存量图片添加:对 COS 上已存在的图片,通过添加盲水印参数的形式为图片添加盲水印并转存。
下载添加:在下载图片时,同步为该图片添加盲水印。
支持通过以下几种方式提取盲水印:
PUT 请求提取:使用上传图片接口,同步提取该图片中的盲水印,并将提取出的水印图转存;
POST 请求提取:对 COS 上已存在的图片提取盲水印,并将提取出的水印图转存。
版本说明
盲水印功能有多种类型不同的版本,提取和添加盲水印需要使用相同的类型及版本才能成功提取。
水印类型 | 版本 | 强度 | 提取盲水印条件 | 限制 |
图片半盲水印(type=1) | 无版本可选 | 无强度可选 | 提取时需要传入原图。 | 要求原图宽高均大于水印图的宽高2倍以上; 建议选用黑底白色图片作为水印图,盲水印效果会更好,也更容易提取; 可抗缩放、压缩。 |
图片全盲水印(type=2) | version=1.0 | 支持强度 level={0,1,2,3},值越大,抗干扰能力越强,高强度下图片可能会泛黄。 | 提取时需要传入水印图,且需要相同版本。 | 要求原图宽高均大于水印图的宽高8倍以上; 建议原图质量大于90以上,并选用黑底白色图片作为水印图,盲水印效果会更好,也更容易提取; 抗攻击性更强,可抗裁剪、缩放、压缩。 |
| version=2.0 | 不支持 | | 要求原图宽高均大于水印图的宽高8倍以上; 建议原图质量大于90以上,并选用黑底白色图片作为水印图,盲水印效果会更好,也更容易提取; 对原图影响更小,不会导致图片泛黄; 可抗缩放、压缩。 |
文字全盲水印(type=3) | version=1.0 | 不支持 | 需要相同版本 | 仅支持数字[0 - 9]及英文大小写[A - Z,a - z]作为水印内容; 建议原图质量大于90以上,盲水印效果会更好,也更容易提取; 可抗裁剪、缩放、压缩。 |
| version=2.0 | 支持level={0,1,2,3},值越大,抗干扰能力越强,但图片可能会泛黄。 | | 仅支持数字[0 - 9]及英文大小写[A - Z,a - z]作为水印内容; 建议原图质量大于90以上,盲水印效果会更好,也更容易提取; 要求原图宽高大于512 x 512像素; 可抗裁剪、缩放、压缩。 |
| version=3.0 | 支持level={0,1,2,3},值越大,抗干扰能力越强。 | | 支持英文、数字、中文等任意UTF8编码的字符作为水印内容,长度不可超过256; 要求原图宽高大于64 x 64像素; 抗攻击性更强,可抗384 x 384分辨率以上的任意裁剪、压缩。 暂不支持下载时添加该版本 |
说明:
授权说明
开通盲水印功能需要授权策略中 action 设置为
ci:SetImageBlindWatermark
,通过不同方式使用盲水印时,授权策略如下:下载时处理:授权策略中 action 设置为
cos:GetObject
。上传时处理:授权策略中 action 设置为
cos:PutObject
。云上数据处理:授权策略中 action 设置为
cos:GetObject
、cos:PutObject
(注意 GetObject 对应的 resource 为源文件,PutObject 对应的 resource 为转存的文件)。服务开通
使用该功能需提前开通数据万象,并绑定存储桶。详情请参见 绑定存储桶。
使用该功能需开启盲水印,详情请参见设置盲水印。
使用限制
费用说明
盲水印为付费功能,由数据万象产品收取,详细计费说明可参见 盲水印费用。
如果采用下载时处理的方式,且通过外网进行下载,调用会产生 万象流量费用。
添加盲水印-接口示例
方式一:上传时添加盲水印
请求示例
PUT /<ObjectKey> HTTP/1.1Host: <BucketName-APPID>.cos.<Region>.myqcloud.comDate: GMT DateAuthorization: Auth StringPic-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.1Host: <BucketName-APPID>.cos.<Region>.myqcloud.comDate: GMT DateAuthorization: Auth StringPic-Operations:{"is_pic_info": 1,"rules": [{"fileid": "exampleobject.jpg","rule": "watermark/3/type/<type>/image/<encodedURL>/text/<TextBase64>/level/<level>/version/<version>"}]
说明:
Authorization: 携带鉴权信息,用于验证请求的合法性的请求头,Pic-Operations头部需签入签名信息中,详情请参见 请求签名 文档。
Pic-Operations 为 json 格式的字符串,具体参数信息可参见 图片处理机制介绍。
当
fileid
与 ObjectKey
相同时,处理后的图片将覆盖原图存储;不相同时将分别存储原图和处理后图片。fileid
的值需要经过 URLEncode。方式三:下载时添加盲水印
在下载图片时添加盲水印,与添加普通水印操作类似,只需在图片访问链接后使用盲水印参数 watermark/3 即可。
请求示例
GET /<ObjectKey>?watermark/3/type/<type>/image/<imageUrl>/text/<text> HTTP/1.1Host: <BucketName-APPID>.cos.<Region>.myqcloud.comDate: <GMT Date>Authorization: <Auth String>
处理参数说明
操作参数:watermark/3,表示当前处理操作为添加盲水印。
示例参数说明如下:
参数名称 | 描述 | 类型 | 是否必选 |
ObjectKey | 对象文件名,例如 folder/sample.jpg。 | String | 是 |
type | 盲水印类型,有效值: 1:表示图片半盲水印 2:表示图片全盲水印; 3:表示文字盲水印。 | Int | 是 |
image | 水印图与原图必须存储在同一个账号下的 COS 存储桶中,且两者所在的存储桶必须位于同一个地域内; 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 | String | 否 | |
version | String | 否 | |
level | Int | 否 |
实际案例
以上传时添加盲水印为例,上传一个名为
exampleobject.jpg
的图片,并以图片半盲水印的方式将水印图添加到exampleobject.jpg
中,水印图链接为:http://examples-1251000004.picsh.myqcloud.com/shuiyin.jpg
。请求
PUT /exampleobject.jpg HTTP/1.1Host: examplebucket-1250000000.cos.ap-shanghai.myqcloud.comDate: Tue, 03 Apr 2018 09:06:15 GMTAuthorization:XXXXXXXXXXXXPic-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 OKContent-Type: application/xmlContent-Length: 645Date: Tue, 03 Apr 2018 09:06:16 GMTStatus: 200 OKx-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****<UploadResult><OriginalInfo><Key>exampleobject.jpg</Key><Location>examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/exampleobject.jpg</Location><ImageInfo><Format>JPEG</Format><Width>640</Width><Height>427</Height><Quality>100</Quality><Ave>0xa18454</Ave><Orientation>1</Orientation></ImageInfo></OriginalInfo><ProcessResults><Object><Key>exampleobject.jpg</Key><Location>examplebucket-1250000000.cos.ap-shanghai.myqcloud.com/exampleobject.jpg</Location><Format>jpg</Format><Width>640</Width><Height>427</Height><Size>463092</Size><Quality>100</Quality></Object></ProcessResults></UploadResult>
注意:
请求体的 [Object Content] 字段为原图的图片内容(二进制字符串),请求头 Pic-Operations 的 rule 字段中,imageUrl 为水印图片的地址。
响应体参数说明可参见 图片处理机制说明-上传时处理返回内容。
提取盲水印-接口示例
对已添加了盲水印的图片,需要使用提取盲水印接口才能提取到盲水印,不论是图片盲水印还是文字盲水印,最终提取出来都是以水印图片的形式返回。
方式一:使用 PUT 请求提取盲水印
请求示例
PUT /<ObjectKey> HTTP/1.1Host: <BucketName-APPID>.cos.<Region>.myqcloud.comDate: GMT DateAuthorization:XXXXXXXXXXXXPic-Operations:{"is_pic_info": 1,"rules": [{"fileid": "exampleobject.jpg","rule": "watermark/4/type/<type>/image/<encodedURL>/version/<version>"}]
方式二:使用 POST 请求提取盲水印
请求示例
POST /<ObjectKey>?image_process HTTP/1.1Host: <BucketName-APPID>.cos.<Region>.myqcloud.comDate: GMT DateAuthorization:XXXXXXXXXXXXPic-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,表示当前处理操作为提取盲水印。
示例参数说明如下:
参数名称 | 描述 | 类型 | 是否必选 |
fileid | 提取出来的水印图的保存路径及名称。当 fileid 与 ObjectKey 相同时,水印图将覆盖待提取水印的图片存储;不相同时将分别存储待提取水印的图片和水印图。名称规则说明:名称需要经过 URLEncode。 以 / 开头为绝对路径,例如 fileid 值为 /p2/test2.jpg 时,表示在 p2 文件夹中存储了一个文件名为 test2.jpg 的文件。不以 / 开头为相对路径,例如 fileid 值为 p2/test2.jpg 时,表示在 p1 文件夹中新建了一个 p2 文件夹,然后在 p2 文件夹中存储了一个文件名为 test2.jpg 的文件。注意:请不要以 / 结尾,否则会产生空文件名。 | String | 是 |
type | 盲水印类型,有效值: 1:表示图片半盲水印 2:表示图片全盲水印 3:表示文字盲水印 注意:提取时必须跟添加盲水印时的 type 类型一致。 | Int | 是 |
image | 图片地址,根据 type 值填写: 当 type 为1,则 image 必填,且为原图图片地址 当 type 为2,则 image 必填,且为水印图地址 当 type 为3,则 image 无需填写(无效) image 需要经过 URL 安全的 Base64 编码,指定的图片必须同时满足如下条件: 水印图与原图必须存储在同一个账号下的 COS 存储桶中,且两者所在的存储桶必须位于同一个地域内; 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>xxxx</ETag></OriginalInfo><ProcessResults><Object><Key>watermark.jpg</Key><Location>examplebucket-1250000000.cos.ap-chengdu.myqcloud.com/watermark.jpg</Location><Format>jpg</Format><Width>640</Width><Height>427</Height><Size>463092</Size><Quality>100</Quality><ETag>xxxxxxx</ETag><FrameCount>1</FrameCount><WatermarkStatus>90</WatermarkStatus></Object><Text>xxxxxxx</Text><WatermarkStatusCode>1</WatermarkStatusCode></ProcessResults></UploadResult>
响应体参数说明
UploadResult 节点内容:
参数名称 | 类型 | 描述 |
OriginalInfo | Container | 待提取水印的图片信息。 |
ProcessResults | Container | 提取出的水印信息。 |
OriginalInfo 节点内容:
节点名称 | 类型 | 描述 |
Key | String | 待提取水印的图片名。 |
Location | String | 待提取水印的图片路径。 |
ImageInfo | Container | 待提取水印的图片信息。 |
ETag | String | 待提取水印的图片的 ETag 信息。 |
ImageInfo 节点内容:
节点名称 | 类型 | 描述 |
Format | String | 图片格式 |
Width | Int | 图片宽度 |
Height | Int | 图片高度 |
Quality | Int | 图片质量 |
Ave | String | 图片主色调,格式为:0xRRGGBB (RR、GG、BB都是十六进制数,表示红、绿、蓝三种颜色) |
Orientation | Int | 图片旋转角度,取值为1-8的整数: 1:旋转0° 2:水平翻转 3:旋转180° 4:垂直翻转 5:顺时针旋转90°+水平翻转 6:顺时针旋转90° 7:顺时针旋转90°+垂直翻转 8:逆时针旋转90° |
FrameCount | Int | 图片的帧数。静态图为1,动图为对应的帧数. |
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 | 水印图的路径。 |
WatermarkStatus | Int | 仅当水印类型为图片全盲水印(type = 2) 时返回该字段,表示提取到全盲水印的可信度。 75—100分:表示确定有盲水印; 60-75分:表示疑似有盲水印; 60以下:可认为未提取到盲水印。 |
Format | String | 水印图的格式。 |
Width | Int | 水印图的宽度。 |
Height | Int | 水印图的高度。 |
Size | Int | 水印图的大小。 |
Quality | Int | 水印图的质量。 |
ETag | String | 水印图的 ETag 信息。 |
FrameCount | Int | 水印图的帧数,固定为1。 |
实际案例
以 PUT 请求提取盲水印为例,现在需要对一个名为
exampleobject.jpg
的图片进行盲水印的提取,以图片全盲水印的方式进行提取,水印图链接为:http://examples-1251000004.picsh.myqcloud.com/filename.jpeg
。请求
PUT /exampleobject.jpg HTTP/1.1Host: examplebucket-1250000000.cos.ap-shanghai.myqcloud.comDate: Tue, 03 Apr 2018 09:06:15 GMTAuthorization:XXXXXXXXXXXXPic-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 OKContent-Type: application/xmlContent-Length: 645Date: Tue, 03 Apr 2018 09:06:16 GMTStatus: 200 OKx-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>