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

图片水印处理（watermark）

最近更新时间: 2025-02-19 14:07:18

简介

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

使用限制

原图格式支持： psd、jpeg、png、gif、webp、tiff、bmp、avif、heic
- 输入为 webp动图、 gif动图 时，不适用于watermark/4 接口
同步处理
- 原图只支持 20MB 以内的图片
- 处理前动图帧数限制：webp动图 最大帧数为50，gif 最大帧数为 200
- 处理前体积限制：图片 w 和h不能超过3万像素，总像素不能超过1.5亿像素
- 处理后体积限制：图片w和h 不能超过9999像素，总像素不得超过2500w 像素。以下情况特别说明：
  - 输出为 avif 时，图片 w和h 不能超过9999像素，总像素不能超过768w像素
  - 输出为 webp静图 时，图片 w 和 h 不能超过16383像素，总像素不得超过2500w 像素
  - 仅限 输入为webp动图格式，输出webp动图/gif动图时，图片 w 和 h 不能超过999像素，总像素（宽x高x帧数）不能超过3150万像素
持久化处理
- 原图只支持 512MB 以内的图片
- 处理前动图帧数限制：gif、webp动图，最大帧数为 500
- 处理前体积限制：图片 w和h 不能超过3万像素，总像素不能超过1.5亿像素
- 处理后体积限制：图片 w和h 不能超过14999像素，总像素不得超过6000w像素。以下情况特别说明：
  - 输出为 heic和 avif 时，图片 w和h 不能超过9999像素，总像素不能超过3072w像素
  - 输出为 webp动图和静图 时，图片 w 和 h 不能超过16383像素，总像素不得超过6000w像素

图片水印

接口规格

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

watermark/1
         /format/<Format>
         /image/<encodedkodocheme>
         /dissolve/<dissolve>
         /gravity/<gravity>
         /dx/<distanceX>
         /dy/<distanceY>
         /ws/<watermarkScale>
         /wst/<watermarkScaleType>
         /ignore-error/<ignoreError>

参数名称	必填	说明
`/format/<Format>`		图片输出格式 1、取值：`heic` 或 `avif` ，属于图片高级压缩格式，按照图片高级压缩收费，当前仅支持持久化处理来使用。 2、取值：`copy`，保持原图格式输出。注意： ● 当原图为`heic` 或 `avif` 时，设置`format/copy` 会保持原图格式不变，且不按照图片高级压缩收费；如果不指定 format 参数，将会输出`jpeg` 。
`/image/<encodedkodocheme>`	是	水印的源路径，目前支持 kodo 资源。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。具体是指水印图片保持原比例，按照自适应原图的类型`wst`，比如默认是按照短边，则水印图片短边=原图短边＊ws。
`/wst/<watermarkScaleType>`		水印图片自适应原图的类型，取值0、1、2、3分别表示为自适应原图的短边、长边、宽、高，默认值为0。例如： 1. 原图大小为250x250，水印图片大小为91x61，如果wst=0、ws=0.1，那么最终水印图片的大小为：37.2x25。 2. 原图大小为250x250，水印图片大小为91x61，如果wst=1、ws=0.1，那么最终水印图片的大小为：25x16.8。
`ignore-error/<ignoreError>`		设置该参数，取值为1，针对以下场景的处理失败，会直接返回源文件或原输入，而不是报错： 1. 图片兼容性问题，导致的处理失败 2. 触发同步/持久化处理的输入输出限制，如格式、文件大小、宽、高、总像素、帧数，导致的处理失败注意： ● 不设置此参数，处理失败时返回错误信息； ● 当输入文件超过1GB，设置此参数不生效，处理失败时返回错误信息。

水印锚点参数表

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

使用示例

水印图片：
- kodocheme = kodo://developer-documents-image/qiniuyun.png
- encodedkodocheme = a29kbzovL2RldmVsb3Blci1kb2N1bWVudHMtaW1hZ2UvcWluaXV5dW4ucG5n
水印透明度: 50% (dissolve=50)
水印位置: 右下角 (gravity=SouthEast)
横向边距: 20px
纵向边距: 20px

水印图片自适应短边比例：0.2

https://dora-doc.qiniu.com/gogopher.jpg?watermark/1/image/a29kbzovL2RldmVsb3Blci1kb2N1bWVudHMtaW1hZ2UvcWluaXV5dW4ucG5n/dissolve/50/gravity/SouthEast/dx/20/dy/20/ws/0.2

