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

图片基本处理（imageView2）

最近更新时间：2021-02-01 15:04:28

imageView2 提供简单快捷的图片格式转换、缩略、剪裁功能。只需要填写几个参数，即可对图片进行缩略操作，生成各种缩略图。imageView2接口可支持处理的原图片格式有psd、jpeg、png、gif、webp、tiff、bmp。（webp不支持动图）

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

接口规格

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

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

其中 <mode> 分为如下几种情况：

模式	说明
`/0/w/<LongEdge>/h/<ShortEdge>`	限定缩略图的长边最多为`<LongEdge>`，短边最多为`<ShortEdge>`，进行等比缩放，不裁剪。如果只指定 `w` 参数则表示限定长边（短边自适应），只指定 `h` 参数则表示限定短边（长边自适应）。
`/1/w/<Width>/h/<Height>`	限定缩略图的宽最少为`<Width>`，高最少为`<Height>`，进行等比缩放，居中裁剪。转后的缩略图通常恰好是 `<Width>x<Height>` 的大小（有一个边缩放的时候会因为超出矩形框而被裁剪掉多余部分）。如果只指定 `w` 参数或只指定 `h` 参数，代表限定为长宽相等的正方图。
`/2/w/<Width>/h/<Height>`	限定缩略图的宽最多为`<Width>`，高最多为`<Height>`，进行等比缩放，不裁剪。如果只指定 `w` 参数则表示限定宽（高自适应），只指定 `h` 参数则表示限定高（宽自适应）。它和模式0类似，区别只是限定宽和高，不是限定长边和短边。从应用场景来说，模式0适合移动设备上做缩略图，模式2适合PC上做缩略图。
`/3/w/<Width>/h/<Height>`	限定缩略图的宽最少为`<Width>`，高最少为`<Height>`，进行等比缩放，不裁剪。如果只指定 `w` 参数或只指定 `h` 参数，代表长宽限定为同样的值。你可以理解为模式1是模式3的结果再做居中裁剪得到的。
`/4/w/<LongEdge>/h/<ShortEdge>`	限定缩略图的长边最少为`<LongEdge>`，短边最少为`<ShortEdge>`，进行等比缩放，不裁剪。如果只指定 `w` 参数或只指定 `h` 参数，表示长边短边限定为同样的值。这个模式很适合在手持设备做图片的全屏查看（把这里的长边短边分别设为手机屏幕的分辨率即可），生成的图片尺寸刚好充满整个屏幕（某一个边可能会超出屏幕）。
`/5/w/<LongEdge>/h/<ShortEdge>`	限定缩略图的长边最少为`<LongEdge>`，短边最少为`<ShortEdge>`，进行等比缩放，居中裁剪。如果只指定 `w` 参数或只指定 `h` 参数，表示长边短边限定为同样的值。同上模式4，但超出限定的矩形部分会被裁剪。

注意：

可以仅指定w参数或h参数。
新图的宽/高/长边/短边，不会比原图大，即本接口总是缩小图片。
所有模式都可以只指定w参数或只指定h参数，并获得合理结果。在w、h为限定最大值时，未指定某参数等价于将该参数设置为无穷大（自适应）；在w、h为限定最小值时，未指定参数等于给定的参数，也就限定的矩形是正方形。
处理后的图片w和h参数不能超过9999像素，总像素不得超过24999999（2500w-1）像素。
处理前的图片w和h参数不能超过3万像素，总像素不能超过1.5亿像素。

