图片处理接口

基本概念

图片服务域名

图片服务域名,是指用来访问图片服务的域名。图片服务和普通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。

示例

图片裁剪

命令参数

参数名称 缩写命令 类型 取值范围 命令描述 缺省值 是否必选
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。
原始图片高度

示例

图片水印命令

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

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

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

图片锚点

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

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

  1. 锚点位置;
  2. 基于锚点位置,指定在水平和垂直方向上的距离。

图片水印

命令参数

参数名称 缩写命令 类型 取值范围 命令描述 缺省值 是否必选
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=”)。

文字水印

命令参数

参数名称 缩写命令 类型 取值范围 命令描述 缺省值 是否必选
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列表中,则显示效果为默认字体宋体。

示例

图文混合水印

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

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

示例

获取图片信息

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

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

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

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

示例

  • 包含exif信息的图片示例:

    http://imgdoc.bce.baidu.com/bce-documentation/BOS/Image1.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信息的图片示例:

    http://imgdoc.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},执行顺序按管道指定顺序从左至右执行。

示例

图片样式

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

访问方式

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

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

添加样式

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

  1. 登录BOS控制台,进入您已开通图片服务的Bucket。点击左侧导航“图片服务”后,点击右侧页面中的“样式管理”。

  2. 点击“添加样式”,进入添加样式表单页面。您可根据需要,设定该样式的图片处理参数,同时您可在右侧的预览区域实时进行效果预览。

    图片样式的设置方式支持“基础设置”和“高级设置”两种。

    • 基础设置,您需要在页面上对下方的每一项处理参数进行手动设定。
    • 高级设置,您可直接在框中直接输入图片处理命令参数。

    创建好样式后,点击“保存”。

    缩放说明

    • 限定宽度,高度等比例。

      您需要输入宽度,缩略时以宽度为基准,将高度等比例缩小。若输入宽度大于原图宽度,则返回原图。

      例如:原图宽高尺寸为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。

  3. 保存样式后,在列表中可以看到您已经添加的样式信息。您可以点击“查看命令”,查看样式对应的参数命令。

    image.png

删除样式

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

image.png

示例

例如定义了如下样式:

样式名 样式参数
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`

原图保护

BOS支持通过API实现原图保护功能,并可通过resource字段指定该功能生效范围,具体请参见原图保护