智能多媒体 > API 文档 > 图片处理 >图片水印处理（watermark）

图片水印处理（watermark）

最近更新时间：2021-02-04 11:44:19

七牛云存储提供四种水印接口：图片水印、文字水印，文字平铺水印、混合水印、渐变色水印。

注意： watermark 接口支持的最大 gif 帧数为 200，超过 200，处理结果只返回原图。

图片水印

接口规格

注意： 接口规格不含任何空格与换行符。

watermark/1
         /image/<encodedImageURL>
         /dissolve/<dissolve>
         /gravity/<gravity>
         /dx/<distanceX>
         /dy/<distanceY>
         /ws/<watermarkScale>
         /wst/<watermarkScaleType>

参数名称	必填	说明
`/image/<encodedImageURL>`	是	水印的源路径，目前支持公网资源，及 kodo 资源。公网资源由 url 表示，kodo 资源可由 `kodo://<bucketname>/<key>` 表示（此时 bucketname 需要与输入源在同一区域），均需要经过`urlsafe_base64_encode`。
`/dissolve/<dissolve>`		透明度，取值范围1-100，默认值为100（完全不透明）。
`/gravity/<gravity>`		水印位置，参考水印锚点参数表，默认值为`SouthEast`（右下角）。
`/dx/<distanceX>`		横轴边距，单位:像素(px)，默认值为10。
`/dy/<distanceY>`		纵轴边距，单位:像素(px)，默认值为10。
`/ws/<watermarkScale>`		水印图片自适应原图的短边比例，ws的取值范围为0-1。具体是指水印图片保持原比例，并短边缩放到原图短边＊ws。
`/wst/<watermarkScaleType>`		水印图片自适应原图的类型，取值0、1、2、3分别表示为自适应原图的短边、长边、宽、高，默认值为0

例如：原图大小为250x250，水印图片大小为91x61，如果ws=1，那么最终水印图片的大小为：372x250。

水印锚点参数表

NorthWest     |     North      |     NorthEast
              |                |    
              |                |    
--------------+----------------+--------------
              |                |    
West          |     Center     |          East 
              |                |    
--------------+----------------+--------------
              |                |    
              |                |    
SouthWest     |     South      |     SouthEast

请求报文

请求语法

GET <imageDownloadURI>?<接口规格> HTTP/1.1
Host: <imageDownloadHost>

头部信息

头部名称	必填	说明
Host	是	下载服务器域名，可为七牛三级域名或自定义二级域名，参考七牛自定义域名绑定流程。

响应报文

响应语法

HTTP/1.1 200 OK
Content-Type: <imageMimeType>

<imageBinaryData>

头部信息

头部名称	必填	说明
Content-Type	是	MIME类型，成功时为图片的MIME类型，失败时为`application/json`。
Cache-Control		缓存控制，失败时为`no-store`，不缓存。

响应内容

如果请求成功，返回图片的二进制数据。
如果请求失败，返回包含如下内容的 JSON 字符串 (已格式化，便于阅读)：

{
    "code":     <HttpCode  int>, 
    "error":   "<ErrMsg    string>",
}

字段名称	必填	说明
code	是	HTTP状态码，请参考响应状态
error	是	与HTTP状态码对应的消息文本

响应状态码

HTTP状态码	含义
200	添加水印成功
400	请求报文格式错误
404	资源不存在
599	服务端操作失败。如遇此错误，请将完整错误信息（包括所有HTTP响应头部）提交工单给我们。

使用示例

水印图片: https://olhvkds73.qnssl.com/logo.png
- ImageURL = "https://olhvkds73.qnssl.com/logo.png"
- encodedImageURL = urlsafe_base64_encode(ImageURL)
水印透明度: 50% (dissolve=50)
水印位置: 右下角 (gravity=SouthEast)
横向边距: 20px
纵向边距: 20px

图片水印

图片链接的URL:https://dn-odum9helk.qbox.me/4c0aa36a9aafb42adeb9e9c173c62a13

文字水印

接口规格

注意： 接口规格不含任何空格与换行符。

watermark/2
         /text/<encodedText>
         /font/<encodedFontName>
         /fontsize/<fontSize>
         /fill/<encodedTextColor>
         /dissolve/<dissolve>
         /gravity/<gravity>
         /dx/<distanceX>
         /dy/<distanceY>

参数名称	必填	说明
`/text/<encodedText>`	是	水印文字内容（经过URL安全的Base64编码）
`/font/<encodedFontName>`		水印文字字体（经过URL安全的Base64编码），默认为黑体，详见支持字体列表注意：中文水印必须指定中文字体。
`/fontsize/<fontSize>`		水印文字大小，单位: 缇，等于1/20磅，默认值是240缇，参考DPI为72。
`/fill/<encodedTextColor>`		水印文字颜色，RGB格式，可以是颜色名称（例如 red）或十六进制（例如 #FF0000），参考RGB颜色编码表，默认为黑色。经过URL安全的Base64编码。
`/dissolve/<dissolve>`		透明度，取值范围1-100，默认值100（完全不透明）。
`/gravity/<gravity>`		水印位置，参考水印位置参数表，默认值为`SouthEast`（右下角）。
`/dx/<distanceX>`		横轴边距，单位:像素(px)，默认值为10。
`/dy/<distanceY>`		纵轴边距，单位:像素(px)，默认值为10。

