友盟+搜索

{{errorMsg}}

介绍

概述

图片处理服务(Image Service,简称 IMG) ,是百川多媒体服务对外提供的海量,安全,低成本高可靠的图片处理服务。用户将原始图片上传,通过简单的 RESTful 接口,在任何时间、任何地点、任何互联网设备上对图片进行处理。图片处理服务提供图片处理接口,图片上传请使用上传接口。基于IMG,用户可以搭建出跟图片相关的服务。

基本概念

分隔符

图片处理服务使用通过URL来访问处理的图片。 所以需要分隔符来区分一些关键字段。不要在使用的图片文件名称中包含图片处理服务设定的分隔符。不然会导致解析出错的问题。

分隔符名称 分隔符 含义
处理分隔符 @ 区分object名称跟处理字符串
样式分隔符 @! 区分object跟样式内容
管道分隔符 | 区分多种操作,详见管道

URL构成规则

图片处理服务使用通过URL来访问处理的图片,本文定义访问方式的规范。

直接显示原图

形式为:http://userdomain/object

通过处理参数访问

形式为:http://userdomain/object@100w_100h_90Q.jpg。

其中userdomain为用户开通图片服务绑定的域名,这个域名会关联到一个Namespace。object为用户所关联Namespace上存储的原图片。@100w_100h_90Q为转换字符串,用来转换处理图片的一段参数。通过指定转换字符串,生成并返回另一张转换处理后的图片。 一个典型的转换字符串,如“@100w_100h_90Q.jpg”,代表需要一张宽(w)100px、高(h)100px、绝对质量(Q)90%、jpg格式的图片。

``

转换字符串分为3部分:初始符、转换参数、转换格式:

  • 初始符是一个“@”符号,从此符号开始,后面都为转换字符串。
  • 转换参数由一个或多个键值对(以"_"连接)组成,“值”在前“键”在后,“值”为数字类型,“键”为一位字母。
  • 转换格式是一种特殊的转换参数,通过指定转换格式,我们对原图处理并返回用户期望的图片文件格式。(支持格式是: jpg, jpeg, webp, png, bmp)。

关键词

顺序无关

转换参数中键值对是循序无关的,即"120w_120h_90Q"和"90Q_120w_120h"都能取到想要的图片,系统会对参数按照本规范以下定义的顺序重新排序后再处理。(由于参数的顺序不同有时会表达不同的语义,如“100w_100h_2x”表达的是“先缩放到100*100,再放大2倍”,即得到200*200的图片;而"2x_100w_100h"按照字面顺序理解是“先放大2倍再缩放到100*100”,即得到100*100的图片,为了避免这样的理解误差,同时简化处理方式,IMG会对参数按照文档中出现的顺序排序后处理。上例中的"2x_100w_100h"会被理解为“100w_100h_2x”,得到200*200的图片。)

覆盖处理

如果转换参数中出现多个相同“键”,后面定义的覆盖前面定义。如“120w_120h_240w”等同于“120h_240w”。

冲突处理

见每个参数中关于冲突的说明。

长边与短边

关于“长边”和“短边”的定义需要特别注意,它们表达的是在缩放中相对比例的长或短。“长边”是指原尺寸与目标尺寸的比值大的那条边;“短边”同理。如原图400 * 200,缩放为800 * 100,(400/800=0.5,200/100=2,0.5 < 2),所以在这个缩放中200那条是长边,400是短边。

URL安全的Base64位编码

在图片处理服务里会有很多参数需要变成Base64位编码, 注意这里的URL 安全Base64位编码只是用在水印操作某些特定参数(文字水印的文字内容,文字颜色,文字字体及图片水印的水印object)里,不要将其用来签名字符串(Signature)的内容。编码的格式是:

  • 先将内容编码成Base64结果;
  • 将结果中的加号”+”替换成中划线“-“;
  • 将结果中的斜杠”/”替换成下划线”_”;
  • 将结果中尾部的“=”号全部去除;

限制

  • 通过图片服务,只能获取图片文件。不允许获取其他格式的文件。支持文件的格式包括jpg, png, bmp, gif, webp, tiff
  • 保存的最终格式只支持jpg, png, bmp, webp (注意gif默认保存成jpg)。
  • 文件的大小限制在20MB。
  • 对缩略后的图片的大小有限制,目标缩略图的宽与高的乘积不能超过4096 * 4096, 而且单边的长度不能超过4096 * 4。
  • 管道目前限制在2个。

图像处理接口

单边固定缩略

可以对图片某一边(宽或高)进行固定到一个长度,另外一边按照比例进行调整。

参数

名称 描述 取值范围
w 指定目标缩略图的宽度 1-4096
h 指定目标缩略图的高度。 1-4096
l 目标缩略图大于原图是否处理。值是1, 即不处理,是0,表示处理 0/1, 默认是0

注意事项

  • 对缩略后的图片的大小有限制,目标缩略图的宽与高的乘积不能超过4096 * 4096, 而且单边的长度不能超过4096 * 4。
  • 如果只指定宽度或者高度,原图将默认转换成jpg格式,如果原图是png, webp, bmp可能会导致图出现变形。详细可以查看质量变换 格式转换

示例

  • 将图缩略成高度为100,宽度按比例处理。

http://imagedemo.image.alimmdn.com/example.jpg@100h

``

  • 将图缩略成宽度为100,高度按比例处理。

