图片基本处理(imageView2)
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)进行转码。
界面操作方式
通过调试命令参数的方式,对使用者并不方便。我们提供了图片处理的图形化编辑界面,通过以下方式进入:
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)