图片水印处理(watermark)
七牛云存储提供四种水印接口:图片水印、文字水印,文字平铺水印、混合水印、渐变色水印。
注意: 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(红色透明)
[
右键拷贝图片链接查看水印生成的具体规格参数。
界面操作方式
通过调试命令参数的方式,对使用者并不方便。我们提供了图片处理的图形化编辑界面,通过以下方式进入:
2、 选择常用场景,并开始编辑图片处理命令
使用示例
- 水印文本:
七牛云存储
- 水印文本字体:
宋体
- 水印文本字体大小:
1000
- 水印文本颜色:
white
- 水印文本透明度:15% (
dissolve=85
) - 水印文本位置:右下角 (
gravity=SouthEast
)
图片链接的URL:https://dn-odum9helk.qbox.me/22ba099e3f680016ec460d4ba714f93e