参数名称	必填	说明
`/format/<Format>`		新图的输出格式取值范围：`jpg`，`gif`，`png`，`webp`等，默认为原图格式。参考支持转换的图片格式。
`/interlace/<Interlace>`		是否支持渐进显示取值范围：`1` 支持渐进显示，`0`不支持渐进显示(默认为0)。适用目标格式：`jpg` 效果：网速慢时，图片显示由模糊到清晰。
`/q/<Quality>`		新图的图片质量取值范围是[1, 100]，默认75。七牛会根据原图质量算出一个修正值，取修正值和指定值中的小值。注意： ● 指定值后面可以增加 `!`，表示强制使用指定值，如`100!`。 ● 支持图片类型：jpg。
`/ignore-error/<ignoreError>`		可选取值：`1` ● 未设置此参数时，正常返回处理结果。 ● 设置了此参数时，若图像处理的结果失败，则返回原图。 ● 设置了此参数时，若图像处理的结果成功，则正常返回处理结果。
`/colors/<colors>`		源图片为 GIF 时，控制输出 GIF 中不同颜色的数量，取值可为2、4、8、16、32、64、128或256，不使用该参数时的默认值为128。

`<Quality>`修正值算法：

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

请求报文

请求语法

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响应头部）提交工单给我们。

注意：

imageView2生成的图片会被七牛云存储缓存以加速下载，但不会持久化。需要持久化的缩略图，请参考持久化数据处理 (pfop)和处理结果另存 (saveas)。
如果原图带有EXIF信息且包含Orientation字段，imageView2默认根据此字段的值进行自动旋转修正。
具备处理动态gif图片的能力。
当一张含有透明区域的图片，转换成不支持透明的格式jpg,bmp等时，透明区域填充白色。
当处理并输出多帧gif图片时，可能处理所需的时间较长并且输出的图片体积较大，建议使用预转持久化处理（persistentOps）或持久化数据处理(pfop)进行转码。

界面操作方式

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

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

图片处理入口

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

图片处理编辑

示例

实时

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

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

查看效果图

宽度固定为200px，高度等比缩小，生成200x133缩略图：

http://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageView2/2/w/200

查看效果图

高度固定为200px，宽度等比缩小，生成300x200缩略图：

http://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageView2/2/h/200

查看效果图

渐进显示图片：

http://dn-odum9helk.qbox.me/resource/gogopher.jpg?imageView2/1/w/200/h/200/interlace/1

查看效果图

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

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

https://dn-odum9helk.qbox.me/resource/Ship.jpg

2. 将图片做缩略处理：

https://dn-odum9helk.qbox.me/resource/Ship.jpg?imageView2/2/w/200/h/200

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

#另存操作的目标空间与资源名
entryURI = "qiniu-developer:Ship-thumb-200.jpg"

#编码结果
encodedEntryURI = "cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAwLmpwZw=="


#需要签名的部分
signingStr = "https://dn-odum9helk.qbox.me/resource/Ship.jpg?imageView2/2/w/200/h/200|saveas/cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAwLmpwZw=="

#签名结果
sign = "bcgojLbLKTsTlhm3XFMYq0cn3lW2G3NAuJYXZDDf:jGo09Pmq5vyG4c-rRb4qF3_dH1g="

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

https://dn-odum9helk.qbox.me/resource/Ship.jpg?imageView2/2/w/200/h/200|saveas/cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAwLmpwZw==/sign/bcgojLbLKTsTlhm3XFMYq0cn3lW2G3NAuJYXZDDf:jGo09Pmq5vyG4c-rRb4qF3_dH1g=

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


https://dn-odum9helk.qbox.me/Ship-thumb-200.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 = 'Bucket_Name'
key = '...'

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

#要进行缩略的操作。
fops = 'imageView2/1/w/200/h/200'

#可以对缩略后的文件进行使用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 = '...'

# 初始化Auth状态
q = Auth(access_key, secret_key)

# 你要保存的空间bucket， 保存的文件名imagename
bucket_name = 'bucket'
key = 'imagename'

# 指定缩略使用的队列名称，不设置代表不使用私有队列，使用公有队列。
pipeline = '...'

# 设置图片缩略参数
fops = 'imageView2/1/w/200/h/200'

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

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)

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

智能多媒体服务

图片基本处理（imageView2）

接口规格

请求报文

请求语法

头部信息

响应报文

响应语法

头部信息

响应内容

响应状态码

界面操作方式

示例

实时

异步