图片水印

文字水印

接口规格

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

watermark/2
         /format/<Format>
         /text/<encodedText>
         /font/<encodedFontName>
         /fontsize/<fontSize>
         /fill/<encodedTextColor>
         /dissolve/<dissolve>
         /gravity/<gravity>
         /dx/<distanceX>
         /dy/<distanceY>
         /ignore-error/<ignoreError>

参数名称	必填	说明
`/format/<Format>`		图片输出格式 1、取值：`heic` 或 `avif` ，属于图片高级压缩格式，按照图片高级压缩收费，当前仅支持持久化处理来使用。 2、取值：`copy`，保持原图格式输出。注意： ● 当原图为`heic` 或 `avif` 时，设置`format/copy` 会保持原图格式不变，且不按照图片高级压缩收费；如果不指定 format 参数，将会输出`jpeg` 。
`/text/<encodedText>`	是	水印文字内容（经过URL安全的Base64编码）
`/font/<encodedFontName>`		水印文字字体（经过URL安全的Base64编码），默认为`方正黑体`，详见支持字体列表注意：中文水印必须指定中文字体。
`/fontstyle/<fontStyle>`		水印字体样式（经过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。
`ignore-error/<ignoreError>`		设置该参数，取值为1，针对以下场景的处理失败，会直接返回源文件或原输入，而不是报错： 1. 图片兼容性问题，导致的处理失败 2. 触发同步/持久化处理的输入输出限制，如格式、文件大小、宽、高、总像素、帧数，导致的处理失败注意： ● 不设置此参数，处理失败时返回错误信息； ● 当输入文件超过1GB，设置此参数不生效，处理失败时返回错误信息。

使用示例

水印文本：七牛云
水印文本字体：方正黑体
水印文本字体大小：400

水印文本颜色：gray

https://dora-doc.qiniu.com/gogopher.jpg?watermark/2/text/5LiD54mb5LqR5a2Y5YKo/fontsize/400

文字水印

混合水印

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

接口规格

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

参数名称	必填	说明
`/format/<Format>`		图片输出格式 1、取值：`heic` 或 `avif` ，属于图片高级压缩格式，按照图片高级压缩收费，当前仅支持持久化处理来使用。 2、取值：`copy`，保持原图格式输出。注意： ● 当原图为`heic` 或 `avif` 时，设置`format/copy` 会保持原图格式不变，且不按照图片高级压缩收费；如果不指定 format 参数，将会输出`jpeg` 。
`/image/<imageWaterMarkParams>`		参考图片水印参数
`/text/<textWaterMarkParams>`		参考文字水印参数

注意：

省略号表示可以附加多个规格参数。
图片水印与文字水印的规格可以混写，按给定顺序处理。

使用示例

对原图加上多个混合水印，可以通过多个水印 Params 组合/image/imageWaterMarkParams，/text/textWaterMarkParams 来实现；示例共添加了6个不同图片和文字水印。

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/UmV

混合水印

文字平铺水印

注意： 输入为 webp动图、 gif动图 时，不支持文字平铺水印

接口规格

watermark/4
         /format/<Format>
         /text/<encodedText>
         /font/<encodedFontName>
         /fontsize/<fontSize>
         /fill/<encodedTextColor>
         /dissolve/<dissolve>
         /rotate/<rotate>
         /uw/<unitW>
         /uh/<unitH>
         /resize/<resize>
         /ignore-error/<ignoreError>

