图片处理V2.0
概述
图片处理服务依托对象存储BOS系统对外提供灵活、多样、实时的图片处理服务。用户将原始图片上传到BOS上,通过调用简单的RESTful接口,实现对图片的实时处理,如缩略、裁剪、格式转换、旋转、加文字/图片水印等,处理结果图会通过CDN实时的返回给用户。
在访问速度上,图片处理服务集成了CDN功能,利用遍布在全国的高质量CDN节点,实现图片内容的加速分发,有效降低源站压力。
图片处理服务的架构如下图所示:
-
用户首次发送请求处理流程:
- 用户端首次发送图片处理请求;
- 首次请求,CDN未命中,请求会被直接发送到BOS源站进行处理;
- 根据用户发送的处理参数对图片进行实时处理;
- 处理后的结果图将被缓存到CDN节点上;
- 同时,将结果图返回给用户端。
-
用户端非首次访问图片处理流程:
- 用户端发送图片处理请求;
- 若CDN命中,则直接跳到步骤5;若CDN未命中,则跳到步骤3;
- 请求会被回源到BOS,并根据用户发送的处理参数对图片进行实时处理;
- 处理后的结果图被缓存到CDN节点上;
- 将结果图返回给用户端。
图片处理服务的灵活便捷体现在,您只要通过在原始图片的请求中直接添加处理参数,即可实时得到处理后的结果图。
计费方式
图片服务收费分为三个部分:
- CDN流量 在CDN上会产生请求流量,这些流量将会记录到CDN计费中,请参考CDN产品定价。
- BOS存储空间、请求次数、外网流出流量和CDN回源请求产生的流出流量 存储空间、请求次数、外网流出流量和CDN回源请求产生的流出流量按BOS标准计费。其中,CDN回源请求的图片流出流量,为处理后目标图的流出流量。请参考BOS产品定价。
- 图片处理数据量 BOS 图像处理包括图像基础处理费用和图像高级处理费用。图像基础处理费用是指对存储在 BOS 中的图像进行缩放、旋转、水印、格式变换、裁剪等操作时产生的费用,图像高级处理费用是指对存储在 BOS 中的图像进行 HEIC 压缩,WebP-M6 压缩等高阶操作。图像基础处理、图像高级处理中 HEIC 图像压缩及 WebP-M6 图像压缩服务于 2020 年 6 月 1 日开始正式计费。您可以登录控制台-财务查看用量数据。
使用方式
说明: 本文档介绍的是BOS图片处理V2.0版本,您仍然可以通过BOS图片处理V1.0版本方式来访问BOS图片处理服务,但今后V1.0版本功能将不再更新。
您需要先将原始图片上传到BOS,每个BOS Bucket默认开通图片处理的功能,无需开通,也无需使用特定域名访问。当访问图片URL时,在Querystring中通过x-bce-process参数指定图片处理命令,即可触发BOS图片处理功能。BOS支持通过命令和样式两种方式访问图片服务。
- 命令方式访问格式:
http://${domain}/${objectkey}?x-bce-process=image/${action},${key}_${value}. 样例:http://bucket-A.bj.bcebos.com/sample.jpg?x-bce-process=image/resize,m_fill,w_200,h_300
。 -
样式方式访问格式:
http://${domain}/${objectkey}?x-bce-process=style/${stylename}. 样例:http://bucket-A.bj.bcebos.com/sample.jpg?x-bce-process=style/stylename
。为了提升图片的安全性,尤其是在BOS中进行了处理并公开发布的图片,BOS也支持对指定Bucket内的图片开启原图保护。即开启原图保护后,如果图片获取者未验证被授权的签名,则只能通过样式方式访问处理后的图片,直接访问原图或通过处理参数访问的方式会被拒绝。目前支持在控制台对原图保护功能进行开启或关闭,也支持通过API进行相关操作,并可通过resource字段指定该功能生效范围。
规则与限制
- 支持的原图格式:jpg、png、bmp、webp、heic、gif。
- 支持的目标格式:jpg、png、bmp、webp、heic、gif。
- 支持图片大小不超过20MB,且图片宽高不超过10000px。
- 处理结果输出图片宽高不超过4096px,包括管道和子命令间的中间输出图片。
- 最多可以同时指定4组操作,即4个action。
- 一个action下不可以重复指定同一个参数。
图片处理命令
整体的图片处理命令形式为:x-bce-process=image/${action},${key}_${value},${key}_${value}/${action},${key}_${value},说明如下:
- image:BOS支持多种数据处理形式,均使用x-bce-process参数触发,当使用图片处理时,需要指定此处名字为image。
- action:BOS支持多种图片处理命令,每种图片处理命令称作一种action,比如缩放resize,裁剪crop等。
- key:每种action支持多种具体的处理参数,比如缩放宽度w,高度h等。
- value:处理参数取值。
- 分隔符说明如下:
分隔符名称 | 分隔符 | 两侧顺序 | 说明 |
---|---|---|---|
处理分隔符 | / | 有关 | 多个action之间的分隔符,前后action顺序执行 |
参数分隔符 | , | 无关 | 多处理参数项之间的分隔符 |
值分隔符 | _ | 固定顺序 | 参数名与参数值之间的分隔符 |
下文详细介绍各个action的使用。
缩放
对图片大小进行缩放处理。
action名称:resize
参数 | 取值 | 说明 |
---|---|---|
m | lift,mfit,fill,pad,fixed | 设置缩略类型。非必选,默认lfit。 |
w | 1-4096 | 设置缩略图的宽度,单位px。lfit类型必须设置w或h,fill fixed类型必须同时设置w和h。 |
h | 1-4096 | 设置缩略图的高度,单位px。lfit类型必须设置w或h,fill fixed类型必须同时设置w和h。 |
limit | 0,1 | 设置是否限制图片缩放的尺寸大小不可超过原图大小,0不限制,1限制。非必选,默认0不限制。 |
color | 8位十六进制颜色码 | 指定pad类型下填充颜色,前6位分别表示RGB色,如ffffff;最后2位表示Alpha通道,可省略,省略时表示不透明。非必选,默认黑色。 |
缩略类型详细说明:
- lfit:等比缩放图片,缩放到能放到以w、h为宽高的矩形内的最大缩放图片。
- mfit:等比缩放图片,缩放到能包含住以w、h为宽高的矩形的最小缩放图片。
- fill:mfit基础上,对w、h矩形内的图片部分进行裁剪。
- pad:lfit基础上,对w、h矩形内的非图片空白部分进行指定颜色填充。
- fixed:强制缩放到指定w宽、h高。
示例
- 等比缩放图片,缩放后的图片宽最大200,高最大100.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/resize,m_lfit,w_200,h_100
- 等比缩放图片,缩放后的图片宽最大200,高最大100,并对200*100矩形内图片未占满的部分以红底色填充.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/resize,m_pad,w_200,h_100,color_FF0000
- 等比缩放图片,缩放后的图片宽最小200,高最小100.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/resize,m_mfit,w_200,h_100
- 等比缩放图片,缩放后的图片宽最小200,高最小100,并对超出200*100部分图片进行裁剪。
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/resize,m_fill,w_200,h_100
- 强制缩放宽200,高100.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/resize,m_fixed,w_200,h_100
裁剪
对图片进行矩形裁剪操作。
action名称:crop
参数 | 取值 | 说明 |
---|---|---|
x | 0-图片宽度 | 裁剪左上角起点相对原点的x坐标,非必选,默认0。 |
y | 0-图片高度 | 裁剪左上角起点相对原点的y坐标,非必选,默认0。 |
w | 1-4096 | 裁剪后图片的宽度,如果指定的宽度超过了图片的宽度,则以图片宽度为准裁剪。单位为px。非必选,默认值原始图片宽度。 |
h | 1-4096 | 裁剪后图片的高度,如果指定的高度超过了图片的高度,则以图片高度为准裁剪。单位为px。非必选,默认值原始图片高度。 |
示例
- 对图片以(10,10)坐标为起点,裁剪200*200.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/crop,x_10,y_10,w_200,h_200
内切圆裁剪
以图片中心为圆心,进行内切圆裁剪。
action名称:circle
参数 | 取值 | 说明 |
---|---|---|
r | 0-图片最小边大小的一半 | 以图片中心为圆心,从图片取出的半径为r的圆形区域,r如果超过最小边大小的一半,默认取原圆的最大内切圆。 |
示例
- 以100为半径,进行内切圆裁剪.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/circle,r_100
圆角矩形裁剪
将图片裁剪为圆角矩形。
action名称:rounded-corners
参数 | 取值 | 说明 |
---|---|---|
r | 1-4096 | 设置圆角的半径。如果指定半径r大于原图宽/高,则默认原图宽/高。 |
示例
- 以50为半径,进行圆角矩形裁剪.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/rounded-corners,r_50
旋转
对图片进行一定角度的旋转。
action名称:rotate
参数 | 取值 | 说明 |
---|---|---|
a | -360-360 | 图片旋转角度,正数表示顺时针旋转,负数表示逆时针旋转。 |
示例
- 将图片顺时针旋转30度.
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/rotate,a_30
自适应方向旋转
根据exif信息进行自动旋转。
action名称:auto-orient
参数 | 取值 | 说明 |
---|---|---|
o | 0,1 | 0:按原图默认方向,不自动旋转;1:自适应旋转。 |
格式转换
对图片格式进行转换。
action名称:format
参数 | 取值 | 说明 |
---|---|---|
f | jpg、png、bmp、webp、heic、gif、auto | 指定目标图片的图片格式,如果为值auto则根据请求Header的Accept字段自动选择最优格式。 |
渐进显示
指定图片显示方式。
action名称:interlace
参数 | 取值 | 说明 |
---|---|---|
i | baseline,progressive | baseline:标准式,指图片按照从上到下的扫描方式显示;progressive:渐进式 ,指图片由模糊到清晰渐进显示。progressive 只对jpg、png格式图片有效,若指定其他格式,则默认显示方式仍为baseline。 |
质量变换
对图片质量进行压缩,质量参数对PNG、BMP和GIF格式无效。
action名称:quality
参数 | 取值 | 说明 |
---|---|---|
q | 1-100 | 指定图片的相对质量,假设原图质量为N,则压缩后质量为N * q% |
Q | 1-100 | 指定图片的绝对质量,假设原图质量为N,如果Q < N,则按照Q进行重新编码,否则保持原图质量N不变 |
示例
- 将图片压缩至当前的30%
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/quality,q_30
水印
对一张图片添加水印处理。
action名称:watermark
图片水印参数 | 取值 | 说明 |
---|---|---|
bucket | - | 指定水印图片存储在BOS的Bucket名称,非必选,默认当前bucket。非当前bucket则要求该水印图片有公共读权限。 |
image | - | 指定水印图片存储在BOS的Object名称,需要取url安全的Base64编码后的值。图片水印必选参数。 |
t | 1-100 | 指定图片水印透明度,取值为100时,表示与原始透明度一致。非必选,默认值100。 |
文字水印参数 | 取值 | 说明 |
---|---|---|
text | - | 水印文字内容,需要进行url安全的Base64编码,且编码后最多不能超过200个字符。文字水印必选。 |
size | 1-1024 | 指定水印字体大小,单位px。非必选,默认30。 |
color | 8位十六进制颜色码 | 指定字体颜色,前6位分别表示RGB色,如ffffff;最后2位表示Alpha通道,可省略,省略时表示不透明。非必选,默认000000黑色。 |
type | 支持的字体见下表 | 指定字体的字体类型,取值要求进行url安全的Base64编码。非必选。若指定的字体样式不在当前已支持的fontFamily列表中,则显示效果为默认字体宋体。 |
style | normal、italic、bold | 指定字体样式。normal(常规)italic(斜体)bold(粗体)。非必选,默认normal。只有当字体支持style效果时,才会渲染文字效果。 |
公共水印参数 | 取值 | 说明 |
---|---|---|
g | 1-9 | 指定水印的锚点位置。非必选,默认9。具体含义见下方说明。 |
x | -4096-4096 | 指定水印基于锚点的水平方向距离。非必选,默认值10。 |
y | -4096-4096 | 指定水印基于锚点的垂直方向距离。非必选,默认值10。 |
a | -360-360 | 指定水印旋转角度。正数表示顺时针旋转,负数表示逆时针旋转。非必选,默认值0。 |
说明:
- 目前不支持在一组action中同时指定图片和文字水印,只能指定图片或文字水印一种类型。如果需要指定图片和文字水印,可通过多组action实现。
- 锚点位置说明,将您的原始图片分成如下图所示9个区域,并按照图示位置进行编号,每个区域的锚点位置如图所示:
目前支持的字体类型如下:
字体 | 名称 | base64编码 |
---|---|---|
FZLanTingHei | 方正兰亭黑 | RlpMYW5UaW5nSGVp |
FZFangSong | 方正仿宋 | RlpGYW5nU29uZw== |
FZShuSong | 方正书宋 | RlpTaHVTb25n |
FZKai | 方正楷体 | RlpLYWk= |
FZHei | 方正黑体 | RlpIZWk= |
示例
- 添加图片水印
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/watermark,image_YmNlLWRvY3VtZW50YXRpb24vQk9TL2JjZS5qcGc=,g_9,a_90
- 添加文字水印
https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?x-bce-process=image/watermark,text_aGVsbG8=,g_9,color_ff0000
获取图片信息
此命令用来获取图片信息,如果图片有exif信息则返回包含exif的完整信息,如果图片不包含exif信息,则返回图片的基本信息。
action名称:info
此命令没有参数,以 x-bce-process=image/info 形式访问即可。
图片处理样式
图片样式是指您可以将一些常用的图片处理操作保存为一个别名,即一个样式。这样,一组复杂的操作,利用样式,可以通过一个简洁的访问即可达到相同效果。
样式访问
整体的图片样式访问形式为:x-bce-process=style/${stylename},说明如下:
- style:当使用图片样式访问时,需要指定此处名字为style。
-
stylename:访问的style的名字。
说明,因为BOS的图片处理命令分新旧两种版本,因此,一个图片处理样式所对应的实际图片处理命令可以是新版或旧版。
这里x-bce-process=style/${stylename}的访问方式只能访问新版命令所对应的样式,旧版本命令所对应的样式仍需通过旧版本@!方式访问。
添加/删除样式
目前通过console添加的样式仍为旧版本命令的样式,新版本命令样式功能即将开通。
原图保护
BOS支持通过API实现原图保护功能,并可通过resource字段指定该功能生效范围,具体请参见原图保护。 对于开通原图保护的文件,不允许匿名下载访问该文件,或带自定义图片处理参数访问,只允许使用style样式访问或携带合法签名访问。