imageMogr2 提供一系列高级图片处理功能，包括格式转换、缩放、裁剪、旋转等。imageMogr2 接口可支持处理的原图片格式有 psd、jpeg、png、gif、webp、tiff、bmp。(webp不支持动图)

注意

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

输出为gif的处理一般处理时间比较长，建议优先使用异步处理。

接口规格

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

imageMogr2/auto-orient

/thumbnail/

/strip

/gravity/

/crop/

/rotate/

/format/

/blur/x

/interlace/

/background/

/quality/

/sharpen/

/size-limit/

/ignore-error/参数名称

必填

说明

auto-orient

建议放在首位，根据原图EXIF信息自动旋正，便于后续处理。

thumbnail

参看缩放操作参数表，默认为不缩放。

strip

去除图片中的元信息。去除的信息有：bKGD、cHRM、EXIF、gAMA、iCCP、iTXt、sRGB、tEXt、zCCP、zTXt、date

gravity

参看图片处理重心参数表，目前在imageMogr2中只影响其后的裁剪偏移参数，默认为左上角(NorthWest)。

crop

参看裁剪操作参数表，默认为不裁剪。

rotate

旋转角度，取值范围为1-360，默认为不旋转。

format

图片格式。支持jpg、gif、png、webp等，默认为原图格式，参看支持输出的图片格式。

blur

高斯模糊参数。radius是模糊半径，取值范围为1-50。sigma是正态分布的标准差，必须大于0。图片格式为gif时，不支持该参数。

interlace

是否支持渐进显示。取值1支持渐进显示，取值0不支持渐进显示(默认为0)。适用jpg目标格式，网速慢时，图片显示由模糊到清晰。

background

