文档中心

AI MediaKit

图像工具 API

提交图像智能裁剪任务 API

POST https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/smart-crop-image

本 API 用于提交一个同步的图像智能裁剪任务，能自动识别图像中的主体人脸区域，并智能地适配您指定的尺寸进行裁剪。本功能支持普通人脸和动漫人脸场景，当未识别到人脸时，可按预设的降级策略（如居中裁剪）输出结果。

说明

如需了解该功能的详细说明及应用，请参阅图像智能裁剪。

请求参数

Header 参数

参数	类型	是否必选	示例值	描述
Authorization	String	是	Bearer {Your_API_Key}	格式为 Bearer {Your_API_Key}。请参考基础概念及准备工作获取 API Key。

Body 参数

参数	类型	是否必选	示例值	描述
image_url	String	是	https://example.com/face.jpg	待处理的图片 URL。图像来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、火山引擎对象存储 (tos://) 三种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。文件大小：建议单张图片不超过 10 MB。支持格式：支持 .png、.jpg、.jpeg、.webp、.tiff、.bmp、.heic 等主流图像格式。输入分辨率限制：宽高均不得超过 6000 px。
target_width	Integer	否	200	裁剪后的目标宽度，单位为 px。默认值为 100。
target_height	Integer	否	200	裁剪后的目标高度，单位为 px。默认值为 100。
scene	String	否	person_face	裁剪场景模型，用于指定识别主体。支持以下两种场景： person_face：（默认）普通人脸裁剪。 cartoon_face：动漫人脸裁剪。
crop_strategy	String	否	center_crop	降级裁剪策略。裁剪后图片与目标宽高比例不一致时的策略： top_crop：（默认）从图像顶部开始，水平居中进行裁剪。 center_crop：从图像正中心开始向四周进行裁剪。 frosted_glass_fill：保持原图完整，在两侧或上下添加毛玻璃效果的背景以达到目标尺寸。
frosted_glass_strength	Number	否	80	毛玻璃填充的模糊强度。仅当 crop_strategy 设置为 frosted_glass_fill 时生效。数值越大越模糊，推荐取值范围为 [10, 100]。默认值为 100。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。

请求示例

以下示例演示了如何为一个图片提交智能裁剪任务：目标尺寸为 200x300px，优先识别普通人脸，降级策略为毛玻璃填充，模糊度为 80。

响应说明

这是一个同步接口，处理结果将直接在本接口的响应体中返回。

响应参数

参数	类型	描述
success	Boolean	任务是否成功。 true：成功。请查看 result 字段以获取任务结果。 false：失败。请查看 error 字段以获取详细错误信息。
result	Object	包含图像处理结果的对象，仅在 success 为 true 时返回。详见下文 Result 对象。
error	Object	错误详情对象，仅在 success 为 false 时返回。详见下文 Error 对象。
task_id	String	任务的唯一标识。
task_type	String	任务类型。
request_id	String	本次 API 请求的唯一标识，可用于问题排查。
expires_at	Integer	任务结果的过期时间戳（Unix Time，单位：秒）。仅当任务成功且有结果时返回。
queue_id	String	任务提交的目标队列 ID。

Result 对象

参数	类型	描述
image_url	String	智能裁剪后的图片文件下载地址。该地址的有效期为 24 小时，请务必及时保存产物。
image_size	Integer	生成图像的大小，单位为字节。
image_format	String	生成图像的格式，例如：jpeg。
image_width	Integer	生成图像的宽度，单位为 px。
image_height	Integer	生成图像的高度，单位为 px。

Error 对象

参数	类型	描述
code	String	具体的错误码，用于程序化识别错误类型。例如：InvalidParameter。关于各错误码的详细信息，请参阅错误码。
type	String	错误的宏观类型。例如：BadRequest。
message	String	对错误的详细描述，可用于开发调试。

响应示例

成功响应示例：

失败响应示例：

最近更新时间：2026.07.30 16:50:56

这个页面对您有帮助吗？

有用

无用