http://imagedemo.image.alimmdn.com/example.jpg@100w

``

  • 将图缩略成宽度为500,高度按比例处理,如果目标缩略图大于原图不处理。

http://imagedemo.image.alimmdn.com/example.jpg@500w_1l

``

指定宽高缩略

可以对图片指定宽或高原图,按照长边短边进行调整。

参数

名称 描述 取值范围
w 指定目标缩略图的宽度 1-4096
h 指定目标缩略图的高度。 1-4096
e 缩放优先边, 默认值:0:长边(默认值) 由于图片缩放过程中,原图尺寸与缩放尺寸不一定是相同比例,需要我们指定以长边还是短边优先进行缩放,如原图200 * 400(比例1:2),需要缩放为100 * 100(比例1:1).长边优先时,缩放为50 100;短边优先时(e=1),缩放为`100 200`,若不特别指定,则代表长边优先 0表示按长边优先,默认值 1表示按短边优先
l 目标缩略图大于原图是否处理。如果值是1, 即不处理,是0,表示处理 0/1, 默认是0

注意事项

  • 对缩略后的图片的大小有限制,目标缩略图的宽与高的乘积不能超过4096 * 4096, 而且单边的长度不能超过4096 * 4。

  • 如果不指定格式,原图将默认转换成jpg格式,如果原图是png, webp, bmp可能会导致图出现变形。详细可以查看质量变换 格式转换

示例

  • 将图缩略成宽度为100,高度为100,按长边优先

http://imagedemo.image.alimmdn.com/example.jpg@100h_100w_0e

``

  • 将图缩略成宽度为100,高度为100,按短边优先

http://imagedemo.image.alimmdn.com/example.jpg@100h_100w_1e

``

强制宽高缩略

可以强制指定目标缩略图的高度和宽度,忽略原图的宽高比。注意这可能会导致图片变形。

参数

名称 描述 取值范围
w 指定目标缩略图的宽度 1-4096
h 指定目标缩略图的高度。 1-4096
e 缩放优先边,如果是强制缩略,值是:2 2(强制缩略)
l 目标缩略图大于原图是否处理。如果值是1, 即不处理,是0,表示处理 0/1, 默认是0

注意事项

  • 此操作会导致图变形。

  • 如果不指定格式,原图将默认转换成jpg格式,如果原图是png, webp, bmp可能会导致图出现变形。详细可以查看质量变换 格式转换

示例

  • 将图强制缩略成宽度为100,高度为100

http://imagedemo.image.alimmdn.com/example.jpg@100h_100w_2e

``

自动裁剪

自动裁剪表示图片先按短边缩略,然后从缩略的目标图片裁剪出中间部分得到对应指定高度和宽度的目标缩略图。

参数

名称 描述 取值范围
w 指定目标缩略图的宽度 1-4096
h 指定目标缩略图的高度。 1-4096
e 缩放优先边,这里指定按短边优化 1
c 是否进行裁剪。如果是想对图进行自动裁剪,必须指定为1 0,1
l 如果目标缩略图大于原图是否处理,值是1, 即不处理,是0,表示处理 0/1, 默认是0

注意事项

  • 自动裁剪从按短边优先缩略的图中间进行裁剪,如果想从裁剪出图的左边部分或者右边部分。即不指定裁剪参数C, 然后再利用管道实现

  • 如果不指定格式,原图将默认转换成jpg格式,如果原图是png, webp, bmp可能会导致图出现变形。详细可以查看质量变换 格式转换

示例

  • 将图自动裁剪成宽度为100,高度为100的效果图

http://imagedemo.image.alimmdn.com/example.jpg@100h_100w_1e_1c

``

  • 将图片按短边裁剪然后,裁剪出左半部分。

http://imagedemo.image.alimmdn.com/example.jpg@100h_100w_1e|0-0-100-100a

``

按比例缩放

可以通过指定一个比例百分比参数,让图片按照指定的比例进行缩略或者放大。

参数

名称 描述 取值范围
p 倍数百分比。 小于100,即是缩小,大于100即是放大。 1-1000

注意:

  • 如果不指定格式,原图将默认转换成jpg格式,如果原图是png, webp, bmp可能会导致图出现变形。详细可以查看质量变换 格式转换

  • 如果参数p跟w, h 合用时,p将直接作用于w, h (乘以p%) 得到新的w,h, 如100w_100h_200p 的作用跟200w_200h 的效果是一样的。

  • 如果对图片进行倍数放大,单边的最大长度不能超过4096 * 4 。

示例

  • 将图按比例放大两倍。

http://imagedemo.image.alimmdn.com/example.jpg@200p

``

  • 将图按比例缩略到原来的1/2

http://imagedemo.image.alimmdn.com/example.jpg@50p

``

高级裁剪

可以通过指定起始横坐标,纵坐标及裁剪的宽度和裁剪的高度对图进行高级裁剪。

参数

名称 描述 取值范围
a 参数的类型:x-y-width-length  如:100-50-200-150a  一共四个参数,每个参数之间以”-“隔开。第一个参数表示起始点x坐标(以左上角为原点),第二个参数表示起始点y坐标, 第三个参数表示要裁剪的宽度,第四个参数表示要裁剪的高度。如100-50-200-150a 表示从点(100, 50) 裁剪大小为(200, 150)的图片。 注意:可以将第三个参数,第四个参数置为0, 表示裁剪到图片的边缘。如100-50-0-0a 表示从点(100, 50) 裁剪到图片的最后 width, height的范围是1-4096

