图片处理V2.0
所有文档

          对象存储 BOS

          图片处理V2.0

          概述

          图片处理服务依托对象存储BOS系统对外提供灵活、多样、实时的图片处理服务。用户将原始图片上传到BOS上,通过调用简单的RESTful接口,实现对图片的实时处理,如缩略、裁剪、格式转换、旋转、加文字/图片水印等,处理结果图会通过CDN实时的返回给用户。

          在访问速度上,图片处理服务集成了CDN功能,利用遍布在全国的高质量CDN节点,实现图片内容的加速分发,有效降低源站压力。

          图片处理服务的架构如下图所示:

          • 用户首次发送请求处理流程:

            1. 用户端首次发送图片处理请求;
            2. 首次请求,CDN未命中,请求会被直接发送到BOS源站进行处理;
            3. 根据用户发送的处理参数对图片进行实时处理;
            4. 处理后的结果图将被缓存到CDN节点上;
            5. 同时,将结果图返回给用户端。
          • 用户端非首次访问图片处理流程:

            1. 用户端发送图片处理请求;
            2. 若CDN命中,则直接跳到步骤5;若CDN未命中,则跳到步骤3;
            3. 请求会被回源到BOS,并根据用户发送的处理参数对图片进行实时处理;
            4. 处理后的结果图被缓存到CDN节点上;
            5. 将结果图返回给用户端。

          图片处理服务的灵活便捷体现在,您只要通过在原始图片的请求中直接添加处理参数,即可实时得到处理后的结果图。

          计费方式

          图片服务收费分为三个部分:

          • 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高。

          示例


          裁剪

          对图片进行矩形裁剪操作。

          action名称:crop

          参数 取值 说明
          x 0-图片宽度 裁剪左上角起点相对原点的x坐标,非必选,默认0。
          y 0-图片高度 裁剪左上角起点相对原点的y坐标,非必选,默认0。
          w 1-4096 裁剪后图片的宽度,如果指定的宽度超过了图片的宽度,则以图片宽度为准裁剪。单位为px。非必选,默认值原始图片宽度。
          h 1-4096 裁剪后图片的高度,如果指定的高度超过了图片的高度,则以图片高度为准裁剪。单位为px。非必选,默认值原始图片高度。

          示例


          内切圆裁剪

          以图片中心为圆心,进行内切圆裁剪。

          action名称:circle

          参数 取值 说明
          r 0-图片最小边大小的一半 以图片中心为圆心,从图片取出的半径为r的圆形区域,r如果超过最小边大小的一半,默认取原圆的最大内切圆。

          示例


          圆角矩形裁剪

          将图片裁剪为圆角矩形。

          action名称:rounded-corners

          参数 取值 说明
          r 1-4096 设置圆角的半径。如果指定半径r大于原图宽/高,则默认原图宽/高。

          示例


          旋转

          对图片进行一定角度的旋转。

          action名称:rotate

          参数 取值 说明
          a -360-360 图片旋转角度,正数表示顺时针旋转,负数表示逆时针旋转。

          示例


          自适应方向旋转

          根据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不变

          示例


          水印

          对一张图片添加水印处理。

          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个区域,并按照图示位置进行编号,每个区域的锚点位置如图所示: gravity.png

          目前支持的字体类型如下:

          字体 名称 base64编码
          FZLanTingHei 方正兰亭黑 RlpMYW5UaW5nSGVp
          FZFangSong 方正仿宋 RlpGYW5nU29uZw==
          FZShuSong 方正书宋 RlpTaHVTb25n
          FZKai 方正楷体 RlpLYWk=
          FZHei 方正黑体 RlpIZWk=

          示例


          获取图片信息

          此命令用来获取图片信息,如果图片有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样式访问或携带合法签名访问。