开发者中心 帮助文档 数据处理 官方数据处理 API 手册 图片处理 图片基本处理 (imageView2)
图片基本处理 (imageView2)

imageView2 是 imageView 接口的更新版本,实现略有差异,功能更为丰富。同样,只需要填写几个参数即可对图片进行缩略操作,生成各种缩略图。imageView2接口可支持处理的原图片格式有psdjpegpnggifwebptiffbmp

接口规格

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

imageView2/<mode>/w/<LongEdge>
                 /h/<ShortEdge>
                 /format/<Format>
                 /interlace/<Interlace>
                 /q/<Quality>
                 /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,但超出限定的矩形部分会被裁剪。

注意:

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

<Quality>修正值算法:min[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,不缓存。

响应内容

{
    "code":     <HttpCode  int>, 
    "error":   "<ErrMsg    string>",
}
字段名称 必填 说明
code HTTP状态码,请参考响应状态码
error 与HTTP状态码对应的消息文本

响应状态码

HTTP状态码 含义
200 缩略成功
400 请求报文格式错误
404 资源不存在
599 服务端操作失败。
如遇此错误,请将完整错误信息(包括所有HTTP响应头部)通过邮件发送给我们。

注意:

示例

实时

http://78re52.com1.z0.glb.clouddn.com/resource/gogopher.jpg?imageView2/1/w/200/h/200

查看效果图

http://78re52.com1.z0.glb.clouddn.com/resource/gogopher.jpg?imageView2/2/w/200

查看效果图

http://78re52.com1.z0.glb.clouddn.com/resource/gogopher.jpg?imageView2/2/h/200

查看效果图

http://78re52.com1.z0.glb.clouddn.com/resource/gogopher.jpg?imageView2/1/w/200/h/200/interlace/1

查看效果图

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

http://78re52.com1.z0.glb.clouddn.com/resource/Ship.jpg

2. 将图片做缩略处理:

http://78re52.com1.z0.glb.clouddn.com/resource/Ship.jpg?imageView2/2/w/200/h/200

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

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

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


#需要签名的部分
signingStr = "78re52.com1.z0.glb.clouddn.com/resource/Ship.jpg?imageView2/2/w/200/h/200|saveas/cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAwLmpwZw=="

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

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

http://78re52.com1.z0.glb.clouddn.com/resource/Ship.jpg?imageView2/2/w/200/h/200|saveas/cWluaXUtZGV2ZWxvcGVyOlNoaXAtdGh1bWItMjAwLmpwZw==/sign/bcgojLbLKTsTlhm3XFMYq0cn3lW2G3NAuJYXZDDf:jGo09Pmq5vyG4c-rRb4qF3_dH1g=

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

http://78re52.com1.z0.glb.clouddn.com/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)
提交工单