tencent cloud

缩放
下载PDF
最后更新时间：2025-12-08 17:24:51
缩放
最后更新时间： 2025-12-08 17:24:51
下载PDF

功能概述

腾讯云数据万象通过 imageMogr2接口提供图片缩放功能。该功能支持以下处理方式：
下载时处理
上传时处理
云上数据处理

授权说明

通过子账号使用时，需要在 授权策略 的 action 中添加对应的权限。对象存储支持的所有操作接口请参见 COS action。
下载时处理：授权策略中 action 设置为 cos:GetObject。
上传时处理：授权策略中 action 设置为 cos:PutObject。
云上数据处理：授权策略中 action 设置为 cos:PutObject。
说明：
GetObject 对应的 resource 为源文件，PutObject 对应的 resource 为转存的文件。

服务开通

首次使用该功能时将默认为您开通数据万象，同时该存储桶将自动绑定数据万象，无需角色授权，即可直接使用。
注意：
数据万象绑定后，如果您手动对存储桶进行数据万象的解绑操作，将无法继续使用该功能。

使用限制

动图格式不支持进行尺寸放大。
更多使用限制，详情请参见 使用限制。

费用说明

该接口为付费服务，产生的费用将由数据万象收取，详细计费说明可参见 图片处理费用。
如果采用下载时处理的方式，且通过外网进行下载，调用会产生 流量费用。

接口示例

方式一：下载时处理

GET /<ObjectKey>?imageMogr2/thumbnail/<imageSizeAndOffsetGeometry> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>

方式二：上传时处理

PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Pic-Operations: 
{
  "is_pic_info": 1,
  "rules": [{
      "fileid": "exampleobject",
      "rule": "imageMogr2/thumbnail/<imageSizeAndOffsetGeometry>"
  }]
}

方式三：云上数据处理

POST /<ObjectKey>?image_process HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Content-length: Size
Authorization: Auth String
Pic-Operations: 
{
  "is_pic_info": 1,
  "rules": [{
      "fileid": "exampleobject",
      "rule": "imageMogr2/thumbnail/<imageSizeAndOffsetGeometry>"
  }]
}
说明：
Authorization: 携带鉴权信息，用于验证请求的合法性的请求头，Pic-Operations 头部需签入签名信息中，详情请参见 请求签名 文档。
Pic-Operations 为 json 格式的字符串，具体参数信息可参见 图片持久化处理。
当 fileid 与 ObjectKey 相同时，处理后的图片将覆盖原图存储；不相同时将分别存储原图和处理后图片。
fileid 的值需要经过 URLEncode。

处理参数说明

