智能裁剪通过主体识别技术自动调整图片，适配多平台和广告位的不同尺寸需求，确保主体居中且完整。-电商经营助手-阿里云帮助中心

适用场景

多平台内容分发：自动生成多种尺寸的内容样式，适应不同平台、不同场景对图片尺寸的不同要求。
内容投放：针对不同广告位同一源图按需裁剪适配多种尺寸，突出主体内容、减少空白，强化产品特色。

功能介绍

自动识别图像的主体区域，精确裁剪。
支持自定义裁剪尺寸输出，可适应不同平台和设备。

效果对比

原图	裁剪为 1000×1000	裁剪为 3000×2000

接口

POST /rest/ai/image/cropping

快速开始

import json

data = json.dumps({
    "ImageUrl": "https://example.com/product.jpg",
    "TargetWidth": 1000,
    "TargetHeight": 1000
})
result = make_signed_request("/rest/ai/image/cropping", data)

d = result["Data"]
print("裁剪结果:", d["ImageUrl"])
print("输出尺寸:", d["Width"], "x", d["Height"])

请求参数

参数	类型	必填	说明
`ImageUrl`	String	是	原图 URL。要求：JPG / JPEG / PNG / BMP / WEBP 格式；分辨率 256×256 至 3000×3000；文件 ≤ 10 MB。
`TargetWidth`	Number	是	期望输出宽度，单位像素，取值 100-5000。
`TargetHeight`	Number	是	期望输出高度，单位像素，取值 100-5000。

当源图宽高比与目标宽高比相差较大时，服务端会优先保证主体完整，必要时对非主体区域做扩展或填充。

响应字段

字段	类型	说明
`Code`	String	业务状态码。成功为 `Success`。
`RequestId`	String	请求唯一标识。
`Message`	String	信息。成功时为 `"Success"`。
`Success`	Boolean	本次调用是否成功。
`Data`	Object	返回的结果结构体信息。
`Data.ImageUrl`	String	裁剪后的结果图片 URL（OSS 签名链接）。
`Data.Width`	Number	输出图像宽度（像素），与 `TargetWidth` 一致。
`Data.Height`	Number	输出图像高度（像素），与 `TargetHeight` 一致。
`Data.UsageMap`	Object	用量字段。
`Data.UsageMap.ProcessedImageCount`	Number	本次已处理图片张数，用于计费核对。

完整示例

请求示例

{
  "ImageUrl": "https://example.com/source.jpg",
  "TargetWidth": 800,
  "TargetHeight": 800
}

响应示例

{
  "Data": {
    "ImageUrl": "https://oss.aliyuncs.com/.../crop-result.png",
    "Height": 750,
    "UsageMap": { "ProcessedImageCount": 1 },
    "Width": 1000
  },
  "RequestId": "616BD57A-D7ED-1F8F-85FA-B52C8D752493",
  "Message": "Success",
  "Code": "success",
  "Success": true
}

使用建议

批量分发的最佳实践：把同一源图按 1000×1000 / 750×1000 / 1200×628 等多种规格依次提交（QPS=5 内可并发），实现"一图多用"。
源图主体居中：源图中主体已经处于画面边缘时，建议先调用智能消除清理干扰元素，再做裁剪可以让主体识别更稳。
主体溢出的兜底：若目标比例与源图相差极大（如把 1×1 裁成 16×9），主体可能溢出。建议先做图像扩展把画面补宽再裁剪。

错误码

错误码	触发场景
`InvalidParameter`	图片格式 / 分辨率 / 大小不在范围；`TargetWidth` 或 `TargetHeight` 不在 100-5000；`ImageUrl` 为空。
`InputContentBlocked`	输入图片触发内容安全审核。
`DownstreamUnavailable`	图片下载失败 / 下游视觉模型暂时不可用。建议指数退避后重试。
`FreeQuotaExhausted`	试用额度已耗尽，需购买商品包或关闭"用完即停"。
`InternalError`	服务端内部错误。请保留 `RequestId` 联系技术支持。

完整错误码列表参见错误码。

使用限制

调用模式：同步。默认 QPS = 5，单次请求超时上限 30 秒。
输入图片：JPG / JPEG / PNG / BMP / WEBP；分辨率 256×256 至 3000×3000；文件 ≤ 10 MB。
输出尺寸：100-5000 像素，宽高独立设置。
计费：¥0.001/张，按 ProcessedImageCount 计件。详见素材优化计费。

常见问题

图像裁剪的策略是什么？

自动识别图片上的主体部分，在尽可能保留主体的前提下，将图片裁剪至输入的目标尺寸。

裁剪会破坏商品主体吗？

有可能。当图片为多主体，或目标尺寸比例与原始图片比例差距过大时，裁剪可能会破坏商品主体。

裁剪可以指定保留的区域或内容吗？

不可以。裁剪根据识别出的完整主体进行剪切，无法指定保留某些局部区域或内容。

后续步骤

智能出图 -- 把裁剪与其他视觉能力一次性编排为异步任务。
智能抠图 -- 裁剪前先抠出主体可获得更紧凑的画面。