注意事项

  • 如果不指定格式,原图将默认转换成jpg格式,如果原图是png, webp, bmp可能会导致图出现变形。详细可以查看质量变换 格式转换

  • 如果指定的起始横纵坐标大于原图,将会返回错误:BadRequest, 错误内容是:Advance cut's position is out of image.

  • 如果从起点开始指定的宽度和高度超过了原图,将会直接裁剪到原图结尾。

使用示例

  • 裁剪图从起点(100, 50)到图的结束

http://imagedemo.image.alimmdn.com/example.jpg@100-50-0-0a

``

  • 裁剪图从起点(100, 50)到裁剪100x100的大小

http://imagedemo.image.alimmdn.com/example.jpg@100-50-100-100a

``

区域裁剪

可以将图片分成多个区域,按照区域进行裁剪。

参数

名称 描述 取值范围
rc 用户可以指定对某一个区域进行裁剪。在这里把图片分成9个区域。  参数格式:<width>x<height>-<pos>rc.jpg  Width 指的是裁剪的宽度[`0, 4096`] Height 指的是裁剪的高度[`0, 4096`] pos指的是裁剪区域,取值范围是[`0,9`],默认是左上角,区域数值对应表见下图 如果想裁剪左上角,宽度是100, 高度是200的区域,参数是:100x200-1rc 如果想裁剪左上角,宽度是100,高度是图片的原高度 参数是:100x0_1rc 或者100x_1rc 如果高度或者宽度不填,或者参数是0,或者参数大于原图。默认是按原图的高度或宽度返回。 width, height的范围是1-4096

区域数值对应表

``

注意事项

  • 如果不指定格式,原图将默认转换成jpg格式,如果原图是png, webp, bmp可能会导致图出现变形。详细可以查看质量变换 格式转换

  • 如果从起点开始指定的宽度和高度超过了原图,将会直接裁剪到原图结尾。

示例

  • 裁剪原图左上区域宽度100高度200的区域

http://imagedemo.image.alimmdn.com/example.jpg@100x200-1rc

``

内切圆

用户可以将图片只保存圆形图案,如果图片的最终格式是png, webp, bmp等支持透明通道的图片,那么图片非圆形区域的地方将会以透明填充。如果图片的最终格式是jpg。那么非圆形区域是以白色进行填充。

参数

参数 描述 取值
ci 从图片取出圆形区域 参数格式:[radius]-[type]ci radius : [1, 4096] 如果radius能指定圆的半径。 但是圆的的半径不能超过原图的最小边的一半。如果半径超过。圆的大小仍然是原圆的最大内切圆。 type: [0, 1] 0:表示图片最终大小仍然是原图大小 1: 表示图片最终大小是能包含这个圆的最小正方形

注意事项

  • 如果图片的最终格式是png, webp, bmp等支持透明通道的图片,那么图片非圆形区域的地方将会以透明填充。如果图片的最终格式是jpg。那么非圆形区域是以白色进行填充。推荐使用保存成png格式
  • 指定半径大于原图最大内切圆的半径。 圆的大小仍然是图片的最大内切圆。

示例

  • 裁剪半径是100, 保持圆是原来大小

http://imagedemo.image.alimmdn.com/example.jpg@100-0ci

  • 裁剪半径是100, 保存圆是能包含圆的最小正方形,格式是png

http://imagedemo.image.alimmdn.com/example.jpg@100-1ci.png

  • 裁剪半径是1000, 保存圆是能包含圆的最小正方形,格式是png

http://imagedemo.image.alimmdn.com/example.jpg@1000-1ci.png

圆角矩形

可以保存图片是圆角矩形,并可以指定圆角的大小 。

参数

参数 描述 取值
2ci 从图片取出圆形区域 参数格式:[radius]-2ci radius : [1, 4096] radius指定圆角的半径。 但是生成的最大圆角的的半径不能超过原图的最小边的一半。

注意事项

  • 如果图片的最终格式是png, webp, bmp等支持透明通道的图片,那么图片非圆形区域的地方将会以透明填充。如果图片的最终格式是jpg. 那么非圆形区域是以白色进行填充 。推荐使用保存成png格式
  • 指定半径大于原图最大内切圆的半径。 圆角的大小仍然是图片的最大内切圆。

示例

  • 裁剪圆角半径是30, 格式是png

http://imagedemo.image.alimmdn.com/example.jpg@30-2ci

  • 图片先自动裁剪成100x100, 然后保存成圆角半径是10,格式是png

http://imagedemo.image.alimmdn.com/example.jpg@100w_100h_1e_1c_10-2ci.png

索引切割

将图片分成x,y轴按指定块大小,然后指定的索引,取出指定的区域。

参数

参数 描述 取值
ic 参数格式:[length]x-[index]ic 或[length]y-[index]ic length是切割长度 index 是表示块数。**(0表示第一块)** 其中x表示按x轴,水平线切割。y 表示按y轴,垂直线切割 length:[1,切割边边长],单位px。如果超出切割边的大小,返回原图。 index:[0,最大块数)。如果超出最大块数,返回原图。

注意事项

  • 如果指定的索引大于切割后范围,将返回原图。

示例

对图片x轴按100平分,取出第一块。

http://imagedemo.image.alimmdn.com/example.jpg@100x-0ic

