图片处理V1.0

更新时间：2020-07-31

基本概念

图片服务域名

图片服务域名，是指用来访问图片服务的域名。图片服务和普通BOS访问使用的是同一个域名，系统会为Bucket提供一个外网直接发布的官方域名即<bucketname>.region.bcebos.com，用户也可以添加自定义域名。如果Bucket开通了CDN加速发布，则图片服务同步开通CDN加速。如果要开通Bucket的CDN加速发布，可参考CDN加速发布。

说明：Console升级后不影响已有域名的图片处理。前期官方提供的bceimg.com域名主要用于客户试用图片服务，升级后将没有存在意义。对于已开通的bceimg.com域名，可继续使用半年，后续会收回。

访问URL

图片处理服务使用通过URL来访问处理的图片。

URL的构成请参考URL构成。

处理命令

处理命令是指URL中用来转换处理图片的一段命令，形式为“缩写命令_参数值”。通过指定的处理命令参数值，BOS生成并返回另一张转换处理后的图片。如“w_250”，表示将图片的宽度处理为250 px。

执行图片某一类处理方式的命令可称为一组命令，如：执行图片缩放功能为一组命令，执行图片裁剪功能为另一组命令。

分隔符

分隔符是指URL中用来区分一些关键字段的分隔符号。

分隔符名称	分隔符	两侧顺序	说明
处理分隔符	@	固定顺序	Object与处理命令之间的分隔符
参数分隔符	_	固定顺序	参数缩略命令与参数值之间的分隔符
命令分隔符	,	无关	多项处理参数项之间的分隔符
管道分隔符	｜	有关	两组处理命令之间分隔符，管道的参见下述“管道”

管道

如果一个图片，需要多重处理，如先裁剪、后缩略等，则多组操作命令之间，需要以管道“|”连接，执行顺序按管道指定顺序从左至右执行。

例如：http://${userdomain}/${objectkey}@${cropcommands}|${scalecommands}为一个管道，执行顺序为从左到右，左侧命令处理结果将会作为右侧命令的输入。

样式

在对图片进行多重处理时，图片访问的URL会变得复杂冗长，非常不利于管理和阅读。为了让图片URL变得更简洁优雅，或是您想达到隐藏处理参数、保护原图的目的时，您可以使用图片样式功能。

图片样式是指您可以将一些常用的图片处理操作保存为一个别名，即一个样式。这样，一组复杂的操作，利用样式，可以通过一个简洁的URL访问即可达到相同效果。

URL构成

直接显示原图

直接显示原图与普通的域名绑定访问方式一样，URL形式为：http://${userdomain}/${objectkey}

userdomain为用户绑定的域名。
objectkey为存储在BOS上的原图片名称。

样例：http://www.myhost.com/pic.jpg

通过处理命令访问

URL形式为：http://${userdomain}/${objectkey}@${commands}

userdomain为用户绑定的域名。
objectkey为存储在BOS上的原图片名称。
commands为处理命令。

样例：http://bucket-A.bj.bcebos.com/sample.jpg@w_200,q_80

通过样式访问

URL形式为：http://${userdomain}/${objectkey}@!${stylename}

userdomain为用户绑定的域名。
objectkey为存储在BOS上的原图片名称。
stylename为样式。

样例：http://bucket-A.bj.bcebos.com/sample.jpg@!stylename

规则和限制

支持图片规格

支持的原图格式：jpg、png、bmp、webp、gif、tiff。
支持的目标图格式：jpg、png、bmp、webp。
支持图片大小为100MB，且图片长和宽不大于4096 px。

域名绑定规则

一个Bucket绑定的域名数（包括图片域名）不能超过20个，其中图片域名不超过1个。
对于同一个域名，只支持一种绑定方式，在普通域名绑定或图片域名绑定中选择一种，不支持两种方式同时绑定。

请求规则

