全部产品
阿里云办公

PhotoProcess

更新时间:2018-06-14 09:30:16

描述

提交大图异步处理任务。

大图异步处理可以将高分辨率 5000 * 5000、甚至 10000 * 10000 的大图,进行缩放、切割处理,这些被图片处理的多个小图都会根据请求的参数保存到 OSS 中,您可以分享 OSS 链接实现处理结果的多端访问。

目前支持 JPG/PNG 格式的图片。

请求参数

名称 类型 是否必填 描述
Project String 项目名
Action String PhotoProcess
SrcUri String 源数据的存储位置,
例如 OSS 资源”oss://bucket1/object”
TgtUri String 转换输出内容到目标位置,
例如 OSS 桶的指定前缀”oss://bucket1/imm-photo-tgt/session123/“
Style String 指定大图异步处理的语法格式
NotifyTopicName String 异步通知的 TopicName
NotifyEndpoint String 异步反向通知的 Endpoint,图像处理状态可以通过该 Endpoint 异步通知到调用者
ExternalID String 任务的外部标签,用于区分不同的任务

Style格式

  • 单一操作处理。Style 采用/[mode],[param]格式;比如Style=/resize, p_50,表示按比例缩小为原图的50%,resize 为mode,p_50为 param。

  • 组合操作处理。Style 采用/[mode], [param]/[mode], [param]格式,执行时从左到右顺序处理;比如Style=/resize,p_60/indexcrop,x_10,y_8,表示先把图片按比例缩小为原图的60%,然后把图片按横向 X 轴分为10片、纵向 Y 轴分为8片,共80张小图。

Style支持的mode和参数

等比例缩放模式resize

mode 为 resize ,提供如下 param 参数:

名称 类型 是否必填 描述
p String 缩放倍数的百分比。
小于100,即是缩小,大于100即是放大。取值范围,1-1000

输出的文件命名规则为 resize.p[value].jpg,例如按照Style=/resize, p_50处理,则输出的文件名为 resize.p50.jpg。假设输入的TgtUri为/bucket1/imm-photo-tgt/session1,那么最终生成的文件位置为/bucket1/imm-photo-tgt/session1/resize.p50.jpg

索引切割模式indexcrop

mode 为 indexcrop,提供如下 param 参数:

名称 类型 是否必填 描述
x String 图片按照宽度Width平均分为 X 份
y String 图片按照高度Heigtht平均分为 Y 份

比如按照 X=4, Y=4 方式切分,将会得到如下的16张小图:屏幕快照 2017-09-27 下午5.16.56.png | left | 517x265

输出的文件命名规则为indexcrop_n.jpg,n 为图中最左上角的序号(计算公式为 n=i+j*4,4为横轴),比如按照Style=/indexcrop, x_4,y_4处理,则按照上述方法会生成16张小图片,最左上角的标号nx=0。假设TgtUri为/bucket1/imm-photo-tgt/session1,希望获取 i=0, j=1 的小图,那么对应的序号为4,文件位置为/bucket1/imm-photo-tgt/session1/indexcrop_4.jpg

像素切割模式crop

mode为crop,提供如下param参数:

名称 类型 是否必填 描述
w String 指定裁剪宽度为 w 像素,最后的那块将会小于或等于 w 像素
h String 指定裁剪高度为 h 像素,最后的那块将会小于或等于 h 像素

输出的文件命名规则为 crop.n.jpg,n为最左上角的序号,参考索引切割模式。比如1024*768的原图,按照”Style=/crop, x_200,y_150“处理,则按照上述描述得到36张小图。如果指定 TgtUri 为/bucket1/imm-photo-tgt/session1,希望获取 i=1,j=2 的小图那么对应的文件位置为/bucket1/imm-photo-tgt/session1/crop_13.jpg

返回参数

名称 类型 描述
RequestId String 用户发送的每次接口调用请求,无论成功与否,系统都会返回一个唯一识别码 RequestId 给用户
TaskId String 任务 ID
TgtLoc String 输出目标文件的位置,
  • 输入参数 ExternalID 不为空,以 TgtUri/{ExternalID}-${TaskId} 为前缀,
  • 输入参数 ExternalID 为空,以 TgtUri/${TaskId} 为前缀,
便于名字空间隔离
Status String 任务状态:
  • Running
  • Finished
  • Failed
CreateTime String 任务创建时间,例如”2017-12-14 10:28:35.360268 +0800 CST”

基于TgtUri返回TgtLoc,在OSS对象存储中的命名规则

基于TgtUri参数指定的前缀和ExternalID,比如/bucket1/imm-photo-tgt/session123/,那么生成的目标文件的前缀为:

/bucket1/imm-photo-tgt/session123/${ExternalID}-${JodId}

重复请求处理

基于幂等性的要求, 两次相同操作以最后执行的请求为准。

如果两次执行操作的内容相同或者重复请求(内容相同,SignatureNonce 也相同),并且系统已经存在该任务,则后续的请求直接返回成功,避免消耗计算资源做相同的任务。

转换生成目标文件

生成的目标文件会持久化保存,推荐为某个桶下的/imm-photo-tgt/${name}路径,从而便于维护管理。

您可以主动删除转换后的目标文件,如果不主动删除则会长期保留以备使用,但是会占用存储空间。如果希望自动的删除目标文件,您也可以在 /imm-format-convert-tgt 前缀下配置 OSS的生命周期,这样目标文件在到期后,会根据策略被清除。

示例

请求示例:

  1. POST https://imm.cn-hangzhou.aliyuncs.com?Action=PhotoProcess
  2. &Project=test
  3. &SrcUri="oss://bucket/1.jpg"
  4. &TgtUri="oss://bucket/imm-photo-tgt/session1"
  5. &Style="/indexcrop,x_10,y_10"

成功返回示例

  1. {
  2. "RequestId": "FF3B7D81-66AE-47E0-BF69-157DCF187514",
  3. "TaskId": "23468948-33EA-28A0-CA35-452ACE867326",
  4. "TgtLoc": "oss://bucket/imm-photo-tgt/session1/23468948-33EA-28A0-CA35-452ACE867326/",
  5. "Status": "Running",
  6. "CreateTime": "2017-11-14 10:28:35.360268 +0800 CST"
  7. }

特殊错误码

错误代码 错误信息 HTTP 状态码 说明
InvalidSourceType The source type is not supported 400 源文件格式不支持
InvalidSourceURI The source URI is not valid. 400 源文件的 URI 无效
EmptySrcFile The source file is empty 400 源文件为空
InvalidTgtType The target type is not supported 400 目标文件格式不支持
InvalidTgtURI The traget URI is not valid 400 目标文位置无效