操作名称：thumbnail。
参数
含义
类型
是否必选
ObjectKey
对象文件名，例如 folder/sample.jpg。
String
是
/thumbnail/!<Scale>p
指定图片的宽高为原图的 Scale%，取值范围为1 - 1000的整数，超出则不处理。
String
否
/thumbnail/!<Scale>px
指定图片的宽为原图的 Scale%，高度不变，取值范围为1 - 1000的整数，超出则不处理。
String
否
/thumbnail/!x<Scale>p
指定图片的高为原图的 Scale%，宽度不变，取值范围为1 - 1000的整数，超出则不处理。
String
否
/thumbnail/<Width>x
指定目标图片宽度为 Width，高度等比缩放，取值范围为1 - 10000的整数，超出则按10000进行处理。
String
否
/thumbnail/x<Height>
指定目标图片高度为 Height，宽度等比缩放，取值范围为1 - 10000的整数，超出则按10000进行处理。
String
否
/thumbnail/<Width>x<Height>
限定缩略图的宽度和高度的最大值分别为 Width 和 Height，进行等比缩放，缩放比例取宽缩放比和高缩放比的较小值，Width 和 Height 的取值范围为1 - 10000，超出则按10000进行处理。
注意：
宽缩放比：目标宽/原图宽；高缩放比：目标高/原图高。
String
否
/thumbnail/!<Width>x<Height>r
限定缩略图的宽度和高度的最小值分别为 Width 和 Height，进行等比缩放，缩放比例取宽缩放比和高缩放比的较大值，Width 和 Height 的取值范围为1 - 10000，超出则按10000进行处理。
注意：
宽缩放比：目标宽/原图宽；高缩放比：目标高/原图高。
String
否
/thumbnail/<Width>x<Height>>
限定缩略图的宽度和高度的最大值分别为 Width 和 Height，进行等比缩小，缩放比例取宽缩放比和高缩放比的较小值，Width 和 Height 的取值范围为1 - 10000，超出则按10000进行处理。如果目标宽（高）大于原图宽（高），则不处理。
注意：
宽缩放比：目标宽/原图宽；高缩放比：目标高/原图高。
String
否
/thumbnail/<Width>x<Height><
限定缩略图的宽度和高度的最大值分别为 Width 和 Height，进行等比放大，缩放比例取宽缩放比和高缩放比的较小值，Width 和 Height 的取值范围为1 - 10000，超出则按10000进行处理。如果目标宽（高）小于原图宽（高），则不处理。
注意：
宽缩放比：目标宽/原图宽；高缩放比：目标高/原图高。
String
否
/thumbnail/<Width>x<Height>!
忽略原图宽高比例，指定图片宽度为 Width，高度为 Height，强行缩放图片，可能导致目标图片变形，Width 和 Height 的取值范围为1 - 10000，超出则按10000进行处理。
String
否
/thumbnail/<Area>@
等比缩放图片，缩放后的图像，总像素数量不超过 Area。
String
否
/pad/<pad>
将原图缩放为指定 Width 和 Height 的矩形内的最大图片，之后使用 color 参数指定的颜色居中填充空白部分；<pad> 取值为0或1。
0代表不使用 pad 模式
1代表使用 pad 模式
String
否
/color/<color>
填充颜色，<color> 需设置为十六进制 RGB 格式（如 #FF0000），详情参考 RGB 编码表，需经过 URL 安全的 Base64编码，默认值为 #FFFFFF，表示白色。
String
否
/ignore-error/1
当处理参数中携带此参数时，针对文件过大、参数超限等导致处理失败的场景，会直接返回原图而不报错。
String
否
说明：
表格中的多个 thumbnail 参数，需至少选择一个，若选择了多个，仅会生效已选的第一个。例如选择了两个参数：/thumbnail/!<Scale>p/!x<Scale>p。仅会生效 !<Scale>p。

实际案例

说明：
本篇文档中的实际案例仅包含下载时处理，该类处理不会保存处理后的图片至存储桶。如有保存需求，您可查阅 图片持久化处理 文档并配置上传时处理或云上数据处理。
原图如下：



案例一：缩放宽高

假设缩放图片宽高为原图50%，示例如下：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/thumbnail/!50p
最终效果如下：



案例二：缩放宽度，高度不变

假设缩放指定图片宽度为原图50%，高度不变，示例如下：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/thumbnail/!50px
最终效果如下：



案例三：Pad 模式缩放

将原图缩放为600 x 600的矩形内的最大图片，并使用指定颜色填充空白部分，示例如下：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?imageMogr2/thumbnail/600x600/pad/1/color/IzNEM0QzRA
最终效果如下：



案例四：Pad 模式缩放并携带私有文件签名

处理方式同上，仅增加签名部分，并与图片处理参数以“&”连接，示例如下：
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?q-sign-algorithm=<signature>&imageMogr2/thumbnail/!50px
说明：
<signature>为签名部分，获取方式请参考 请求签名。

注意事项

为了避免未授权人员通过访问不携带处理参数的链接实现访问和下载原图的情况，您可同时将处理参数签入到请求签名中，处理参数整体是参数的 key，value 为空，如下是简单的示例（仅做样式参考，可能已经过期无法直接访问），详细计算方法请参见 请求签名。
http://examples-1251000004.cos.ap-shanghai.myqcloud.com/sample.jpeg?q-sign-algorithm=sha1&q-ak=************************************&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=****************************************&watermark/1/image/aHR0cDovL2V4YW1wbGVzLTEyNTEwMDAwMDQucGljc2gubXlxY2xvdWQuY29tL3NodWl5aW4uanBn/gravity/southeast

本页内容是否解决了您的问题？
您也可以 联系销售 或 提交工单 以寻求帮助。
是
否

文档反馈