对于同一组处理命令的参数处理采用无序原则，如 @w_250,h_380,q_90 等同于 @h_380,w_250,q_90。
如果获取的Object名称本身带有@符号时，其后字符全部按照处理命令对待，用户需要提前替换Object 名称中的@符号。
最大支持4个管道。

访问限制

Authorization的签名计算与普通Object处理方式类似，但必须将带参数的图片名称作为一个完整的URL Path用于签名。如带水印的图片签名计算的URL应该为http://test.gz.bcebos.com/IMG_5974.JPG@!shuiyin1?authorization=...，其中参与签名的URL Path为IMG_5974.JPG@!shuiyin1。

图片处理命令

图片缩放、旋转、渐进显示

命令参数

参数名称	缩写命令	类型	取值范围	命令描述	缺省值	是否必选
scale	s	unsigned int	0,1,2	指定缩放方式。 s_0表示无裁剪，等比例缩放； s_1表示拉伸缩放； s_2表示等比例居中裁剪缩放。	0	否
width	w	unsigned int	1～4096	指定目标缩略图的最大宽度单位为px。	-	s_1, s_2时，必选
height	h	unsigned int	1～4096	指定目标缩略图的最大高度单位为px。	-	s_1, s_2时，必选
quality	q	unsigned int	1～100	指定目标图片的绝对质量，只对jpg/jpeg、png、 webp 格式有效。当指定q命令的值大于原图 quality的值时，则默认使用原图quality的值。	原图 quality值。	否
format	f	string	jpg、 png、 webp、 bmp	指定目标图片格式。响应时对应的Content-Type 分别为image/jpeg、image /png、image/webp、image /bmp。	jpg	否
angle	a	int	-360～360	指定图片旋转方式。正数表示顺时针旋转，如`a_60`；负数表示逆时针旋转，如`a_-30`。	0	否
orientation	o	int	0,1,2	根据exif信息进行自动旋转。 `o_0`：按原图默认方向，不自动旋转； `o_1`：先旋转，然后再缩略； `o_2`：先缩略，然后再旋转。	0	否
display	d	string	`baseline` `progressive`	指定图片显示方式。 `baseline`：标准式，指图片按照从上到下的扫描方式显示； `progressive`：渐进式，指图片由模糊到清晰渐进显示。 `progressive` 只对jpg、png格式图片有效，若指定其他格式，则默认显示方式仍为`baseline`。	`baseline`	否
limit	l	unsigned int	0,1	指定是否限制图片缩放的尺寸大小。l_0表示不限制图片缩放的尺寸；l_1表示限制图片缩放尺寸（长和宽）不可超过原图大小。	0	否

注意事项：

当s_0时，即无裁剪等比缩放时：

w和h可以只指定其中一个，图片按指定的参数比例进行缩放。例如，原图尺寸为100 × 200，指定参数为w_50后，图片处理的尺寸为50 × 100；若指定h_50后，图片处理的尺寸为25 × 50。

w和h同时指定时，系统会取“目标宽度/原图宽度”与“目标高度/原图高度”中值小的参数为标准进行等比例缩放。
例如：原图尺寸为400 × 500 ，指定参数为w_100,h_200时，由于“100/400”< “200/500”，则系统按照w_100的比例进行缩放，目标尺寸为100 × 125。

当s_1时，必须同时指定w和h的值，若不同时指定，访问会报错。

当s_2时，必须同时指定w和h的值，若不同时指定，访问会报错。指定w和h后，图片会按照“目标宽度/原图宽度”与“目标高度/原图高度”中值小的参数为标准进行等比例缩放，并对比值较大的另一边进行居中裁剪。

例如：原图尺寸为500 × 1000 ，指定参数为s_2，w_250，h_600时，由于“250/500” < “600/1000”，会以目标宽度250为基准进行等比缩放，同时将高度按照居中裁剪为500。

示例