对图片y轴按100平分,取出第一块。

http://imagedemo.image.alimmdn.com/example.jpg@100y-0ic

对图片x轴按100平分,取出第一百块,仍然是原图

http://imagedemo.image.alimmdn.com/example.jpg@100x-100ic

缩略后填充

先把图按短边优先缩略,然后再用指定颜色填充剩余区域

参数

名称 描述 取值范围
w 指定目标缩略图的宽度 1-4096
h 指定目标缩略图的高度。 1-4096
e 缩略优先边,这里必须指定值为4 4
bgc 指定填充的背景颜色。默认不指定,为白色填充。参数格式:<red>-<green>-<blue>bgc 如:100-100-100bgc red,green,blue指定一个颜色 Red, green, blue[`0-255`]

注意事项

  • 如果不指定格式,原图将默认转换成jpg格式,如果原图是png, webp, bmp可能会导致图出现变形。详细可以查看质量变换 格式转换

  • bgc 由红绿蓝三原色这三个参数指定生成对应颜色。

示例

  • 将图按短边缩略到100x100, 然后按白色填充

http://imagedemo.image.alimmdn.com/example.jpg@100w_100h_4e

``

  • 将图按短边缩略到100x100, 然后按红色填充

http://imagedemo.image.alimmdn.com/example.jpg@100w_100h_4e_100-0-0bgc

``

质量变换

如果图片保存成jpg, 可以支持质量变换。

参数

名称 描述 取值范围
q 决定jpg图片的相对quality,对原图按照q%进行quality压缩。如果原图quality是100%,使用"90q"会得到quality 90%的图片;如果原图quality是80%,使用“90q”会得到quality 72%的图片 只能在原图是jpg格式的图片上使用,才有相对压缩的概念.如果保存图片是png,那么相对质量就相当于绝对质量。 1-100
Q 决定jpg图片的绝对quality,把原图quality压到Q%,如果原图quality小于指定数字,则不压缩。如果原图quality是100%,使用"90Q"会得到quality 90%的图片;如果原图quality是95%,使用“90Q”还会得到quality 90%的图片;如果原图quality是80%,使用“90Q”不会压缩,返回quality 80%的原图。 只能在jpg/png效果上使用,其他格式无效果。 如果一个转换url里,即指定了q和Q,按Q来处理 1-100

注意事项

  • 如果不填Q或者q 这两个参数,这样有可能会导致图片占用大小变大。如明确想得到一个质量固定的图片,请采用Q参数。如果想按原图质量来保存,指定成100q

示例

  • 将原图缩略成100w_100h,相对原图质量的80的jpg图

http://imagedemo.image.alimmdn.com/example.jpg@100w_100h_80q

``

  • 将原图缩略成100w_100h,绝对质量的80的jpg图

http://imagedemo.image.alimmdn.com/example.jpg@100w_100h_80Q

``

格式转换

可以将图片转换成对应格式(jpg, png, bmp, webp)

参数

名称 描述
jpg 将原图保存成jpg格式,如果原图是png,webp, bmp存在透明通道,默认会把透明填充成黑色。如果想把透明填充成白色可以指定1wh参数
png 将原图保存成png格式
webp 将原图保存成webp格式
bmp 将原图保存成bmp格式
src 按原图格式返回,如果原图是gif, 此时返回gif格式第一帧,保存成jpg格式,而非gif格式

注意事项

  • wh只有当原图是四通道(即有透明背景)的png, webp, bmp转换成jpg格式时才有效果。即把原图当中的透明背景以白色填充,如果不指定wh,那么上述图转换成jpg时,透明背景将会变成黑色。

  • 保存成jpg格式时,默认是保存成标准型的jpg(Baseline JPEG) 如果想指定是渐进式JPEG(Progressive JPEG), 可以指定参数1pr, 详见渐进显示

示例

  • 将png保存成jpg格式

http://imagedemo.image.alimmdn.com/panda.png@.jpg

``

  • 将png保存成jpg格式,透明的地方填充成白色

http://imagedemo.image.alimmdn.com/panda.png@1wh.jpg

``

  • 将jpg保存成高度为100, 宽度为100的png格式

http://imagedemo.image.alimmdn.com/example.jpg@100h_100w.png

``

旋转

可以对处理后的图片进行按顺时针旋转

参数

名称 描述 取值范围
r 默认值 :0(表示不旋转) [`0, 360`]

注意事项

  • 旋转后的图可能会导致图的尺寸变大。

  • 旋转对图的尺寸有限制,图片的宽或者高不能超过4096。

示例

  • 将原图缩略成宽度为100,高度为100,按顺时针旋转90度

http://imagedemo.image.alimmdn.com/example.jpg@100w_100h_90r

``

  • 将原图按顺时针旋转270度

http://imagedemo.image.alimmdn.com/example.jpg@270r

``

自适应方向

某些手机拍摄出来的照片可能带有旋转参数(存放在照片exif信息里面)

参数

名称 描述 取值范围
o 进行自动旋转 0:表示按原图默认方向,不进行自动旋转 1:表示根据图片的旋转参数,对图片进行自动旋转,如果存在缩略参数,是先进行缩略,再进行旋转。 2: 表示根据图片的旋转参数,对图片进行自动旋转,如果存在缩略参数,先进行旋转,再进行缩略 [`0, 2`]