请求报文

请求语法

GET <imageDownloadURI>?<接口规格> HTTP/1.1
Host: <imageDownloadHost>

头部信息

头部名称	必填	说明
Host	是	下载服务器域名，可为七牛三级域名或自定义二级域名，参考七牛自定义域名绑定流程。

响应报文

响应语法

HTTP/1.1 200 OK
Content-Type: <imageMimeType>

<imageBinaryData>

头部信息

头部名称	必填	说明
Content-Type	是	MIME类型，成功时为图片的MIME类型，失败时为`application/json`。
Cache-Control		缓存控制，失败时为`no-store`，不缓存。

响应内容

如果请求成功，返回图片的二进制数据。
如果请求失败，返回包含如右内容的JSON字符串（已格式化，便于阅读）：

{
    "code":     <httpCode  int>, 
    "error":   "<errMsg    string>",
}

字段名称	必填	说明
code	是	HTTP状态码，请参考响应状态。
error	是	与HTTP状态码对应的消息文本

响应状态码

HTTP状态码	含义
200	添加水印成功
400	请求报文格式错误
404	资源不存在
599	服务端操作失败。如遇此错误，请将完整错误信息（包括所有HTTP响应头部）提交工单错误日志给我们。

文字平铺水印

接口规格

watermark/4
         /text/<encodedText>
         /font/<encodedFontName>
         /fontsize/<fontSize>
         /fill/<encodedTextColor>
         /dissolve/<dissolve>
         /rotate/<rotate>
         /uw/<unitW>
         /uh/<unitH>
         /resize/<resize>

参数名称	必填	说明
`/text/<encodedText>`	是	水印文字内容（经过URL安全的Base64编码）
`/font/<encodedFontName>`		水印文字字体（经过URL安全的Base64编码），缺省为黑体，详见支持字体列表注意：中文水印必须指定中文字体。
`/fontsize/<fontSize>`		水印文字大小，单位: 缇，等于1/20磅，[1, 10000), 默认值是240缇，参考DPI为72。
`/fill/<encodedTextColor>`		水印文字颜色，RGB格式，可以是颜色名称（比如red）或十六进制（比如#FF0000），参考RGB颜色编码表，缺省为黑色. （经过URL安全的Base64编码）
`/dissolve/<dissolve>`		透明度，取值范围1-100，缺省值100（完全不透明）
`/rotate/<rotate>`		水印文字旋转角度，[-180, 180]，默认为0。
`/uw/<unitW>`		水印文字填充单元宽度，默认值为100。
`/uh/<unitH>`		水印文字填充单元高度，默认值为100。
`/resize/<resize>`		水印文字填充单元缩放比例，[0.1，10]，默认为1（不缩放）。

使用示例

水印文本：七牛云存储
水印文本字体：宋体
水印文本字体大小：400
水印文本颜色：gray
水印文本透明度：50% (dissolve=50)
水印文字旋转角度: 30
水印文字填充单元宽度：180
水印文字填充单元高度：180
水印文字填充单元缩放比例： 1

文字水印

右键拷贝图片链接查看水印生成的具体规格参数。

混合水印

本接口用于同时在一个原图上打多个不同类型的水印。

接口规格

注意1： 接口规格不含任何空格与换行符。

注意2： 省略号表示可以附加多个规格参数。

注意3： 图片水印与文字水印的规格可以混写，按给定顺序处理。

watermark/3
         /text/<textWaterMarkParams1>
         /image/<imageWaterMarkParams1>
         /image/<imageWaterMarkParams2>
         /text/<textWaterMarkParams2>
         ...

参数名称	必填	说明
`/image/<imageWaterMarkParams>`		参考图片水印参数
`/text/<textWaterMarkParams>`		参考文字水印参数

请求报文

请求语法

GET <imageDownloadURI>?<接口规格> HTTP/1.1
Host: <imageDownloadHost>

请求头部

头部名称	必填	说明
Host	是	下载服务器域名，可为七牛三级域名或自定义二级域名，参考七牛自定义域名绑定流程。

响应报文

响应语法

HTTP/1.1 200 OK
Content-Type: <imageMimeType>

<imageBinaryData>

头部信息

头部名称	必填	说明
Content-Type	是	MIME类型，成功时为图片的MIME类型，失败时为`application/json`。
Cache-Control		缓存控制，失败时为`no-store`，不缓存。

响应内容

如果请求成功，返回图片的二进制数据。
如果请求失败，返回包含如下内容的JSON字符串（已格式化，便于阅读）：

{
    "code":     <httpCode  int>, 
    "error":   "<errMsg    string>",
}

字段名称	必填	说明
code	是	HTTP状态码，请参考响应状态
error	是	与HTTP状态码对应的消息文本

