智能多媒体服务 > API 文档 > 图片处理 >图片基本处理（imageView2）

图片基本处理（imageView2）

最近更新时间: 2026-08-18 15:23:41

简介

imageView2 提供简单快捷的图片格式转换、缩略、质量变换功能。只需要填写几个参数，即可对图片进行缩略操作，生成各种缩略图。图片处理为收费项，详细的计费说明请参见计费与定价。

功能	说明
[缩略]()	等比缩放、设定目标宽高缩放等多种方式
[格式转换]()	格式转换、GIF 颜色控制
[渐进显示]()	图片渐进显示
[质量变换]()	对图片质量进行调节

限制说明

原图格式支持： psd、jpeg、png、gif、webp、tiff、bmp、avif、heic
同步处理
- 原图支持 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像素

参数说明

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

imageView2/<mode>/w/<LongEdge>
                 /h/<ShortEdge>
                 /format/<Format>
                 /interlace/<Interlace>
                 /q/<Quality>
                 /colors/<colors>
                 /ignore-error/<ignoreError>

参数说明

参数名称	必填	说明
`/mode`	是	定义等比缩放、设定目标宽高缩放的多种不同方式，取值范围：[0,5]的整数，必填项。分为如下几种情况：
		mode=0，使用姿势：`/0/w/<LongEdge>/h/<ShortEdge>` 1、限定缩略图的长边最多为`<LongEdge>`，短边最多为`<ShortEdge>`，进行等比缩放，不裁剪。 2、如果只指定 `w` 参数则表示限定长边（短边自适应），只指定 `h` 参数则表示限定短边（长边自适应）。
		mode=1，使用姿势：`/1/w/<Width>/h/<Height>` 1、限定缩略图的宽最少为`<Width>`，高最少为`<Height>`，进行等比缩放，居中裁剪。 2、转后的缩略图通常恰好是 `<Width>x<Height>` 的大小（有一个边缩放的时候会因为超出矩形框而被裁剪掉多余部分）。 3、如果只指定 `w` 参数或只指定 `h` 参数，代表限定为长宽相等的正方图。
		mode=2，使用姿势：`/2/w/<Width>/h/<Height>` 1、限定缩略图的宽最多为`<Width>`，高最多为`<Height>`，进行等比缩放，不裁剪。 2、如果只指定 `w` 参数则表示限定宽（高自适应），只指定 `h` 参数则表示限定高（宽自适应）。 3、它和模式0类似，区别是mode=2是限定宽和高，mode=0是限定长边和短边。从应用场景来说，模式0适合移动设备上做缩略图，模式2适合PC上做缩略图。
		mode=3，使用姿势：`/3/w/<Width>/h/<Height>` 1、限定缩略图的宽最少为`<Width>`，高最少为`<Height>`，进行等比缩放，不裁剪。 2、如果只指定` w` 参数或只指定` h` 参数，代表长宽限定为同样的值。你可以理解为模式1是模式3的结果再做居中裁剪得到的。
		mode=4，使用姿势：`/4/w/<LongEdge>/h/<ShortEdge>` 1、限定缩略图的长边最少为`<LongEdge>`，短边最少为`<ShortEdge>`，进行等比缩放，不裁剪。 2、如果只指定 `w` 参数或只指定 `h` 参数，表示长边短边限定为同样的值。这个模式很适合在手持设备做图片的全屏查看（把这里的长边短边分别设为手机屏幕的分辨率即可），生成的图片尺寸刚好充满整个屏幕（某一个边可能会超出屏幕）。
		mode=5，使用姿势：`/5/w/<LongEdge>/h/<ShortEdge>` 1、限定缩略图的长边最少为`<LongEdge>`，短边最少为`<ShortEdge>`，进行等比缩放，居中裁剪。 2、如果只指定 `w` 参数或只指定 `h` 参数，表示长边短边限定为同样的值。同上模式4，但超出限定的矩形部分会被裁剪。