注意事项

  • 如果采用缩略旋转1,可能会导致图片最终的宽度和高度跟指定的参数不符。

  • 进行自适应方向旋转,必须要求原图的宽度和高度必须小于4096.

  • 如果原图是没有旋转参数,加上1o, 2o参数不会对图有影响。

示例

  • 将图缩略成宽度为100,对图片不做自动旋转处理

http://imagedemo.image.alimmdn.com/f.jpg@100w.jpg

``

  • 将图缩略成宽度为100,对图片进行自动旋转1

http://imagedemo.image.alimmdn.com/f.jpg@100w_2o.jpg

``

得到的目标效果图宽度是100,高度是127。

  • 将图缩略成宽度为100,对图片进行自动旋转2

http://imagedemo.image.alimmdn.com/f.jpg@100w_1o.jpg

``

得到的目标效果图宽度是79, 高度是100。

渐进显示

jpg格式在呈现时有两种方式,一种是自上而下扫描式的,另外一种是先模糊后渐渐清晰(在网络环境比较差时明显)默认保存是第一种,如果指定呈现时是先模糊后清晰的,请使用渐进显示参数。

参数

名称 描述 取值范围
pr 1表示保存成渐进显示的jpg格式 0表示保存成普通的jpg格式 [`0, 1`]

注意事项

  • 此参数只有效果图是jpg格式时,才有意义 。

示例

  • 将图缩略成宽度100, 高度100,并且保存成渐进显示的jpg格式

http://imagedemo.image.alimmdn.com/example.jpg@100w_200h_1pr.jpg

``

  • 将png图保存成渐进显示的jpg格式

http://imagedemo.image.alimmdn.com/panda.png@1pr

``

锐化

可以对处理后的图片进行锐化处理,使图片变得清晰。

参数

名称 描述 取值范围
sh 0: 表示不进行锐化处理,默认值 1: 表示进行锐化处理 [`0, 1`]

示例

  • 对原图进行锐化处理

http://imagedemo.image.alimmdn.com/example.jpg@1sh

``

  • 将原图缩略成高度100, 宽度100,并进行锐化操作,保存成png格式

http://imagedemo.image.alimmdn.com/example.jpg@100w_100h_1sh.png

``

模糊效果

可以对图片进行模糊操作。

参数

参数 描述 取值
bl 参数格式:[radius]-[sigma]bl radius是模糊半径 sigma是正态分布的标准差 如:3-2bl 模糊半径是3,标准差是2 radius取值在 [1,50], radius越大,越模糊 sigma取值 [1,50],越大,越模糊

示例

  • 对图片进行模糊半径是3, 标准差是2。

http://imagedemo.image.alimmdn.com/example.jpg@3-2bl

  • 图片先自动裁剪成100x100, 然后对图片进行模糊半径是3, 标准差是2。

http://imagedemo.image.alimmdn.com/example.jpg@100w100h1e1c3-2bl

亮度和对比度

可以对处理后的图片进行亮度和对比度调节

参数

名称 描述 取值范围
b 亮度调整 0表示原图亮度,小于0表示亮度越低,大于0表示亮度越高 [`-100, 100`]
d 对比度调整 0表示原图对比度,小于0表示对比越低,大于0表示对比越高 [`-100, 100`]

示例

  • 将原图只进行亮度调整

http://imagedemo.image.alimmdn.com/example.jpg@50b

``

  • 将原图只进行对比度调整

http://imagedemo.image.alimmdn.com/example.jpg@-50d

``

  • 将原图进行亮度和对比度调整

http://imagedemo.image.alimmdn.com/example.jpg@-50d_50b

``

获取exif信息

exif 是专门为数码相机的照片设定的,可以记录数码照片的属性信息和拍摄数据。 可以通过@exif 来获取,返回格式是Json格式,目前只支持返回

  • GPSLatitudeRef
  • GPSLatitude
  • GPSLongitudeRef
  • GPSLongitude
  • DateTime
  • DateTimeOriginal
  • DateTimeDigitized
  • Make
  • Model
  • Orientation

注意事项

如果原图没有exif 信息,会返回400错误。错误码是:BadRequest 错误内容是:Image has no exif info.

示例

  • 没有exif 的例子

http://imagedemo.image.alimmdn.com/example.jpg@exif

<Error>
    <Code>BadRequest</Code>
    <Message>Image has no exif info.</Message>
    <RequestId>5502D98553F47BFAB7F95B8C</RequestId>
    <HostId>imagedemo.image.alimmdn.com</HostId>
</Error> 

  • 有exif 的例子

http://imagedemo.image.alimmdn.com/f.jpg@exif

{
    "DateTime": {"value": "2015:02:11 15:38:27"},
    "FileSize": {"value": "23471"},
    "GPSLatitude": {"value": "0deg "},
    "GPSLatitudeRef": {"value": "North"},
    "GPSLongitude": {"value": "0deg "},
    "GPSLongitudeRef": {"value": "East"},
    "ImageHeight": {"value": "333"},
    "ImageWidth": {"value": "424"},
    "Orientation": {"value": "7"}
} 

获取基本信息和exif信息

可以通过@infoexif来获取获取文件的基本信息包括宽度,长度,文件大小,格式。并且如果文件有exif信息,就返回exif信息,如果没有exif信息,就只返回基本信息。返回结果是json格式。

示例

  • 没有exif 的例子

http://imagedemo.image.alimmdn.com/example.jpg@infoexif

