文档首页

新手指南

API参考手册

SDK

工具

技术文章

图片高级处理（imageMogr）

描述

除了能简便地生成缩略图外，七牛云处理服务还提供一系列高级图片处理功能，包括缩放、裁剪、旋转等等，称为imageMogr。
本接口不再进行功能扩展，建议开发者使用新的imageMogr2接口。

接口规格

建议优先使用第二版imageMogr，其规格如下。

注意：接口规格不含任何空格与换行符，下列内容经过格式化以便阅读。

imageMogr/v2
         /auto-orient
         /thumbnail/<imageSizeGeometry>
         /gravity/<gravityType>
         /crop/<imageSizeAndOffsetGeometry>
         /quality/<imageQuality>
         /rotate/<rotateDegree>
         /format/<destinationImageFormat>

第一版imageMogr兼容保留，其规格是：

imageMogr/auto-orient
         /thumbnail/<imageSizeGeometry>
         /gravity/<gravityType>
         /crop/<imageSizeAndOffsetGeometry>
         /quality/<imageQuality>
         /rotate/<rotateDegree>
         /format/<destinationImageFormat>
参数名称 必填 说明
/auto-orient 根据原图EXIF信息自动旋正，便于后续处理，建议放在首位
/thumbnail/<imageSizeGeometry> 参看缩放操作参数表，缺省为不缩放
/gravity/<gravityType> 参看裁剪锚点参数表，只影响其后的裁剪偏移参数，缺省为左上角（NorthWest）
/crop/<imageSizeAndOffsetGeometry> 参看裁剪操作参数表，缺省为不裁剪
/quality/<imageQuality> 图片质量，取值范围1-100，缺省为85
如原图质量小于指定质量，则使用原图质量
/rotate/<rotateDegree> 旋转角度，取值范围1-360，缺省为不旋转
/format/<destinationImageFormat> 图片格式，支持jpg、gif、png、webp等，缺省为原图格式

缩放操作参数表

参数名称 必填 说明
/thumbnail/!<Scale>p 基于原图大小，按指定百分比缩放。

取值范围0-1000
/thumbnail/!<Scale>px 以百分比形式指定目标图片宽度，高度等比缩放。

取值范围0-1000
/thumbnail/!x<Scale>p 以百分比形式指定目标图片高度，宽度等比缩放。

取值范围0-1000
/thumbnail/<Width>x 指定目标图片宽度，高度等比缩放。

取值范围0-10000
/thumbnail/x<Height> 指定目标图片高度，宽度等比缩放。

取值范围0-10000
/thumbnail/<Width>x<Height> 限定长边，短边自适应缩放，将目标图片限制在指定宽高矩形内。

取值范围0-10000
/thumbnail/!<Width>x<Height>r 限定短边，长边自适应缩放，目标图片会延伸至指定宽高矩形外。

取值范围0-10000
/thumbnail/<Width>x<Height>! 限定目标图片宽高值，忽略原图宽高比例，按照指定宽高值强行缩略，可能导致目标图片变形。

取值范围0-10000
/thumbnail/<Width>x<Height>> 当原图尺寸大于给定的宽度或高度时，按照给定宽高值缩小。

取值范围0-10000
/thumbnail/<Width>x<Height>< 当原图尺寸小于给定的宽度或高度时，按照给定宽高值放大。

取值范围0-10000
/thumbnail/<Area>@ 按原图高宽比例等比缩放，缩放后的像素数量不超过指定值。

取值范围0-100000000

裁剪操作参数表（cropSize）

参数名称 必填 说明
/crop/<Width>x 指定目标图片宽度，高度不变。取值范围0-10000
/crop/x<Height> 指定目标图片高度，宽度不变。取值范围0-10000
/crop/<Width>x<Height> 同时指定目标图片宽高。取值范围0-10000

裁剪偏移参数表（cropOffset）

参数名称 必填 说明
/crop/!{cropSize}a<dx>a<dy> 相对于偏移锚点，向右偏移个像素，同时向下偏移个像素。

取值范围0－1000
/crop/!{cropSize}-<dx>a<dy> 相对于偏移锚点，向下偏移个像素，同时从指定宽度中减去个像素。

取值范围0－1000
/crop/!{cropSize}a<dx>-<dy> 相对于偏移锚点，向右偏移个像素，同时从指定高度中减去个像素。

取值范围0－1000
/crop/!{cropSize}-<dx>-<dy> 相对于偏移锚点，从指定宽度中减去个像素，同时从指定高度中减去个像素。

取值范围0－1000

例如，

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

注意1：必须同时指定横轴偏移和纵轴偏移。
注意2：计算偏移值会受到位置偏移指示符（/gravity/）影响。默认为相对于左上角计算偏移值（即NorthWest），参看裁剪锚点参数表。

裁剪锚点参数表

注意：不区分大小写。

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

转义说明

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

p => % (percent)
r => ^ (reverse)
a => + (add)

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

请求

请求报文格式

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响应头部）通过邮件发送给我们。

附注

  • imageMogr生成的图片会被七牛云存储缓存以加速下载，但不会持久化。需要持久化的缩略图，请参考触发持久化处理和saveas处理。
  • auto-orient 参数是和图像处理顺序相关的，一般建议放在首位（根据原图EXIF信息自动旋正）。
  • thumbnail 和 crop 之间的操作可以链式处理，即可以先对图进行缩略再裁剪，或者先裁剪再缩略。
  • gravity 只会使其后的裁剪偏移(cropOffset)受到影响，建议放在/crop参数之前。
  • 当处理多帧gif图片时，可能处理所需的时间较长并且输出的图片体积较大。如果您有多张多帧gif图片需要处理，可在图片上传完成后异步进行预转，这样不必在初次访问时进行图片处理，访问速度更快。
  • 第一版的imageMogr对gif图片仅反回原图，不做处理。

示例

缩放

  1. 生成480x320缩略图

    等比缩小75%：

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/thumbnail/!75p

    查看效果图

    按原宽度75%等比缩小：

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/thumbnail/!75px

    查看效果图

    按原高度75%等比缩小：

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/thumbnail/!x75p

    查看效果图

  2. 生成700x467放大图

    指定新宽度为700px：

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/thumbnail/700x

    查看效果图

    指定新高度为467px：

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/thumbnail/x467

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/thumbnail/300x300

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/thumbnail/!200x200r

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/thumbnail/200x300!

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/thumbnail/200x300>

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/thumbnail/700x600<

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/thumbnail/350000@

    查看效果图

裁剪

  1. 生成300x427裁剪图

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/crop/300x

    查看效果图

  2. 生成640x200裁剪图

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/crop/x200

    查看效果图

  3. 生成300x300裁剪图

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/crop/300x300

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/crop/!300x300a30a100

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/crop/!300x300a30-100

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/crop/!300x300-30a100

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/crop/!300x300-30-100

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/gravity/NorthWest/crop/300x300

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/gravity/North/crop/300x300

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/gravity/NorthEast/crop/300x300

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/gravity/West/crop/300x300

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/gravity/Center/crop/300x300

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/gravity/East/crop/300x300

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/gravity/SouthWest/crop/300x300

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/gravity/South/crop/300x300

    查看效果图

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

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/gravity/SouthEast/crop/300x300

    查看效果图

旋转

  1. 顺时针旋转45度

    http://developer.qiniu.com/resource/gogopher.jpg?imageMogr2/rotate/45

    查看效果图

内部参考资源

如果有任何问题，请进入 七牛云存储问答社区 或者发送 工单 咨询