图片智能裁剪

最近更新时间:2020-01-10 10:15:21

1. 接口描述

接口请求域名: tiia.tencentcloudapi.com 。

根据输入的裁剪比例,智能判断一张图片的最佳裁剪区域,确保原图的主体区域不受影响。

可以自动裁剪图片,适应不同平台、设备的展示要求,避免简单拉伸带来的变形。

  • 公共参数中的签名方式必须指定为V3版本,即配置SignatureMethod参数为TC3-HMAC-SHA256。

默认接口请求频率限制:20次/秒。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数

参数名称 必选 类型 描述
Action String 公共参数,本接口取值:CropImage。
Version String 公共参数,本接口取值:2019-05-29。
Region String 公共参数,详见产品支持的 地域列表
Width Integer 需要裁剪区域的宽度,与Height共同组成所需裁剪的图片宽高比例;
输入数字请大于0、小于图片宽度的像素值;
Height Integer 需要裁剪区域的高度,与Width共同组成所需裁剪的图片宽高比例;
输入数字请请大于0、小于图片高度的像素值;
宽高比例(Width : Height)会简化为最简分数,即如果Width输入10、Height输入20,会简化为1:2。
Width : Height建议取值在[1, 2.5]之间,超过这个范围可能会影响效果;
ImageUrl String 图片URL地址。
图片限制:
• 图片格式:PNG、JPG、JPEG。
• 图片大小:所下载图片经Base64编码后不超过4M。图片下载时间不超过3秒。
建议:
• 图片像素:大于50*50像素,否则影响识别效果;
• 长宽比:长边:短边<5;
接口响应时间会受到图片下载时间的影响,建议使用更可靠的存储服务,推荐将图片存储在腾讯云COS。
ImageBase64 String 图片经过base64编码的内容。最大不超过4M。与ImageUrl同时存在时优先使用ImageUrl字段。
注意:图片需要base64编码,并且要去掉编码头部。

3. 输出参数

参数名称 类型 描述
X Integer 裁剪区域左上角X坐标值
Y Integer 裁剪区域左上角Y坐标值
Width Integer 裁剪区域的宽度,单位为像素
Height Integer 裁剪区域的高度,单位为像素
OriginalWidth Integer 原图宽度,单位为像素
OriginalHeight Integer 原图高度,单位为像素
CropResult Integer 0:抠图正常;
1:原图过长,指原图的高度是宽度的1.8倍以上;
2:原图过宽,指原图的宽度是高度的1.8倍以上;
3:抠图区域过长,指抠图的高度是主体备选框高度的1.6倍以上;
4:抠图区域过宽,指当没有检测到人脸时,抠图区域宽度是检测出的原图主体区域宽度的1.6倍以上;
5:纯色图,指裁剪区域视觉较为单一、缺乏主体部分 ;
6:宽高比异常,指Width : Height取值超出[1, 2.5]的范围;

以上是辅助决策的参考建议,可以根据业务需求选择采纳或忽视。
RequestId String 唯一请求 ID,每次请求都会返回。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 图像智能裁剪成功

输入一张图片,输出裁剪坐标结果

输入示例

https://tiia.tencentcloudapi.com/?Action=CropImage
&ImageUrl=https://test.jpg
&Width=https://test.jpg
&Height=https://test.jpg
&<公共请求参数>

输出示例

{
  "Response": {
    "X": 0,
    "Y": 110,
    "Width": 1100,
    "Height": 880,
    "OriginalWidth": 1100,
    "OriginalHeight": 1390,
    "CropResult": 0,
    "RequestId": "bfd478e1-5c94-4e37-ad22-4a5224a09492"
  }
}

5. 开发者资源

API Explorer

该工具提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力,能显著降低使用云 API 的难度,推荐使用。

SDK

云 API 3.0 提供了配套的开发工具集(SDK),支持多种编程语言,能更方便的调用 API。

命令行工具

6. 错误码

以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码

错误码 描述
FailedOperation.DownLoadError 文件下载失败。
FailedOperation.ImageDecodeFailed 图片解码失败。
FailedOperation.ImageNotSupported 不支持的图片文件。
FailedOperation.InvokeChargeError 调用计费返回失败。
FailedOperation.RequestTimeout 后端服务超时。
FailedOperation.UnKnowError 内部错误。
FailedOperation.UnOpenError 服务未开通。
LimitExceeded.TooLargeFileError 文件太大。
ResourcesSoldOut.ChargeStatusException 计费状态异常。