将图片缩略成高度为200，宽度按比例处理。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@h_200
将图片缩略成宽度为150，高度为200，目标图片绝对质量为60，目标图片格式为png。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@s_1,w_150,h_200,q_60,f_png
将图片进行等比例居中裁剪缩放，缩放宽度为80，高度为100。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@s_2,w_80,h_100
将图片顺时针旋转30度。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@a_30
将图片缩略成宽度为150，高度为100，逆时针旋转90度，并渐进显示。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@s_1,w_150,h_100,a_-90,d_progressive

图片裁剪

命令参数

参数名称	缩写命令	类型	取值范围	命令描述	缺省值	是否必选
crop	c	unsigned int	0,1	指定图片是否执行裁剪功能。 c_1表示对图片进行裁剪； c_0表示不对图片进行裁剪，其他裁剪参数无效。	-	否
offsetX	x	unsigned int	0～4096	指定图片裁剪左上角起点x坐标。	0	否
offsetY	y	unsigned int	0～4096	指定图片裁剪左上角起点y坐标。	0	否
width	w	unsigned int	1～4096	指定图片裁剪的宽度。如果指定的宽度超过了图片的宽度，则以图片宽度为准裁剪。单位为px。	原始图片宽度	否
height	h	unsigned int	1～4096	指定图片裁剪的高度。如果指定的高度超过了图片的高度，则以图片高度为准裁剪。单位为px。	原始图片高度	否

示例

以图片左上角横坐标为100，纵坐标为150为起点进行图片裁剪，裁剪宽度和高度默认为原始图片宽度和高度。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@c_1,x_100,y_150
以图片左上角横、纵坐标均为0为起点进行图片裁剪，裁剪宽度指定为600，裁剪高度指定为600。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@c_1,w_600,h_600
以图片左上角横坐标为100，纵坐标为150为起点进行图片裁剪，裁剪宽度指定为400，裁剪高度指定为200。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@c_1,x_100,y_150,w_400,h_200

图片水印命令

图片水印是指在图片上方插入另一张图片或者文字作为水印，是一种数字信息的保护手段。

目前百度智能云支持图片水印和文字水印两种水印方式。

在了解图片水印命令前，您需要先了解图片锚点的含义。

图片锚点

将您的原始图片分成如下图所示9个区域，并按照图示位置进行编号，每个区域的锚点位置如图所示：

确定水印在原图上的最终位置，您需要确定如下两个因素：

锚点位置；
基于锚点位置，指定在水平和垂直方向上的距离。

图片水印

命令参数

参数名称	缩写命令	类型	取值范围	命令描述	缺省值	是否必选
watermark	wm	unsigned	0，1，2	指定水印方式。 wm_0表示关闭水印功能； wm_1表示图片水印； wm_2表示文字水印。	-	是
key	k	string	-	指定水印图片存储在BOS上的 Object名称，即ObjectKey。如Object存储在文件夹下，则需要包含文件夹路径。该值要求为Base64编码后的值。	-	是
gravity	g	unsigned int	1～9	指定水印的锚点位置。图片锚点的含义请参考图片水印命令。	9	否
gravityX	x	int	-4096～4096	指定水印基于锚点的水平方向距离。	10	否
gravityY	y	int	-4096～4096	指定水印基于锚点的垂直方向距离。	10	否
angle	a	int	-360～360	指定水印图片的旋转角度。正数表示顺时针旋转，如`a_60`；负数表示逆时针旋转，如`a_-30`。	0	否
opacity	o	unsigned int	1～100	指定水印图片的透明度。取值为100时，表示与原始图片透明度一致。	100	否

说明

水印图片要与原始图片存储在BOS的同一个Bucket下。

示例

原图为image.jpg，水印图片为bce-documentation/BOS/bce.jpg(Base64编码后为“YmNlLWRvY3VtZW50YXRpb24vQk9TL2JjZS5qcGc=”)。