参数名称	必填	说明
`/format/<Format>`		图片输出格式 1、取值：`heic` 或 `avif` ，属于图片高级压缩格式，按照图片高级压缩收费，当前仅支持持久化处理来使用。 2、取值：`copy`，保持原图格式输出。注意： ● 当原图为`heic` 或 `avif` 时，设置`format/copy` 会保持原图格式不变，且不按照图片高级压缩收费；如果不指定 format 参数，将会输出`jpeg` 。
`/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，数值为大于0的整数。。
`/uh/<unitH>`		水印文字填充单元高度，默认值为100，数值为大于0的整数。。
`/resize/<resize>`		水印文字填充单元缩放比例，取值范围为[0.1，10]，小数点保留后一位；默认为1，即不缩放。
`ignore-error/<ignoreError>`		设置该参数，取值为1，针对以下场景的处理失败，会直接返回源文件或原输入，而不是报错： 1. 图片兼容性问题，导致的处理失败 2. 触发同步/持久化处理的输入输出限制，如格式、文件大小、宽、高、总像素、帧数，导致的处理失败注意： ● 不设置此参数，处理失败时返回错误信息； ● 当输入文件超过1GB，设置此参数不生效，处理失败时返回错误信息。

使用示例

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

水印文字填充单元缩放比例： 1

https://dora-doc.qiniu.com/gogopher.jpg?watermark/4/text/5LiD54mb5LqR5a2Y5YKo/fontsize/400/fill/Z3JheQ==/dissolve/50/rotate/30/uw/180/uh/180/resize/1

文字水印

渐变色水印

接口规格

watermark/7
         /format/<Format>
         /ori/<Orientation>
         /startpos/<StartPosition>
         /stoppos/<StopPosition>
         /startclr/<StartColor>
         /stopclr/<StopColor>
         /ignore-error/<ignoreError>

请求参数详解

名称	必填	说明
`/format/<Format>`		图片输出格式 1、取值：`heic` 或 `avif` ，属于图片高级压缩格式，按照图片高级压缩收费，当前仅支持持久化处理来使用。 2、取值：`copy`，保持原图格式输出。注意： ● 当原图为`heic` 或 `avif` 时，设置`format/copy` 会保持原图格式不变，且不按照图片高级压缩收费；如果不指定 format 参数，将会输出`jpeg` 。
`/ori/<orientation>`	是	渐变色方向，1 (自上而下) 2 (自右向左) 3 (自下而上) 4 (自左向右)
`/startpos/<startPosition>`	是	渐变开始位置。单位像素（px）, 如 10，数值为大于0的整数。
`/stoppos/<stopPosition>`	是	渐变结束位置。单位像素（px）, 如 100，数值为大于0的整数。注意：渐变结束位置数值必须大于渐变开始位置。
`/startclr/<encodedStartColor>`	是	开始位置颜色的透明度, 如 #FF0000FF（红色不透明) , 需要经过URL安全的Base64编码
`/stopclr/<encodedStopColor>`	是	结束位置颜色的透明度, 如 #FF000000（红色透明）, 需要经过URL安全的Base64编码
`ignore-error/<ignoreError>`		设置该参数，取值为1，针对以下场景的处理失败，会直接返回源文件或原输入，而不是报错： 1. 图片兼容性问题，导致的处理失败 2. 触发同步/持久化处理的输入输出限制，如格式、文件大小、宽、高、总像素、帧数，导致的处理失败注意： ● 不设置此参数，处理失败时返回错误信息； ● 当输入文件超过1GB，设置此参数不生效，处理失败时返回错误信息。

使用示例

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

结束位置颜色及透明度：#FF000000（红色透明）

https://dora-doc.qiniu.com/gogopher.jpg?watermark/7/ori/1/startpos/0/stoppos/100/startclr/I0ZGMDAwMEZG/stopclr/I0ZGMDAwMDAw

图片渐变水印

操作方式

您可以通过同步处理、持久化处理、图片样式设置、CDN中间源处理等方式，对图片进行处理，详情介绍请参见图片处理操作方式。

返回原图示例

加水印时设置 ignore-error/1，即 对特定场景下 的图片处理失败进行兜底，保证图片处理返回原图或原输入，而不是直接报错；一定程度上提高图片处理的可用性，提升用户体验。

示例

简单示例，触发同步输出限制，返回原图：转avif格式的同时加水印，图片 w和h 不能超过9999像素，总像素不能超过768w像素。
```
https://dn-dora-document.qbox.me/pexels-clement.jpg?watermark/2/format/avif/text/5LiD54mb5LqR5a2Y5YKo/fontsize/10000/fill/I0ZGRkZGRg==/ignore-error/1
```
复杂示例，使用管道，返回原输入：如果第一步 缩放 ，处理成功；第二步 转avif格式的同时加水印，触发avif格式的同步输出限制，设置 ignore-error 生效后，会返回原输入（即第一步处理结果）。
```
https://dn-dora-document.qbox.me/pexels-clement.jpg?imageMogr2/thumbnail/4000x6000!/ignore-error/1|watermark/2/format/avif/text/5LiD54mb5LqR5a2Y5YKo/fontsize/10000/fill/I0ZGRkZGRg==/ignore-error/1
```

计费说明

设置 ignore-error/1 生效后，不会计费。

计费示例：管道存在时，比如 A/ignore-error/1|B/ignore-error/1，A处理成功，B处理失败（设置，则A计费，B不计费，结果返回A处理结果。

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