响应状态码

HTTP状态码	含义
200	添加水印成功
400	请求报文格式错误
404	资源不存在
599	服务端操作失败。如遇此错误，请将完整错误信息（包括所有HTTP响应头部）提交工单给我们。

注意：

watermark生成的图片会被七牛云存储缓存以加速下载，但不会持久化。需要持久化的缩略图，请参考持久化数据处理和saveas。
使用qrsctl工具，给图片下载URL中的水印规格添加别名，使得URL更加友好。

qrsctl login <email> <password>

qrsctl style <bucket> watermarked.jpg watermark/2/text/<encodedText>

qrsctl separator <bucket> -

此时，如下两个URL等价:

http://<Domain>/<Key>?watermark/2/text/<encodedText>

http://<Domain>/<Key>-watermarked.jpg

设置原图保护，仅限使用缩略图样式别名的友好URL形式来访问目标图片。

设置原图保护后，原图不能访问：

http://<Domain>/<Key>

同时也禁止根据图像处理API对原图进行参数枚举：

http://<Domain>/<Key>?watermark/2/text/<encodedText>

此时只能访问指定规格的图片资源：

http://<Domain>/<Key>-watermarked.jpg

使用示例

如果需要对原始图片加上多个混合水印，可以通过多个水印 Params 组合（image/imageWaterMarkParams，/text/textWaterMarkParams）来实现。示例图共添加了6个水印，包含：3个不同的文字水印和3个图片水印。

https://dora-doc.qiniu.com/baidi.png?
	watermark/3
	/image/aHR0cHM6Ly9kb3JhLWRvYy5xaW5pdS5jb20veGlhb2ppLnBuZw==/gravity/North/dy/-10/dx/0
	/text/5ZCD6L-H54yr5bGx546L77yM5YW25LuW5qa06I6y55qG6Lev5Lq6/gravity/SouthWest/dx/10/dy/180/fontsize/500
	/text/5LuF6ZmQN-WkqSAgMjAxOS4wNC4wMS0yMDE5LjA0LjA3/gravity/SouthWest/dx/30/dy/130/fontsize/300
	/image/aHR0cHM6Ly9kb3JhLWRvYy5xaW5pdS5jb20vcXVhbi5wbmc=/gravity/SouthWest/dx/80/dy/30
	/image/aHR0cHM6Ly9kb3JhLWRvYy5xaW5pdS5jb20v5LqM57u056CBLnBuZw==/gravity/SouthEast/dx/10/dy/30
	/text/5omr56CB6aKG5Y-W5LyY5oOg5Yi4/gravity/SouthEast/dx/50/dy/10/fontsize/300/fill/UmVk

混合水印

渐变色水印

接口规格

watermark/7
         /ori/<Orientation>
         /startpos/<StartPosition>
         /stoppos/<StopPosition>
         /startclr/<StartColor>
         /stopclr/<StopColor>

请求参数详解

名称	必填	说明
`/ori/<orientation>`	Y	渐变色方向，1 (自上而下) 2 (自右向左) 3 (自下而上) 4 (自左向右)
`/startpos/<startPosition>`	Y	渐变开始位置。单位像素（px）, 如 10
`/stoppos/<stopPosition>`	Y	渐变结束位置。单位像素（px）, 如 100
`/startclr/<encodedStartColor>`	Y	开始位置颜色及透明度, 如 #FF0000FF（红色不透明) , 需要经过URL安全的Base64编码
`/stopclr/<encodedStopColor>`	Y	结束位置颜色及透明度, 如 #FF000000（红色透明）, 需要经过URL安全的Base64编码

使用示例

渐变色方向：1 (自上而下)
渐变开始位置：0
渐变结束位置：100
开始位置颜色及透明度：#FF0000FF（红色不透明）
结束位置颜色及透明度：#FF000000（红色透明）

[ 图片渐变水印

右键拷贝图片链接查看水印生成的具体规格参数。

界面操作方式

通过调试命令参数的方式，对使用者并不方便。我们提供了图片处理的图形化编辑界面，通过以下方式进入：

1、登录七牛控制台，并点击打开图片处理

图片处理入口

2、选择常用场景，并开始编辑图片处理命令

图片处理编辑

使用示例

水印文本：七牛云存储
水印文本字体：宋体
水印文本字体大小：1000
水印文本颜色：white
水印文本透明度：15% (dissolve=85)
水印文本位置：右下角 (gravity=SouthEast)

文字水印

图片链接的URL:https://dn-odum9helk.qbox.me/22ba099e3f680016ec460d4ba714f93e

以上内容是否对您有帮助？

智能多媒体服务

图片水印处理（watermark）

图片水印

接口规格

水印锚点参数表

请求报文

响应报文

使用示例

文字水印

接口规格

请求报文

响应报文

文字平铺水印

接口规格

使用示例

混合水印

接口规格

请求报文

响应报文

使用示例

渐变色水印

接口规格

请求参数详解

使用示例

界面操作方式

使用示例