`/format/<Format>`	否	图片输出格式 1、取值：`copy`，保持原图格式输出。 2、取值：`jpg`，`gif`，`png`，`webp`等，参考支持转换的图片格式。 3、取值：`heic` 或 `avif `，属于图片高级压缩格式，按照图片高级压缩收费。注意： ● 必须指定`mode`参数，否则不生效。 ● 当原图为`heic` 或 `avif` 时，设置`format/copy` 会保持原图格式不变，且不按照图片高级压缩收费；如果不指定 format 参数，将会输出`jpeg` 。
`/colors/<colors>`	否	控制图片颜色数量 ● 源图片为 `GIF` 时，控制输出 GIF 中不同颜色的数量，取值可为2、4、8、16、32、64、128、256，不使用该参数时的默认值为128。 ● 输出图片为 `PNG` 时，控制输出 PNG 中不同颜色的数量，取值可为2、4、8、16、32、64、128、256，不使用该参数时默认关闭。注意： ● 必须指定`mode`参数，否则不生效。 ● 如果只设置图片颜色数量，不做其他缩放处理，建议使用图片高级处理-格式转换
`/interlace/<Interlace>`	否	是否支持渐进显示取值范围：`1` 支持渐进显示，`0`不支持渐进显示(默认为0)。适用目标格式：`jpg` 效果：网速慢时，图片显示由模糊到清晰。新图的输出格式，必须指定`mode`参数，否则不生效。注意： ● 必须指定`mode`参数，否则不生效。 ● 如果只设置渐渐显示，不做其他缩放处理，建议使用图片高级处理-渐进显示
`/q/<Quality>`	否	新图的图片质量 ● 取值范围是[1, 100] ● 输入是 `jpeg`，且不强制指定质量条件下，七牛会根据原图质量算出一个修正值，取修正值和指定值中的小值。注意： ● 必须指定`mode`参数，否则不生效。 ● 指定值后面可以增加 `!`，表示强制使用指定值，如`100!`。 ● heic：默认值35 ● avif：默认值50 ● 其他格式：默认值75 ● 如果只设置图片质量，不做其他缩放处理，建议使用图片高级处理-质量变换
`/ignore-error/<ignoreError>`	否	设置该参数，取值为1，针对以下场景的处理失败，会直接返回源文件或原输入，而不是报错： 1. 图片兼容性问题，导致的处理失败 2. 触发同步/持久化处理的输入输出限制，如格式、文件大小、宽、高、总像素、帧数，导致的处理失败注意： ● 不设置此参数，处理失败时返回错误信息； ● 当输入文件超过1GB，设置此参数不生效，处理失败时返回错误信息； ● 设置 ignore-error/1 生效后，不会计费。
`/strip`	否	去除所有元信息
`/meta-keep-list/<metaKeepList>`	否	保留指定的元信息，参数格式为 `urlsafebase64("k1,k2,k3")`，当前只支持部分 exif 子标签

注意：

所有模式都可以只指定w参数或只指定h参数，并获得合理结果。在w、h为限定最大值时，未指定某参数等价于将该参数设置为无穷大（自适应）；在w、h为限定最小值时，未指定参数等于给定的参数，也就限定的矩形是正方形。
新图的宽/高/长边/短边，不会比原图大，即本接口总是 缩小图片。
如果原图带有 EXIF 信息且包含 Orientation 字段且不能被识别出来，imageView2 默认根据此字段的值进行自动旋转修正。
当一张含有透明区域的图片，转换成不支持透明的格式jpg,bmp等时，透明区域填充白色。
<Quality>修正值算法：
- 原图 quality <= 90：min[90, 原图quality*sqrt（原图长宽乘积/结果图片长宽乘积）]
- 原图 quality > 90： 原图quality*sqrt（原图长宽乘积/结果图片长宽乘积)

示例

原图

裁剪正中部分，等比缩小生成200x200缩略图：

https://dora-doc.qiniu.com/gogopher.jpg?imageView2/1/w/200/h/200

查看效果图

宽度固定为200px，高度等比缩小，生成200x133缩略图：
```
https://dora-doc.qiniu.com/gogopher.jpg?imageView2/2/w/200
```
高度固定为200px，宽度等比缩小，生成300x200缩略图：
```
https://dora-doc.qiniu.com/gogopher.jpg?imageView2/2/h/200
```

渐进显示图片：

https://dora-doc.qiniu.com/gogopher.jpg?imageView2/1/w/200/h/200/interlace/1

查看效果图

设置图片质量为55：

https://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageView2/1/w/200/h/200/q/55

查看效果图

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

操作方式

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

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