{
    "FileSize": {"value": "21839"},
    "Format": {"value": "jpg"},
    "ImageHeight": {"value": "267"},
    "ImageWidth": {"value": "400"}
} 

  • 有exif 的例子

http://imagedemo.image.alimmdn.com/f.jpg@infoexif

{
    "DateTime": {"value": "2015:02:11 15:38:27"},
    "FileSize": {"value": "23471"},
    "Format": {"value": "jpg"},
    "GPSLatitude": {"value": "0deg "},
    "GPSLatitudeRef": {"value": "North"},
    "GPSLongitude": {"value": "0deg "},
    "GPSLongitudeRef": {"value": "East"},
    "ImageHeight": {"value": "333"},
    "ImageWidth": {"value": "424"},
    "Orientation": {"value": "7"}
} 

图片水印接口

概述

水印操作可以在图片上设置另外一张图片或者文字做为水印。

水印类型分成图片水印,文字水印,和文图混合水印。

基本参数

图片水印,文字水印,和文图混合水印都可以使用如下参数。

名称 描述 参数类型
t 参数意义:透明度, 如果是图片水印,就是让图片变得透明,如果是文字水印,就是让水印变透明。  默认值:100, 表示 100%(不透明) 取值范围: [`0-100`] 可选参数
p 参数意义:位置,水印打在图的位置,位置如成如下图。  默认值:9,表示在右下角打水印  取值范围:[`1-9`] 可选参数
x 参数意义:水平边距, 就是距离图片边缘的水平距离, 这个参数只有当水印位置是左上,左中,左下, 右上,右中,右下才有意义  默认值:10  取值范围:[`0 – 4096`]  单位:像素(px) 可选参数
y 参数意义:垂直边距, 就是距离图片边缘的垂直距离, 这个参数只有当水印位置是左上,中上, 右上,左下,中下,右下才有意义  默认值:10  取值范围:[`0 – 4096`]  单位:像素(px) 可选参数
voffset 参数意义: 中线垂直偏移,当水印位置在左中,中部,右中时,可以指定水印位置根据中线往上或者往下偏移。  默认值:0  取值范围:[`-1000, 1000`]  单位:像素(px) 可选参数

区域数值对应表

``

注意事项

水平边距、垂直边距、中线垂直偏移可以调节不仅可以调节水印在图片中的位置,而且当图片存在多重水印时,也可以调节两张水印在图中的布局。

使用示例

  • 右下角打上文字水印

http://imagedemo.image.alimmdn.com/example.jpg@watermark=2&&type=d3F5LXplbmhlaQ&size=40&text=SGVsbG8g5Zu-54mH5pyN5YqhIQ

``

  • 右下角打上文字水印,水平边距是 10,垂直边距20

http://imagedemo.image.alimmdn.com/example.jpg@watermark=2&&type=d3F5LXplbmhlaQ&size=40&text=SGVsbG8g5Zu-54mH5pyN5YqhIQ&color=I0ZGRkZGRg&t=90&p=9&x=10&y=20

``

  • 右中部分打上水印,水平边距为10, 垂直中线偏移为20,透明度为50

http://imagedemo.image.alimmdn.com/example.jpg@watermark=2&&type=d3F5LXplbmhlaQ&size=40&text=SGVsbG8g5Zu-54mH5pyN5YqhIQ&color=I0ZGRkZGRg&t=50&p=6&x=10&voffset=20

``

3.  图片水印

图片水印就是在原图的基础上加上一张水印图片

访问类型

@watermark=1&object=<encodedobject>&t=<transparency>&x=<distanceX>&y=<distanceY>&p=<position>…

其中watermark与object两个参数为必填项。

参数

名称 描述 参数类型
object 参数意义: 水印图片的object名字(必须编码)  注意:内容必须是url 安全Base64编码 EncodedObject = url_safe_base64_encode(object) 如object为”panda.png”, 编码过后的内容就是 “cGFuZGEucG5n” 必选参数

水印图片支持预处理,目前支持的处理有调节亮度(b)和对比度(d),按比例缩略(p),指定宽度缩略(w,h) 这几个参数,其他参数暂未支持。

如果要指定对水印图片进行预处理,处理参数带在水印object之后,以@符号连接。如:

  • 对panda.png 进行放大2倍 Object = url_safe_base64_encode(“panda.png@200p”)

  • 对panda.png 进行缩小一倍,亮度调节成50, 对比度调节成40 Object = url_safe_base64_encode (“panda.png@50p_50b_40d”)

  • 对panda.png 增加按宽度50缩略,亮度调节成30 Object = url_safe_base64_encode (“panda.png@50w_30b”)

  • 对panda.png 增加按高度20缩略,对比度调节成10 Object = url_safe_base64_encode (“panda.png@20h_10d”)

所以尽量不要让原object名字是带@. 不然可能会导致访问异常。如不要让 原始object名字是”panda@123.png”.

使用示例

  • 原图example.jpg 加上水印图片是panda.png, 右下角, 水平边距为10, 垂直边距为10, 透明度为90

http://imagedemo.image.alimmdn.com/example.jpg@watermark=1&&object=cGFuZGEucG5n&t=90&p=9&x=10&y=10

``

  • 原图example.jpg 加上水印图片是panda.png, 对panda.png进行缩小50%, 亮度为10, 对比度为20, 水印位置为右中, 水平边距为10, 中线垂直边距为20