在右下角加上图片水印，指定垂直距离为10，透明度为60。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@wm_1,k_YmNlLWRvY3VtZW50YXRpb24vQk9TL2JjZS5qcGc=,y_10,o_60
在左下角加上水印，水平和垂直距离取缺省值，透明度为50，并顺时针旋转90度。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@wm_1,k_YmNlLWRvY3VtZW50YXRpb24vQk9TL2JjZS5qcGc=,g_7,o_50,a_90

文字水印

命令参数

参数名称	缩写命令	类型	取值范围	命令描述	缺省值	是否必选
watermark	wm	unsigned	0，1，2	指定水印方式。 wm_0表示关闭水印功能； wm_1表示图片水印； wm_2表示文字水印。	-	是
text	t	string	-	水印文字内容，需要进行 Base64编码，且编码后最多不能超过80个字符。	-	是
gravity	g	unsigned int	1～9	指定水印的锚点位置。图片锚点的含义请参考图片水印命令。	9	否
gravityX	x	int	-4096～4096	指定水印基于锚点的水平方向距离。	10	否
gravityY	y	int	-4096～4096	指定水印基于锚点的垂直方向距离。	10	否
angle	a	int	-360～360	指定水印图片的旋转角度。正数表示顺时针旋转，如 `a_60`；负数表示逆时针旋转，如 `a_-30`。	0	否
fontSize	sz	unsigned int	1～1024	指定水印字体大小，单位是 px。	30	否
fontColor	fc	string	-	指定字体颜色，为一个8位的16进制字符串，其中每2 位用来表示RGBA中的一项。前6位分别表示RGB色，如 ffffff；最后2位表示Alpha 通道，可省略，省略时表示不透明。例如：000000ff表示黑色不透明字体。	000000	否
fontFamily	ff	string	-	指定字体的字体类型，取值要求进行Base64编码。已支持的字体类型请参见下方列表。	宋体	否
fontStyle	fs	string	normal（常规） italic（斜体） bold（粗体）	指定字体样式。	normal	否

已支持的字体类型：

参数取值	字体类型
MicrosoftYaHei	微软雅黑
FangSong	仿宋
SimHei	黑体
KaiTi	楷体
SimSun	宋体
FZBeiWeiKaiShuJianTi	方正北魏楷书简体
FZBoYaSongJianTi	方正博雅宋简体
FZCuHeiSongJianTi	方正粗黑宋简体
FZLanTingZhongHeiJianTi	方正兰亭中黑简体
FZZhengHei	方正正黑
AvantGarde	AvantGarde
Bookman	Bookman
Courier	Courier
Helvetica	Helvetica
HelveticaNarrow	HelveticaNarrow
NewCenturySchlbk	NewCenturySchlbk
Palatino	Palatino
Times	Times
Symbol	Symbol

说明：

只有当fontFamily支持fontStyle效果时，才会渲染文字效果。
若指定的字体样式不在当前已支持的fontFamily列表中，则显示效果为默认字体宋体。

示例

最简单的文字水印，文字内容为“hello world”。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@wm_2,t_aGVsbG8gd29ybGQ=
文字内容为“hello world”，字体类型为微软雅黑，字体颜色和字体大小取默认值，字体样式为粗体，水印位置在右中，距离锚点水平距离20，垂直距离20，并顺时针旋转30度。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@wm_2,t_aGVsbG8gd29ybGQ=,ff_TWljcm9zb2Z0WWFIZWk=,fs_bold,g_6,x_20,y_20,a_30

图文混合水印

图文混合水印是指将图片水印和文字水印同时打在原始图片上。

由于图片水印和文字水印为两组独立的命令，因此图文混合水印需要用管道实现。

示例

