图片服务API文档

滴滴云技术支持发表于:2019年04月24日 15:29:10更新于:2019年05月24日 16:19:47

简介

滴滴云图片服务API提供标准的轻量级无状态HTTP接口,支持用户对数据的全方位管理。

接口概览

API

描述

图片信息

获取文件的基本信息,包括长度、宽度、文件大小、格式。

图片旋转

将图片按顺时针旋转。

图片模糊

对图片进行模糊操作。

图片缩放

将图片缩小或者放大。

图片裁剪

裁剪图片,指定裁剪的起始点以及裁剪的宽高来决定裁剪的区域。

图片水印

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

格式转换

将图片转换成对应格式。

错误码

错误码

ErrInvalidArgument                 = "InvalidArgument"
ErrBadRequest                       = "BadRequest"
ErrMissingArgument               = "MissingArgument"
ErrImageTooLarge                  = "ImageTooLarge"
ErrWatermarkError                  = "WatermarkError"
ErrAccessDenied                    = "AccessDenied"
ErrSignatureDoesNotMatch    = "SignatureDoesNotMatch"
ErrNoSuchFile                         = "NoSuchFile"
ErrNoSuchStyle                       = "NoSuchStyle"
ErrInvalidRange                       = "InvalidRange"
ErrInternalError                        = "InternalError"
ErrNotImplemented                  = "NotImplemented


图片信息(info)

功能:获取文件的基本信息,包括长度、宽度、文件大小、格式。

描述:如果文件有exif信息,则返回exif信息;如果文件没有exif信息,则只返回基本信息。返回结果是json格式。

接口:https://image-demo.s3.didiyunapi.com/pixar.jpg?x-s3-process=image/info

示例:https://image-demo.s3.didiyunapi.com/pixar.jpg?x-s3-process=image/info

示例

{

    "FileSize": 160667,

    "Format": "png",

    "ImageHeight": 333,

    "ImageWidth": 333

}

图片旋转(rotate)

功能:将图片按顺时针旋转。

描述:旋转图片可能会导致图片的尺寸变大;旋转对图片的尺寸有限制,图片的宽或者高不能超过 4096。

接口:https://image-demo.s3.didiyunapi.com/pixar.jpg?x-s3-process=image/rotate,value

操作

参数

描述

取值范围

rotatevalue图片按顺时针旋转的角度[0, 360]默认值为 0,表示不旋转。

示例:https://image-demo.s3.didiyunapi.com/pixar.jpg?x-s3-process=image/rotate,90

图片模糊(blur)

功能:对图片进行模糊操作。

描述:对图片进行模糊操作。

接口:https://image-demo.s3.didiyunapi.com/pixar.jpg?x-s3-process=image/blur,param_value

操作参数描述取值范围

 

      blur

r模糊半径[1,50]r 越大图片越模糊。

s正态分布的标准差[1,50]s 越大图片越模糊。

示例:https://image-demo.s3.didiyunapi.com/pixar.jpg?x-s3-process=image/blur,r_10,s_10

图片缩放(resize)

功能:将图片缩小或者放大。

描述:包含原图、缩略图、其他限制条件。

           原图:单边大小不能超过30,000;

           缩略图:目标缩略图宽与高的乘积不能超过 4096x4096,且单边长度不能超过 4096x4。

           其他限制:调用 resize,默认是不允许放大。即如果请求的图片比原图大,那么返回的仍然是原图。如果想取到放大的图片,即增加参数调用 limit_0。

                             当只指定宽度或者高度时,在等比缩放的情况下,都会默认进行单边的缩放。在固定宽高的模式下,会默认宽高一样的情况下进行缩略。

接口:https://image-demo.s3.didiyunapi.com/pixar.jpg?x-s3-process=image/resize,parame_value

操作名称描述取值范围

 

 

 

 

 

按宽高缩放

 

 

 

 

 

m

指定缩略的模式:

  •  lfit: 等比缩放,限制在指定w与h的矩形内的最大图片。

  • mfit: 等比缩放,延伸出指定w与h的矩形框外的最小图片。

  • fixed:固定宽高,强制缩略。

lfit、mfit、fixed,默认为 lfit。
w指定目标缩略图的宽度。1-4096
h指定目标缩略图的高度。1-4096
limit指定当目标缩略图大于原图时是否处理。值是 1 表示不处理;值是 0 表示处理。0/1, 默认是 1
按比例缩放p倍数百分比。 小于 100,即是缩小,大于 100 即是放大。1-1000

示例:

https://image-demo.s3.didiyunapi.com/pixar.jpg?x-s3-process=image/resize,p_1000

https://image-demo.s3.didiyunapi.com/pixar.jpg?x-s3-process=image/resize,m_fixed,w_100,h_10

图片裁剪(crop)

功能:裁剪图片,指定裁剪的起始点以及裁剪的宽高来决定裁剪的区域。

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

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

接口:https://image-demo.s3.didiyunapi.com/pixar.jpg?x-s3-process=image/crop,parame_value

操作名称描述取值范围

 

 

 

 

裁剪

 

 

 

 

 

w指定裁剪宽度。[0-图片宽度]

h指定裁剪高度。[0-图片高度]

x指定裁剪起点横坐标(默认左上角为原点)。[0-图片边界]