http://imagedemo.image.alimmdn.com/example.jpg@watermark=1&&object=cGFuZGEucG5nQDUwcF8xMGJfMjBk&t=90&p=6&x=10&voffset=20

``

文字水印

文字水印就是在原图的基础上加上一段文字内容做为水印。

访问类型

@watermark=2&text=<encodeText>&type=<encodeType>&size=<size>&color=<encode colr>&t=<t>&p=<p>&x=<x>&voffset=<offset>&y=<y>

其中watermark与object两个参数为必填项。

参数

名称 描述 参数类型
text 参数意义:表示文字水印的文字内容 EncodefontText = url_safe_base64_encode (fontText) 最大长度为64个字符(即支持汉字最多20个左右) 必选参数
type 参数意义:表示文字水印的文字类型(必须编码)  注意:必须是Base64编码 EncodeFontType = url_safe_base64_encode (fontType)  取值范围:见下表(文字类型编码对应表)  默认值:wqy-zenhei ( 编码后的值:d3F5LXplbmhlaQ) 可选参数
color 参数意义:文字水印文字的颜色(必须编码)  注意:参数必须是Base64位编码 EncodeFontColor = url_safe_base64_encode(fontColor) 参数的构成必须是:# + 六个十六进制数 如:#000000表示黑色。 #是表示前缀,000000每两位构成RGB颜色, #FFFFFF表示的是白色  默认值:#000000黑色 base64编码后值:IzAwMDAwMA 可选参数
size 参数意义:文字水印文字大小(px)  取值范围:(0,1000`]  默认值:40 可选参数
s 参数意义:文字水印的阴影透明度  取值范围:(0,100`] 可选参数

文字类型编码对应表

参数值 中文意思 编码后的值
wqy-zenhei 文泉驿正黑 d3F5LXplbmhlaQ
wqy-microhei 文泉微米黑 d3F5LW1pY3JvaGVp
fangzhengshusong 方正书宋 ZmFuZ3poZW5nc2h1c29uZw
fangzhengkaiti 方正楷体 ZmFuZ3poZW5na2FpdGk
fangzhengheiti 方正黑体 ZmFuZ3poZW5naGVpdGk
fangzhengfangsong 方正仿宋 ZmFuZ3poZW5nZmFuZ3Nvbmc
droidsansfallback DroidSansFallback ZHJvaWRzYW5zZmFsbGJhY2s