背景填充颜色，可以是颜色名称(比如red)或十六进制颜色(比如#FF0000)的URL安全的Base64编码。我们支持的颜色名称有transparent(#00000000)、none(#00000000)、white(#FFFFFF)、black(#000000)、red(#FF0000)、orange(#FFA500)、yellow(#FFFF00)、green(#008000)、blue(#0000FF)、purple(#800080)、gray(#7E7E7E)、pink(#FFC0CB)，其中none与transparent均为透明背景色，另外十六进制颜色不区分大小写，具体颜色请参考颜色编码表。缺省背景色为white(#FFFFFF)。

quality

新图的图片质量。取值范围为1-100，默认75。七牛会根据原图质量算出一个修正值，取修正值和指定值中的小值。

注意：

1.指定值后面可以增加 !，表示强制使用指定值，如：100!。

2.支持图片类型：jpg。

sharpen

图片是否锐化，当设置值为1时打开锐化效果。

size-limit

限制图片转换后的大小，支持以兆字节和千字节为单位的图片。

1.仅对于jpg格式的图片，可以用于限制图片转换后的大小，支持魔法变量$(fsize)表示原图大小。如：http://developer.qiniu.com/resource/Ship.jpg?imageMogr2/size-limit/$(fsize)。

2.对于所有图片格式，若在尾部加上!，表示用转换后的图片大小与原图大小做比较，如果转换后的图片比原图小，则返回转换后的图片，否则返回原图。如：http://developer.qiniu.com/resource/Ship.jpg?imageMogr2/size-limit/15k!。这个主要用于保证返回的图片不会比原图大。

注意： 需要根据图片实际大小设置合理的sizeLimit大小。

ignore-error

取值为 1 时，则处理失败时返回原图；取值为 0 时，则处理失败时返回错误信息。默认值为 0。

修正值算法：

原图quality <= 90: min[90, 原图quality*sqrt(原图长宽乘积/结果图片长宽乘积)]

原图quality > 90: 原图quality*sqrt(原图长宽乘积/结果图片长宽乘积)

注意:

处理后的图片w和h参数不能超过9999像素，总像素不得超过24999999(2500w-1)像素。

处理前的图片w和h参数不能超过3万像素，总像素不能超过 2 亿像素。

缩放操作参数表

参数名称

必填

说明

/thumbnail/!p

基于原图的长宽，按指定百分比缩放。Scale取值范围1-999。

/thumbnail/!px

以百分比形式指定目标图片宽度，高度不变。Scale取值范围1-999。

/thumbnail/!xp

以百分比形式指定目标图片高度，宽度不变。Scale取值范围1-999。

/thumbnail/x

指定目标图片宽度，高度等比缩放，Width取值范围1-9999。

/thumbnail/x

指定目标图片高度，宽度等比缩放，Height取值范围1-9999。

/thumbnail/x

等比缩放，比例值为宽缩放比和高缩放比的较小值，Width 和 Height 取值范围1-9999。

注意： 宽缩放比：目标宽/原图宽   高缩放比：目标高/原图高

/thumbnail/!xr

等比缩放，比例值为宽缩放比和高缩放比的较大值，Width 和 Height 取值范围1-9999。

注意： 宽缩放比：目标宽/原图宽   高缩放比：目标高/原图高

/thumbnail/x!

按指定宽高值强行缩略，可能导致目标图片变形，width和height取值范围1-9999。

/thumbnail/x>

等比缩小，比例值为宽缩放比和高缩放比的较小值。如果目标宽和高都大于原图宽和高，则不变，Width 和 Height 取值范围1-9999。

注意： 宽缩放比：目标宽/原图宽   高缩放比：目标高/原图高;

/thumbnail/x<

等比放大，比例值为宽缩放比和高缩放比的较小值。如果目标宽(高)小于原图宽(高)，则不变，Width 和 Height 取值范围1-9999。

注意： 宽缩放比：目标宽/原图宽   高缩放比：目标高/原图高;

/thumbnail/@

按原图高宽比例等比缩放，缩放后的像素数量不超过指定值，Area取值范围1-24999999。

注意：

处理后的图片 Width 和 Height 范围1-9999，总像素小于2500万像素。

处理前的图片 Width 和 Height 范围1-29999，总像素不超过 2 亿像素。

图片处理重心参数表

在图片高级处理现有的功能中只影响其后的裁剪操作参数表，即裁剪操作以 gravity 为原点开始偏移后，进行裁剪操作。

NorthWest | North | NorthEast

| |

| |

--------------+----------------+--------------

| |

West | Center | East

| |

--------------+----------------+--------------

| |

| |

SouthWest | South | SouthEast

裁剪操作参数表 (cropsize)

参数名称

必填

说明

/crop/x

指定目标图片宽度，高度不变。取值范围为0-10000。

/crop/x

指定目标图片高度，宽度不变。取值范围为0-10000。

/crop/x

同时指定目标图片宽高。取值范围为0-10000。

裁剪偏移参数表 (cropoffset)

参数名称

必填

说明

/crop/!{cropsize}aa

相对于偏移锚点，向右偏移dx个像素，同时向下偏移dy个像素。取值范围不限，小于原图宽高即可。

/crop/!{cropsize}-a

相对于偏移锚点，从指定宽度中减去dx个像素，同时向下偏移dy个像素。取值范围不限，小于原图宽高即可。

/crop/!{cropsize}a-

相对于偏移锚点，向右偏移dx个像素，同时从指定高度中减去dy个像素。取值范围不限，小于原图宽高即可。

/crop/!{cropsize}--

相对于偏移锚点，从指定宽度中减去dx个像素，同时从指定高度中减去dy个像素。取值范围不限，小于原图宽高即可。

示例

/crop/!300x400a10a10 表示从源图坐标为 x:10,y:10 处截取 300x400 的子图片。

/crop/!300x400-10a10 表示从源图坐标为 x:0,y:10 处截取 290x400 的子图片。

注意

必须同时指定横轴偏移和纵轴偏移。

计算偏移值会受到位置偏移指示符 /gravity/ 的影响。默认为相对于左上角 NorthWest 计算偏移值，参考图片处理重心参数表。

转义说明

部分参数以 ! 开头，表示参数将被转义。为便于阅读，我们采用特殊转义方法，如下所示：

p => % (percent)

r => ^ (reverse)

a => + (add)

即 !50x50r 实际代表 50x50^ 这样一个字符串。而 !50x50 实际代表 50x50 这样一个字符串(该字符串并不需要转义)。 中的 OffsetGeometry 部分可以省略，默认为 +0+0。即 /crop/50x50 等价于 /crop/!50x50a0a0，执行 -crop 50x50+0+0 语义。

请求报文

请求语法

GET ? HTTP/1.1

Host:

头部信息

头部名称

必填

说明

Host

是

下载服务器域名，可为七牛三级域名或自定义二级域名，参考七牛自定义域名绑定流程。

响应报文

响应语法

HTTP/1.1 200 OK

Content-Type:

头部信息

头部名称

必填

说明

Content-Type

是

MIME类型，成功时为图片的MIME类型，失败时为application/json。

Cache-Control

缓存控制，失败时为no-store，不缓存。

响应内容

如果请求成功，返回图片的二进制数据。

如果请求失败，返回包含如下内容的 JSON 字符串(已格式化，便于阅读)：

{

"code": ,

"error": "",

}字段名称

必填

说明

code

是

HTTP状态码，请参考响应状态码。

error

是

与HTTP状态码对应的消息文本。

响应状态码

HTTP状态码

含义

200

缩放成功。

400

请求报文格式错误。

404

资源不存在。

599

服务端操作失败。如遇此错误，请将完整错误信息(包括所有的HTTP响应头部)提交工单 给我们。

注意

imageMogr2生成的图片会被七牛云存储缓存以加速下载，但不会持久化。需要持久化的缩略图，请参考持久化数据处理 (pfop)和处理结果另存 (saveas)。

auto-orient 参数是和图像处理顺序相关的，一般建议放在首位(根据原图EXIF信息自动旋正)。

thumbnail 和 crop 之间的操作可以链式处理，即可以先对图进行缩略再裁剪，或者先裁剪再缩略。

gravity 只会使其后的裁剪偏移 cropoffset 受到影响，建议放在 /crop 参数之前。

当处理多帧 gif 图片时，可能处理所需的时间较长并且输出的图片体积较大。如果您有多张多帧 gif 图片需要处理，可在图片上传完成后异步进行预转，这样不必在初次访问时进行图片处理，访问速度更快。请参考预转持久化处理 (persistentOps)。

当一张含有透明区域的图片，转换成不支持透明区域的图片格式 jpg、bmp 等时，透明区域填充白色。

界面操作方式

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

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

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

实时示例

缩放

1. 生成 480x320 缩略图

等比缩小 75%：

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/thumbnail/!75p

按原宽度 75% 等比缩小：

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/thumbnail/!75px

按原高度 75% 等比缩小：

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/thumbnail/!x75p

2. 生成 700x467 放大图

指定新宽度为 700px：

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/thumbnail/700x

指定新高度为 467px：

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/thumbnail/x467

3. 限定长边，生成不超过 300x300 的缩略图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/thumbnail/300x300

4. 限定短边，生成不小于 200x200 的缩略图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/thumbnail/!200x200r

5. 强制生成 200x300 的缩略图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/thumbnail/200x300!

6. 原图大于指定长宽矩形，按长边自动缩小为 200x133 缩略图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/thumbnail/200x300>

7. 原图小于指定长宽矩形，按长边自动拉伸为 700x467 放大图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/thumbnail/700x600<

8. 生成图的像素总数小于指定值

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/thumbnail/350000@

裁剪

1. 生成 300x427 裁剪图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/crop/300x

2. 生成 640x200 裁剪图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/crop/x200

3. 生成 300x300 裁剪图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/crop/300x300

4. 生成 300x300 裁剪图，偏移距离 30x100

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/crop/!300x300a30a100

5. 生成 300x200 裁剪图，偏移距离 30x0

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/crop/!300x300a30-100

6. 生成 270x300 裁剪图，偏移距离 0x100

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/crop/!300x300-30a100

7. 生成 270x200 裁剪图，偏移距离 0x0

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/crop/!300x300-30-100

8. 锚点在左上角 (NorthWest)，生成 300x300 裁剪图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/gravity/NorthWest/crop/300x300

9. 锚点在正上方 (North)，生成 300x300 裁剪图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/gravity/North/crop/300x300

10. 锚点在右上角 (NorthEast)，生成 300x300 裁剪图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/gravity/NorthEast/crop/300x300

11. 锚点在正左方 (West)，生成 300x300 裁剪图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/gravity/West/crop/300x300

12. 锚点在正中 (Center)，生成 300x300 裁剪图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/gravity/Center/crop/300x300

13. 锚点在正右方 (East)，生成 300x300 裁剪图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/gravity/East/crop/300x300

14. 锚点在左下角 (SouthWest)，生成 300x300 裁剪图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/gravity/SouthWest/crop/300x300

15. 锚点在正下方 (South)，生成 300x300 裁剪图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/gravity/South/crop/300x300

16. 锚点在右下角 (SouthEast)，生成 300x300 裁剪图

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/gravity/SouthEast/crop/300x300

旋转

1. 顺时针旋转 45 度：

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/rotate/45

2. 旋转并添加背景色

http://qiniuphotos.qiniudn.com/gogopher.jpg?imageMogr/v2/auto-orient/thumbnail/!256x256r/gravity/center/crop/!256x256/blur/3x9/quality/80/rotate/45/background/b3Jhbmdl

高斯模糊

半径为 3，Sigma 值为 5：

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/blur/3x5

渐进显示

渐进显示图片：

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageMogr2/thumbnail/300x300/interlace/1

##保存图片

可以实时保存图片到指定空间，在上述url的基础上，加上|saveas/encoded(saved_bucket:saved_key)参数。

1. 原资源是一个名为 Ship.jpg 的图片：

http://7xvilo.com1.z0.glb.clouddn.com/Ship.jpg

2. 将图片做缩略处理：

http://7xvilo.com1.z0.glb.clouddn.com/Ship.jpg?imageMogr2/thumbnail/200x200!

3. 对上述云处理结果进行持久化保存：

#另存操作的目标空间与资源名

entryURI = "qiniu-developer:Ship-thumb-200x200.jpg"

#编码结果

encodedEntryURI = "cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAweDIwMC5qcGc="

#需要签名的部分

signingStr = "7xvilo.com1.z0.glb.clouddn.com/Ship.jpg?imageMogr2/thumbnail/200x200!|saveas/cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAweDIwMC5qcGc="

＃签名算法

import hmac

import hashlib

import base64

str = hmac.new('m6TAzSGQUIU2y5G4F9iLzBh7aDz25rYkj8J....','7xvilo.com1.z0.glb.clouddn.com/Ship.jpg?imageMogr2/thumbnail/200x200!|saveas/cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAweDIwMC5qcGc=',hashlib.sha1).digest().encode('base64').rstrip()

print str

#签名结果

sign = "bcgojLbLKTsTlhm3XFMYq0cn3lW2G3NAu.....:iRukarshohgP1ZVSOPp2U6nxhok="

##注意 其中m6TAzSGQUIU2y5G4F9iLzBh7aDz25rYkj8J....指的是sk,bcgojLbLKTsTlhm3XFMYq0cn3lW2G3NAu.....指的是ak,ak,sk在个人面板，密钥管理处获得。

4. 最终得到的完整下载 URL：

http://7xvilo.com1.z0.glb.clouddn.com/Ship.jpg?imageMogr2/thumbnail/200x200!|saveas/cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAweDIwMC5qcGc=/sign/bcgojLbLKTsTlhm3XFMYq0cn3lW2G3NAuJYXZDDf:iRukarshohgP1ZVSOPp2U6nxhok=

5. 保存转码后资源可通过如下 URL 访问：

http://7xvilo.com1.z0.glb.clouddn.com/Ship-thumb-200x200.jpg

异步实例

触发持久化

以Python Sdk为例，本例将空间名为bucket_name中的图片key缩略为长200宽200的图片，并且保存到目标Bucket_Name,且文件名为自定义文件key。

注意:

其他语言 Sdk 可在官方 Sdks下载，可以通过查看 Sdk 使用指南中触发持久化使用。

from qiniu import Auth, PersistentFop, build_op, op_save, urlsafe_base64_encode

#对已经上传到七牛的图片发起异步缩略操作

#access_key，secret_key在个人面板的密钥管理处获得，非个人账号密码

access_key = '...'

secret_key = '...'

q = Auth(access_key, secret_key)

#要缩略的文件所在的空间和文件名。

bucket_name = '...'

key = '...'

#pipeline是使用的队列名称,不设置代表不使用私有队列，使用公有队列。

pipeline = '...'

#要进行缩略的操作。

fops = 'imageMogr2/thumbnail/200x200!'

#可以对缩略后的文件进行使用saveas参数自定义命名，当然也可以不指定文件会默认命名并保存在当前空间

saveas_key = urlsafe_base64_encode('目标Bucket_Name:自定义文件key')

fops = fops+'|saveas/'+saveas_key

pfop = PersistentFop(q, bucket_name, pipeline)

ops = []

ops.append(fops)

ret, info = pfop.execute(key, ops, 1)

print(info)

assert ret['persistentId'] is not None

预转持久化

以Python Sdk为例，本例中将上传的图片缩略为长200宽200的图片，缩略图保存到目标Bucket_Name,且文件名为自定义文件key，原图保存到bucket_name空间，且文件名为key。

注意:

其他语言 Sdk 可在官方 Sdks下载，可以通过查看 Sdk 使用指南中预转持久化使用。

from qiniu import Auth, put_file, etag, urlsafe_base64_encode

import qiniu.config

#access_key，secret_key在个人面板的密钥管理处获得，非个人账号密码

access_key = '...'

secret_key = '...'

# 初始化Auth状态

q = Auth(access_key, secret_key)

# 你要测试的空间， 并且这个文件名key在你空间中存在

bucket_name = '...'

key = '...'

# 是使用的队列名称,不设置代表不使用私有队列，使用公有队列。

pipeline = '...'

# 设置图片缩略参数

fops = 'imageMogr2/thumbnail/200x200!'

# 通过添加'|saveas'参数，指定处理后的文件保存的bucket和key，不指定默认保存在当前空间，bucket_saved为目标bucket，bucket_saved为目标key

saveas_key = urlsafe_base64_encode('目标Bucket_Name:自定义文件key')#

fops = fops+'|saveas/'+saveas_key

# 在上传策略中指定fobs和pipeline

policy={

'persistentOps':fops,

'persistentPipeline':pipeline

}

token = q.upload_token(bucket_name, key, 3600, policy)

# 图片所在的本地路径

localfile = '...'

ret, info = put_file(token, key, localfile)

print(info)

assert ret['key'] == key

assert ret['hash'] == etag(localfile)