History
Introduction
API Category
Making API Requests
Region APIs
Instance APIs
Cloud Hosting Cluster APIs
Image APIs
Instance Launch Template APIs
Placement Group APIs
Key APIs
Security Group APIs
Network APIs
Data Types
Error Codes
裁剪
聚焦模式
字号
功能概述
腾讯云数据万象通过 imageMogr2 接口提供裁剪功能，包括普通裁剪、缩放裁剪、内切圆裁剪、圆角裁剪和人脸智能裁剪。
该功能支持以下处理方式：
下载时处理
上传时处理
云上数据处理
限制说明
支持格式：支持处理 JPG、BMP、GIF、PNG、WEBP 格式，并且支持 HEIF 格式的解码和处理操作。
体积限制：处理图片原图大小不超过32MB、宽高不超过30000像素且总像素不超过2.5亿像素，处理结果图宽高设置不超过9999像素；针对动图，原图宽 x 高 x 帧数不超过2.5亿像素。
动图帧数限制：gif 帧数限300帧。
接口示例
1. 下载时处理
GET /<ObjectKey>?imageMogr2/cut/<width>x<height>x<dx>x<dy>/crop/<imageSizeAndOffsetGeometry>/iradius/<radius>/rradius/<radius>/scrop/<Width>x<Height> HTTP/1.1Host: <BucketName-APPID>.cos.<Region>.myqcloud.comDate: <GMT Date>Authorization: <Auth String>
说明：
请忽略上面的空格与换行符。
2. 上传时处理
PUT /<ObjectKey> HTTP/1.1Host: <BucketName-APPID>.cos.<Region>.myqcloud.comDate: GMT DateAuthorization: Auth StringPic-Operations:{"is_pic_info": 1,"rules": [{"fileid": "exampleobject","rule": "imageMogr2/cut/<width>x<height>x<dx>x<dy>/crop/<imageSizeAndOffsetGeometry>/iradius/<radius>/rradius/<radius>/scrop/<Width>x<Height>"}]}
说明：
3. 云上数据处理
POST /<ObjectKey>?image_process HTTP/1.1Host: <BucketName-APPID>.cos.<Region>.myqcloud.comDate: GMT DateContent-length: SizeAuthorization: Auth StringPic-Operations:{"is_pic_info": 1,"rules": [{"fileid": "exampleobject","rule": "imageMogr2/cut/<width>x<height>x<dx>x<dy>/crop/<imageSizeAndOffsetGeometry>/iradius/<radius>/rradius/<radius>/scrop/<Width>x<Height>"}]}
处理参数说明
参数 | 含义 |
ObjectKey | 对象文件名，例如 folder/sample.jpg。 |
/ignore-error/1 | 当处理参数中携带此参数时，针对文件过大、参数超限等导致处理失败的场景，会直接返回原图而不报错 |
普通裁剪参数说明
操作名称：cut。
参数 | 含义 |
<width> | 指定目标图片的宽为 width |
<height> | 指定目标图片的高为 height |
<dx> | 相对于图片左上顶点水平向右偏移 dx |
<dy> | 相对于图片左上顶点水平向下偏移 dy |
说明：
参数取值范围应大于0，小于原图宽高。
缩放裁剪参数说明
操作名称：crop。
参数 | 含义 |
/crop/<Width>x | 指定目标图片宽度为 Width，高度不变。Width 取值范围应大于0，小于原图宽度 |
/crop/x<Height> | 指定目标图片高度为 Height，宽度不变。Height 取值范围应大于0，小于原图高度 |
/crop/<Width>x<Height> | 指定目标图片宽度为 Width，高度为 Height 。Width 和 Height 取值范围都应大于0，小于原图宽度/高度 |
内切圆裁剪参数说明
操作名称：iradius。
参数 | 含义 |
/iradius/<radius> | 内切圆裁剪功能，radius 是内切圆的半径，取值范围为大于0且小于原图最小边一半的整数。内切圆的圆心为图片的中心。图片格式为 gif 时，不支持该参数。 |
圆角裁剪参数说明
操作名称：rradius。
参数 | 含义 |
/rradius/<radius> | 圆角裁剪功能，radius 为图片圆角边缘的半径，取值范围为大于0且小于原图最小边一半的整数。圆角与原图边缘相切。图片格式为 gif 时，不支持该参数。 |
人脸智能裁剪参数说明
操作名称：scrop。
参数 | 含义 |
/scrop/<Width>x<Height> | 基于图片中的人脸位置进行缩放裁剪。目标图片的宽度为 Width、高度为 Height。 |
九宫格方位图
九宫格方位图可为图片的多种操作提供位置参考。红点为各区域位置的原点（通过 gravity 参数选定各区域后位移操作会以相应远点为参照）。
注意：
当 gravity 参数设置为 center 时，dx、dy 参数无效。
当 gravity 参数设置为 north 或 south 时，dx 参数无效（水印会水平居中）。
当 gravity 参数设置为 west 或 east 时，dy 参数无效（水印会垂直居中）。
实际案例
说明：
案例一：普通裁剪
相对于图片左上顶点水平向右平移100像素，垂直向下平移10像素，指定目标图片大小为600×600进行裁剪：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/cut/600x600x100x10
原图如下：
最终效果如下：
案例二：缩放裁剪
假设以中心点 center 为参考点，缩放裁剪至300×400，示例如下：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/crop/300x400/gravity/center
最终效果如下：
案例三：内切圆裁剪
取半径为200，进行内切圆裁剪：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/iradius/200
最终效果如下：
案例四：圆角裁剪
取半径为100，进行圆角裁剪：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/rradius/100
最终效果如下：
案例五：人脸智能裁剪
基于图片中的人脸位置进行缩放裁剪，目标图片大小为100×600，示例如下：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/scrop/100x600
说明：
如果图片中没有识别到人脸，则返回原图。
案例六：人脸智能裁剪并携带私有文件签名
处理方式同上，仅增加签名部分，并与图片处理参数以“&”连接，示例如下：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?q-sign-algorithm=<signature>&imageMogr2/scrop/100x600
说明：
注意事项
为了避免未授权人员通过访问不携带处理参数的链接实现访问和下载原图的情况，您可同时将处理参数签入到请求签名中，处理参数整体是参数的 key，value 为空，如下是简单的示例（仅做样式参考，可能已经过期无法直接访问），详细计算方法请参见 请求签名。
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?q-sign-algorithm=sha1&q-ak=AKID********************&q-sign-time=1593342360;1593342720&q-key-time=1593342360;1593342720&q-header-list=&q-url-param-list=watermark%252f1%252fimage%252fahr0cdovl2v4yw1wbgvzlteyntewmdawmdqucgljc2gubxlxy2xvdwquy29tl3nodwl5aw4uanbn%252fgravity%252fsoutheast&q-signature=26a429871963375c88081ef60247c5746e834a98&watermark/1/image/aHR0cDovL2V4YW1wbGVzLTEyNTEwMDAwMDQucGljc2gubXlxY2xvdWQuY29tL3NodWl5aW4uanBn/gravity/southeast
文档反馈