使用示例

  • 字体是文泉驿正黑,字体大小是40, 颜色是白色(#FFFFFF), 文字阴影是50, 文字水印内容是:Hello, 图片服务!, 水印位置是:右中,水平边距是:10, 中线垂直偏移是:20

http://imagedemo.image.alimmdn.com/example.jpg@watermark=2&type=d3F5LXplbmhlaQ&size=40&text=SGVsbG8g5Zu-54mH5pyN5YqhIQ&color=I0ZGRkZGRg&s=50&t=90&p=6&x=10&voffset=20

``

  • 最简单水印:文字内容是:Hello, 图片服务

http://imagedemo.image.alimmdn.com/example.jpg@watermark=2&text=SGVsbG8g5Zu-54mH5pyN5YqhIQ

``

文图混合水印

文图混合水印就是文字,图片并列一起做为水印打在图片上。

访问类型

@watermark=3&object=<encodeObject>&text=<encodeText>&type=<encodeType>&size=<size>&color=<encodecolor>&order=<order>&align=<align>&interval=<interval>&t=<t>&p=<p>&x=<x>&y=<y>

其中watermark与object两个参数为必填项。

参数

文图混合水印,相当于文字水印跟图片水印的混合,并行在一行输出。所以文图混合水印支持文字水印和图片水印的参数。其中object, text是必选参数。

名称 描述 参数类型
order 参数意义: 文字,图片水印前后顺序  取值范围:[`0, 1`] order = 0 图片在前(默认值); order = 1 文字在前。 可选参数
align 参数意义:文字、图片对齐方式  取值范围:[`0, 1, 2`] align = 0 上对齐(默认值) align = 1 中对齐 align = 2 下对齐 可选参数
interval 参数意义:文字和图片间的间距 取值范围: [`0, 1000`] 可选参数

使用示例

  • 单纯文字水印,文字内容是:Hello, 图片服务! 阴影是50, 位置在右下角, 水平边距和垂直边距都是10, 水印透明是:90

http://imagedemo.image.alimmdn.com/example.jpg@watermark=2&text=SGVsbG8g5Zu-54mH5pyN5YqhIQ&s=50&t=90&p=9&x=10&y=10

``

  • 单纯图片水印,图片object 是panda.png,位置在右下角, 水平边距和垂直边距都是10, 水印透明是:90

http://imagedemo.image.alimmdn.com/example.jpg@watermark=1&&object=cGFuZGEucG5n&t=90&p=9&x=10&y=10

``

  • 文图混合水印,文字内容是:Hello, 图片服务! 阴影是50, 位置在右下角,图片object 是panda.png。 水平边距和垂直边距都是10, 水印透明是:90, 排版方式是图片前, 对齐方式是中对齐,间距是10

http://imagedemo.image.alimmdn.com/example.jpg@watermark=3&&object=cGFuZGEucG5n&type=d3F5LXplbmhlaQ&size=40&text=SGVsbG8g5Zu-54mH5pyN5YqhIQ&color=I0ZGRkZGRg&order=0&align=1&interval=10&t=90&p=9&x=10&y=10

``

管道

访问规则

<文件URL>@<action1>|<action2>

URL 通过@符号后面处理参数(action1, action2)来实现即时云处理,如果有多任务(比如先做缩略,再加上水印)可以用管道来实现,执行顺序按管道指定顺序执行,目前只支持二级管道。

管道的分隔符是”|”

上述表示先做对文件URL做处理action1 然后再在上述的基础上做处理action2,然后输出结果。上述action1,action2可以是简单缩略,文字水印,图片水印任意一种。

使用示例

  • 先对图片做按高度300缩略,然后再加上文字水印,水印内容是:Hello 图片服务!

http://imagedemo.image.alimmdn.com/example.jpg@300h|watermark=2&text=SGVsbG8g5Zu-54mH5pyN5YqhIQ

``

这个例子由action1( 300h : 按高度是300缩略) 操作完再执行action2(watermark=2&&text=SGVsbG8g5Zu-a54mH5pyN5YqhIQ: 文字水印,水印内容是:Hello 图片服务!)处理时间, 先对图片执行Action1操作,再执行Action2操作。

  • 先对图片做文字水印,水印内容是: Hello, 图片服务! 水印位置在右下角,然后再对图片做图片水印,水印object是:panda.png, 水印位置在中间。

http://imagedemo.image.alimmdn.com/example.jpg@watermark=2&text=SGVsbG8g5Zu-54mH5pyN5YqhIQ&p=9|watermark=1&object=cGFuZGEucG5n&t=90&p=5

``

图片样式接口

访问规则

<文件URL>@!StyleName

文件URL即是由Channel+object 组成的url地址

  1. @!是样式的分隔符,在URL带了这个分隔符,图片处理服务会把该分隔符后面的内容当成样式的名称。
  2. StyleName表示的是样式的名字。
  3. 创建样式、删除样式和修改样式都在前端控制台实现。
  4. 当访问的样式在指定Channel不存在时,将返回NotSuchStyle错误。

使用示例

假如我们对image-demo这个Channel创建三个样式。

样式名 样式内容
pipe1 150w_150h_1e_1c_0i_100q_1x.jpg| watermark=1&&object=cGFuZGEucG5n&t=51&p=9&x=10&y=10
pipe2 250w_250h_0e_0c_0i_90q_1x.jpg|150w_150h_0e_1c_1i_90q_1x.jpg
pipe3 180w_180h_1e_1c_0i_0o_90q_1x.jpg| watermark=2&&type=d3F5LXplbmhlaQ&size=25&text=SGVsbG8g5Zu-54mH5pyN5YqhIQ&color=IzAwMDAwMA&t=90&p=9&x=10&y=10

对于样式1(pipe1):

http://imagedemo.image.alimmdn.com/example.jpg@150w_150h_1e_1c_0i_100q_1x.jpg|watermark=1&&object=cGFuZGEucG5n&t=51&p=9&x=10&y=10

``

http://imagedemo.image.alimmdn.com/example.jpg@!pipe1

``

两者是一样的。

对于样式2(pipe2):

http://imagedemo.image.alimmdn.com/example.jpg@250w_250h_0e_0c_0i_90q_1x.jpg%7C150w_150h_0e_1c_1i_90q_1x.jpg

``

http://imagedemo.image.alimmdn.com/example.jpg@!pipe2

``

效果是一样的

对于样式3 (pipe3):

http://imagedemo.image.alimmdn.com/example.jpg@180w_180h_1e_1c_0i_0o_90q_1x.jpg|watermark=2&&type=d3F5LXplbmhlaQ&size=25&text=SGVsbG8g5Zu-54mH5pyN5YqhIQ&color=IzAwMDAwMA&t=90&p=9&x=10&y=10

``

http://imagedemo.image.alimmdn.com/example.jpg@!pipe3

``

效果是一样的

错误响应

当用户访问图片处理服务出现错误的时候,图片处理服务会返回给用户相应的错误码和错误信息,以帮助用户定位与处理问题。

错误的响应格式

错误响应的消息体例子

<Error>
  <Code>BadRequest</Code> 
  <Message>Input is not base64 decoding.</Message> 
  <RequestId>52B155D2D8BD99A15D0005FF</RequestId> 
  <HostId>userdomain</HostId> 
</Error> 

错误包含以下元素:

  • Code: 图片处理服务返回给用户的错误码。

  • Message: 图片处理服务给出的详细错误信息。

  • RequestId: 用以标识错误请求的唯一UUID,在无法解决问题时候,可以使用此错误ID发送给图片处理服务的工程师去定位错误的原因。

  • HostId:用来标识访问的图片处理服务集群。

错误码

错误码 描述 HTTP 状态码
TooManyPipe 管道数目超过限制 400
InvalidArgument 参数错误 400
BadRequest 错误请求 400
MissingArgument 缺少参数 400
ImageTooLarge 图片大小超过限制 400
WatermarkError 水印错误 400
AccessDenied 拒绝访问 403
SignatureDoesNotMatch 签名不匹配 403
NoSuchFile 图片不存在 404
NoSuchChannel 频道不存在 404
InternalError 服务内部错误 500
NotImplemented 方法未实现 501

FAQ

图片处理后变形

图片处理URL,如果不加图片格式,默认都是jpg格式,所以有时会变形,需要在URL最后加文件类型后缀,比如“.png”。