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

本 API 用于提交一个同步的图像裁剪任务，可对输入图像进行多模式裁剪，包括方向裁剪、定向裁剪、自定义裁剪与内切圆裁剪，适用于多端尺寸适配、主体保留、商品图去边以及指定区域截取等多种场景。

请求参数

Header 参数

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

Body 参数

参数	类型	是否必选	示例值	描述
image_url	String	是	https://example.com/source.jpg	待处理的图片 URL。图像来源：支持公网 HTTP/HTTPS URL、本地上传 (mediakit://)、火山引擎对象存储 (tos://) 三种输入协议。关于各协议的具体说明和使用示例，请参阅多源媒体输入与本地上传。文件大小：建议单张图片不超过 35 MB。支持格式：支持 .png、.jpg、.jpeg、.webp 等主流图像格式。仅支持处理静图。特殊限制：当使用内切圆裁剪（crop_mode 为 circle）时，原图的最短边不得超过 2048 px。
crop_mode	String	否	custom	裁剪模式，决定了裁剪的行为方式及所需参数。默认为 directional。 directional：方向裁剪。根据指定的宽度、高度和位置进行裁剪。 origin：定向裁剪。根据指定的宽高、偏移量和锚点进行裁剪。 custom：自定义裁剪。根据指定的左上角和右下角坐标进行裁剪。 circle：最大内切圆裁剪。此模式下无需配置其他参数。关于不同裁剪模式的详细介绍，请见裁剪模式说明。
output_format	String	否	png	输出图片的格式。默认为 original（保持原图格式）。可选值：png、jpeg、webp。注意：对于内切圆裁剪（crop_mode 为 circle），为确保背景透明，建议将输出格式设置为 png 或 webp。若输出为 jpeg，非圆形区域将被填充为白色。
queue_id	String	否	q00a9731598092652e4a95292434198	任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考项目与队列管理。
方向裁剪参数（当 crop_mode 为 directional 时生效）
crop_width	Integer	否	800	裁剪后图像的目标宽度，单位为 px。当 crop_mode 为 directional 时，必须提供 crop_width 和 crop_height，且二者不能同时为 0。若 crop_width 设为 0，则宽度将根据 crop_height 按原图比例自适应。
crop_height	Integer	否	600	裁剪后图像的目标高度，单位为 px。当 crop_mode 为 directional 时，必须提供 crop_width 和 crop_height，且二者不能同时为 0。若 crop_height设为 0，则高度将根据 crop_width 按原图比例自适应。
crop_position	String	否	center	裁剪区域的位置，默认为 center。可选值： center：居中 up：顶部 down：底部 left：左侧 right：右侧
定向裁剪参数（当 crop_mode 为 origin 时生效）
crop_width	Integer	否	400	裁剪后图像的目标宽度，单位为 px。当 crop_mode 为 origin 时必填。
crop_height	Integer	否	300	裁剪后图像的目标高度，单位为 px。当 crop_mode 为 origin 时必填。
origin_gravity	String	否	northwest	裁剪的锚点（起始点），默认为 northwest (左上角)。可选值： northwest north northeast west center east southwest south southeast
origin_x	Integer	否	50	裁剪区域相对于锚点的水平偏移量，单位为 px。当 crop_mode 为 origin 时必填。正值向右，负值向左。
origin_y	Integer	否	100	裁剪区域相对于锚点的垂直偏移量，单位为 px。当 crop_mode 为 origin 时必填。正值向下，负值向上。
自定义裁剪参数（当 crop_mode 为 custom 时生效）
custom_x1	Integer	否	100	裁剪区域左上角的横坐标（X 轴），单位为 px。当 crop_mode 为 custom 时必填。
custom_y1	Integer	否	150	裁剪区域左上角的纵坐标（Y 轴），单位为 px。当 crop_mode 为 custom 时必填。
custom_x2	Integer	否	400	裁剪区域右下角的横坐标（X 轴），单位为 px。当 crop_mode 为 custom 时必填。
custom_y2	Integer	否	350	裁剪区域右下角的纵坐标（Y 轴），单位为 px。当 crop_mode 为 custom 时必填。

请求示例

以下示例演示了如何对一张图片进行自定义裁剪，截取由左上角坐标 (100, 150) 和右下角坐标 (400, 350) 限定的矩形区域，并以 PNG 格式输出。

响应说明

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

响应参数

参数	类型	描述
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	生成图像的格式，例如：png。
image_width	Integer	生成图像的宽度，单位为 px。
image_height	Integer	生成图像的高度，单位为 px。

Error 对象

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

响应示例

成功响应示例：

失败响应示例：

AI MediaKit