对象存储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样式访问或携带合法签名访问。