最简单的图文混合水印：图片为bce-documentation/BOS/bce.jpg，文字内容为“hello world”，其余参数均取默认值。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@wm_1,k_YmNlLWRvY3VtZW50YXRpb24vQk9TL2JjZS5qcGc=|wm_2,t_aGVsbG8gd29ybGQ=
图文混合水印：水印图片为bce-documentation/BOS/bce.jpg，位于原图左下角，距离锚点水平距离为,15，垂直距离为20，透明度为50；文字内容为“hello world”，位于正上方，垂直距离为100，字体颜色为淡紫色。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@wm_1,k_YmNlLWRvY3VtZW50YXRpb24vQk9TL2JjZS5qcGc=,g_7,x_15,y_20,o_50|wm_2,t_aGVsbG8gd29ybGQ=,g_2,y_100,fc_aa88aa

获取图片信息

此命令用来获取图片信息，如果图片有exif信息则返回包含exif的完整信息，如果图片不包含exif信息，则返回图片的基本信息。

说明：exif信息记录了数码照片的属性信息和拍摄数据，并非每一张图片都包含exif信息。

返回的exif信息包含但不限于：

dateTime
dateTimeOriginal
dateTimeDigitized
format
gpsLatitude
gpsLatitudeRef
gpsLongitude
gpsLongitudeRef
imageHeight
imageWidth
imageSize
make
model
orientation
resolutionX
resolutionY
resolutionUnit

示例

包含exif信息的图片示例：

https://doc.bce.baidu.com/bce-documentation/BOS/orient.jpg?exif

返回示例：

{
    "dateTime": {
        "value": "2016-08-31T14:57:07Z"
    },
    "dateTimeDigitized": {
        "value": "2016-08-31T14:57:07Z"
    },
    "dateTimeOriginal": {
        "value": "2016-08-31T14:57:07Z"
    },
    "format": {
        "value": "JPEG"
    },
    "gpsLatitude": {
        "value": "40/1,2/1,3675/100"
    },
    "gpsLatitudeRef": {
        "value": "N"
    },
    "gpsLongitude": {
        "value": "116/1,16/1,257/100"
    },
    "gpsLongitudeRef": {
        "value": "E"
    },
    "imageHeight": {
        "value": "2448"
    },
    "imageSize": {
        "value": "1225883"
    },
    "imageWidth": {
        "value": "3264"
    },
    "make": {
        "value": "Apple"
    },
    "model": {
        "value": "iPhone 6"
    },
    "resolutionUnit": {
        "value": "2"
    },
    "resolutionX": {
        "value": "72/1"
    },
    "resolutionY": {
        "value": "72/1"
    }
}

不包含exif信息的图片示例：

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg?exif

返回示例：

{
    "format": {
        "value": "JPEG"
    },
    "imageHeight": {
        "value": "296"
    },
    "imageSize": {
        "value": "63506"
    },
    "imageWidth": {
        "value": "279"
    }
}

管道

管道用来连接实现多条独立命令的执行。

访问方式

管道的处理命令格式为http://${userdomain}/${objectkey}@${commands 1}|${commands 2}，执行顺序按管道指定顺序从左至右执行。

示例

对图片先缩放、旋转，再裁剪。先按宽200的比例等比缩放并顺时针旋转90度，再以左上角横坐标为50，纵坐标为100为起点进行裁剪，裁剪宽度和高度默认为图片宽度和高度。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@w_200,a_30|c_1,x_50,y_100
对图片先裁剪，再缩放。先以左上角横坐标为10，纵坐标为20进行裁剪，裁剪宽度指定为600，高度为300，再按宽200，高200进行拉伸缩放，并指定目标图片的绝对质量为60，目标图片格式为png。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@c_1,x_10,y_20,w_600,h_300|s_1,w_200,h_200,q_60,f_png
图文混合水印：水印图片为bce-documentation/BOS/bce.jpg，位于原图左下角，距离锚点水平距离为,15，垂直距离为20，透明度为50；文字内容为“hello world”，位于正上方，垂直距离为100，字体颜色为淡紫色。

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@wm_1,k_YmNlLWRvY3VtZW50YXRpb24vQk9TL2JjZS5qcGc=,g_7,x_15,y_20,o_50|wm_2,t_aGVsbG8gd29ybGQ=,g_2,y_100,fc_aa88aa

