数据万象图片盲水印-API 文档-文档中心-腾讯云

功能概述
盲水印功能是指将水印以不可见的形式添加到图片中，与常用的明水印相比，盲水印不会破坏图片的内容完整性。
盲水印的使用流程如下图所示：
﻿
﻿
﻿
支持通过以下几种方式添加盲水印：
﻿上传添加：在上传图片时，同步为该图片添加盲水印并存储。
﻿存量图片添加：对 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。
开通盲水印功能需要授权策略中 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>"
  }]
说明：
Authorization: 携带鉴权信息，用于验证请求的合法性的请求头，Pic-Operations头部需签入签名信息中，详情请参见 请求签名 文档。
Pic-Operations 为 json 格式的字符串，具体参数信息可参见 图片处理机制介绍。
当 fileid 与 ObjectKey 相同时，处理后的图片将覆盖原图存储；不相同时将分别存储原图和处理后图片。
fileid 的值需要经过 URLEncode。
方式三：下载时添加盲水印
在下载图片时添加盲水印，与添加普通水印操作类似，只需在图片访问链接后使用盲水印参数 watermark/3 即可。
请求示例
GET /<ObjectKey>?watermark/3/type/<type>/image/<imageUrl>/text/<text> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
处理参数说明
操作参数：watermark/3，表示当前处理操作为添加盲水印。
示例参数说明如下：
参数名称
描述
类型
是否必选
ObjectKey
对象文件名，例如 folder/sample.jpg。
String
是
type
盲水印类型，有效值：
1：表示图片半盲水印
2：表示图片全盲水印；
3：表示文字盲水印。
不同盲水印类型的区别，请参见 版本说明。
Int
是
image
需要添加的水印图地址，需要经过 URL 安全的  Base64 编码。 当 type 为1或2时必填，type 为3时无效。 指定的水印图片必须同时满足如下条件：
水印图与原图必须存储在同一个账号下的 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
盲水印文字，需要经过 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:XXXXXXXXXXXX
﻿
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>
              <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 请求提取盲水印的请求包与 PUT Object 接口一致，只需在请求包头部增加图片处理参数 Pic-Operations 并使用提取盲水印参数（watermark/4）即可。
PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization:XXXXXXXXXXXX
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:XXXXXXXXXXXX
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，表示当前处理操作为提取盲水印。
示例参数说明如下：
参数名称
描述
类型
是否必选
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.1
Host: examplebucket-1250000000.cos.ap-shanghai.myqcloud.com
Date: Tue, 03 Apr 2018 09:06:15 GMT
Authorization:XXXXXXXXXXXX
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>

水印类型	版本	强度	提取盲水印条件	限制
图片半盲水印（type=1）	无版本可选	无强度可选	提取时需要传入原图。	要求原图宽高均大于水印图的宽高2倍以上；建议选用黑底白色图片作为水印图，盲水印效果会更好，也更容易提取；可抗缩放、压缩。
图片全盲水印（type=2）	version=1.0	支持强度 level={0,1,2,3}，值越大，抗干扰能力越强，高强度下图片可能会泛黄。	提取时需要传入水印图，且需要相同版本。	要求原图宽高均大于水印图的宽高8倍以上；建议原图质量大于90以上，并选用黑底白色图片作为水印图，盲水印效果会更好，也更容易提取；抗攻击性更强，可抗裁剪、缩放、压缩。
图片全盲水印（type=2）		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分辨率以上的任意裁剪、压缩；暂不支持下载时添加该版本

参数名称	描述	类型	是否必选
ObjectKey	对象文件名，例如 folder/sample.jpg。	String	是
type	盲水印类型，有效值： 1：表示图片半盲水印 2：表示图片全盲水印； 3：表示文字盲水印。不同盲水印类型的区别，请参见版本说明。	Int	是
image	需要添加的水印图地址，需要经过 URL 安全的 Base64 编码。当 type 为1或2时必填，type 为3时无效。指定的水印图片必须同时满足如下条件：水印图与原图必须存储在同一个账号下的 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	盲水印文字，需要经过 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	否

节点名称	类型	描述
Key	String	待提取水印的图片名。
Location	String	待提取水印的图片路径。
ImageInfo	Container	待提取水印的图片信息。
ETag	String	待提取水印的图片的 ETag 信息。

图片盲水印

本页目录：

功能概述

版本说明

授权说明

服务开通

使用限制

费用说明

添加盲水印-接口示例

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

请求示例

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

请求示例

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

请求示例

处理参数说明

实际案例

请求

响应

提取盲水印-接口示例

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

请求示例

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

请求示例

处理参数说明

响应

响应头

响应体

响应体参数说明

实际案例

请求

响应