y指定裁剪起点纵坐标(默认左上角为原点)。[0-图片边界]


g设置裁剪的原点位置,由九宫格的格式,一共有九个地方可以设置,每个位置位于每个九宫格的左上角。[nw, north, ne, west, center, east, sw, south, se]

裁剪原点位置参数示意图:

image2019-2-14%2014%3A46%3A53.png?version=1&modificationDate=1550126813000&api=v2

示例:https://image-demo.s3.didiyunapi.com/pixar.jpg?x-s3-process=image/crop,x_10,y_10,w_200,h_200,g_se

图片水印(watermark)

功能:在图片上设置另外一张图片或者文字做为水印。

描述: 图片水印的水印图只能使用当前S3存储空间的图片,网络图片需上传至当前存储空间方可使用。

           一张图片上,最多支持3张不同的水印图做水印。

           同一张水印图,可以重复使用,但是必须放在不同位置。

           各个水印位置,不能完全重叠。

接口:https://image-demo.s3.didiyunapi.com/pixar.jpg?x-s3-process=image/watermark,param_value

操作名称描述取值范围

 

 

基础水印参数

g

水印打在图的位置。

[nw,north,ne,west,center,east,sw,south,se]

x

参数意义:水平边距,就是距离图片边缘的水平距离, 这个参数只有当水印位置是左上,左中,左下, 右上,右中,右下才有意义。

默认值:10,单位:像素(px)

[0 – 4096]


y

参数意义:垂直边距, 就是距离图片边缘的垂直距离, 这个参数只有当水印位置是左上,中上, 右上,左下,中下,右下才有意义

 默认值:10,单位:像素(px)

[0 – 4096]

图片水印参数

image

 水印图片为当前的Bucket下Object,直接针对Object名称进行base64编码。

内容必须是URL安全base64编码 encodedObject = url_safe_base64_encode(object) 如object为”panda.png”, 编码过后的内容为”cGFuZGEucG5n”

URL安全的base64编码
文字水印参数text

参数意义:表示文字水印的文字内容(必须编码)

必须是URL安全base64编码 encodeText = url_safe_base64_encode(fontText) 最大长度为64个字符(即支持汉字最多20个左右)

最大长度为64个字符(即支持汉字最多20个左右)

type表示文字水印的文字类型(必须编码)

color

参数意义:文字水印文字的颜色

参数的构成必须是:六个十六进制数,如:000000表示黑色。 000000每两位构成RGB颜色, FFFFFF表示的是白色

默认值:000000黑色

[0X000000, 0XFFFFFF]

size

参数意义:文字水印文字大小(px)

默认值:40

(0,1000]

rotate文字顺时针旋转角度[0,360]

字体支持表:

参数值

中文意思

URL安全base64编码后的值

备注

wqy-zenhei文泉驿正黑d3F5LXplbmhlaQ==根据RFC,可省略填充符=变为d3F5LXplbmhlaQ
wqy-microhei文泉微米黑d3F5LW1pY3JvaGVp
fangzhengshusong方正书宋ZmFuZ3poZW5nc2h1c29uZw==根据RFC,可省略填充符=变为ZmFuZ3poZW5nc2h1c29uZw
fangzhengkaiti方正楷体ZmFuZ3poZW5na2FpdGk=根据RFC,可省略填充符=变为ZmFuZ3poZW5na2FpdGk
fangzhengheiti方正黑体ZmFuZ3poZW5naGVpdGk=根据RFC,可省略填充符=变为ZmFuZ3poZW5naGVpdGk
fangzhengfangsong方正仿宋ZmFuZ3poZW5nZmFuZ3Nvbmc=根据RFC,可省略填充符=变为ZmFuZ3poZW5nZmFuZ3Nvbmc
droidsansfallbackDroidSansFallbackZHJvaWRzYW5zZmFsbGJhY2s=根据RFC,可省略填充符=变为ZHJvaWRzYW5zZmFsbGJhY2s

示例:https://image-demo.s3.didiyunapi.com/pixar.jpg?x-s3-process=image/watermark,type_d3F5LXplbmhlaQ,size_30,text_SGVsbG8g5Zu-54mH5pyN5YqhIQ,color_FFFFFF,t_100,g_se,x_10,y_10

格式转换(format)

功能:将图片转换成对应格式。

描述: jpg、png、bmp、webp、gif、tiff。 默认不填格式,是按原图格式返回。

           对于普通缩略请求,建议 format 参数放到处理参数串最后,例如:image/resize,w_100/format,jpg。

           对于缩略+水印的请,建议 format 参数跟缩略参数放在一起,例如:image/reisze,w_100/format,jpg/watermark,...。

           保存成 jpg 格式时,是保存成标准型的 jpg (Baseline JPEG)。

接口:https://image-demo.s3.didiyunapi.com/pixar.jpg?x-s3-process=image/format,value

操作名称描述

 

 

 

format

jpg将原图保存成 jpg 格式。

png将原图保存成 png 格式。

webp将原图保存成 webp 格式。

bmp将原图保存成 bmp 格式。

tiff将原图保存成 tiff 格式。

gif将 gif 格式保存成 gif 格式,非 gif 格式是按原图格式保存。

示例:https://image-demo.s3.didiyunapi.com/pixar.jpg?x-s3-process=image/format,jpg