图片样式

访问方式

图片样式的访问方式为：http://${userdomain}/${objectkey}@!${stylename}，其中stylename为您定义的样式名称。

例如：您定义了一个名为“small”的样式，您的域名为51mingxi.com，您的图片名称为image.jpg，则您通过样式访问该图片的URL为http://51mingxi.com/image.jpg@!small。

添加样式

您可以通过控制台进行图片样式的定义，同时还可以在定义的同时实时进行效果预览。

登录BOS控制台，进入您已开通图片服务的Bucket。点击左侧导航“图片服务”后，点击右侧页面中的“样式管理”。
点击“添加样式”，进入添加样式表单页面。您可根据需要，设定该样式的图片处理参数，同时您可在右侧的预览区域实时进行效果预览。

图片样式的设置方式支持“基础设置”和“高级设置”两种。
- 基础设置，您需要在页面上对下方的每一项处理参数进行手动设定。
- 高级设置，您可直接在框中直接输入图片处理命令参数。
创建好样式后，点击“保存”。

缩放说明
- 限定宽度，高度等比例。
  
  您需要输入宽度，缩略时以宽度为基准，将高度等比例缩小。若输入宽度大于原图宽度，则返回原图。
  
  例如：原图宽高尺寸为400 × 320，限定宽度200，高度等比例，生成缩略图尺寸为200×160；限定宽度500，高度等比例，生成缩略图尺寸为400×320。
- 限定高度，宽度等比例。
  
  您需要输入高度，缩略时以高度为基准，将宽度等比例缩小。若输入高度大于原图高度，则返回原图。
  
  例如：原图宽高尺寸为400 × 320，限定高度160，宽度等比例，生成缩略图尺寸为200×160；限定高度500，宽度等比例，生成缩略图尺寸为400×320。
- 限定宽度和高度。
  
  您需要输入宽度和高度，图片会保持原图比例进行缩略，直至宽、高都满足设定值，不裁剪。
  
  例如：原图宽高尺寸为400 × 320，限定宽度为100，高度为100，生成缩略图尺寸为100 × 80；限定宽度为500，高度为500，生成缩略图尺寸为400×320。
- 固定宽度和高度。
  
  您需要输入宽度和高度，图片会保持原图比例先进行缩略，超出设定宽、高部分进行居中裁剪。
  
  例如：原图宽高尺寸为400 × 320 ，固定宽度100和高度100（缩小较大图片，并裁剪图片），生成缩略图尺寸为100×100；固定宽度500和高度500（放大较小图片，并裁剪图片），生成缩略图尺寸为500×500。
保存样式后，在列表中可以看到您已经添加的样式信息。您可以点击“查看命令”，查看样式对应的参数命令。

删除样式

在样式管理列表中，点击“操作”列的“删除”，可删除样式。

示例

例如定义了如下样式：

样式名	样式参数
small	`s_0,h_600,l_1,a_10,f_png,q_80 \| wm_2,t_aGVsbG8gd29ybGQ=,ff_U2ltU3Vu,sz_26,fc_0000007f,g_9,x_70,y_50`

使用参数命令访问：

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@s_0,h_600,l_1,a_10,f_png,q_80|wm_2,t_aGVsbG8gd29ybGQ=,ff_U2ltU3Vu,sz_26,fc_0000007f,g_9,x_70,y_50
使用样式访问：

https://doc.bce.baidu.com/bce-documentation/BOS/image.jpg@!small

对象存储 BOS

对象存储 BOS

图片处理V1.0

基本概念

URL构成

规则和限制

图片处理命令

图片缩放、旋转、渐进显示

图片裁剪

图片水印命令

图片水印

文字水印

图文混合水印

获取图片信息

管道

图片样式