`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}`。请参考[基础概念及准备工作](https://docs.volcengine.com/docs/6448/2300661)获取 API Key。 | ### Body 参数 |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |image_url |String |是 |`https://example.com/source.jpg` |待处理的图片 URL。

* **图像来源**：支持公网 HTTP/HTTPS URL、本地上传 (`mediakit://`)、火山引擎对象存储 (`tos://`) 三种输入协议。关于各协议的具体说明和使用示例，请参阅[多源媒体输入与本地上传](https://docs.volcengine.com/docs/6448/2536893)。

* **文件大小**：建议单张图片不超过 35 MB。

* **支持格式**：支持 `.png`、`.jpg`、`.jpeg`、`.webp` 等主流图像格式。仅支持处理静图。

* **特殊限制**：当使用内切圆裁剪（`crop_mode` 为 `circle`）时，原图的最短边不得超过 2048 px。 | |`crop_mode` |String |否 |`custom` |裁剪模式，决定了裁剪的行为方式及所需参数。默认为 `directional`。

* `directional`：方向裁剪。根据指定的宽度、高度和位置进行裁剪。

* `origin`：定向裁剪。根据指定的宽高、偏移量和锚点进行裁剪。

* `custom`：自定义裁剪。根据指定的左上角和右下角坐标进行裁剪。

* `circle`：最大内切圆裁剪。此模式下无需配置其他参数。

关于不同裁剪模式的详细介绍，请见[裁剪模式说明](https://docs.volcengine.com/docs/6448/2484298#c3c61d22)。 | |`output_format` |String |否 |`png` |输出图片的格式。默认为 `original`（保持原图格式）。可选值：`png`、`jpeg`、`webp`。

**注意**：对于内切圆裁剪（`crop_mode` 为 `circle`），为确保背景透明，建议将输出格式设置为 `png` 或 `webp`。若输出为 `jpeg`，非圆形区域将被填充为白色。 | |`queue_id` |String |否 |`q00a9731598092652e4a95292434198` |任务提交的目标队列 ID。如不传，默认会使用系统自动创建的队列 ID。您可以将不同业务或优先级的任务提交到不同的队列，以实现按队列对应的项目进行分账。您可以在 AI MediaKit 控制台队列管理页面创建和管理队列，系统会自动分配一个队列 ID。详情请参考[项目与队列管理](https://docs.volcengine.com/docs/6448/2519520)。 | |方向裁剪参数（当 `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 格式输出。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/crop-image' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/source_image.jpg", "crop_mode": "custom", "custom_x1": 100, "custom_y1": 150, "custom_x2": 400, "custom_y2": 350, "output_format": "png" }' ``` ## 响应说明这是一个同步接口，处理结果将直接在本接口的响应体中返回。 ### 响应参数 |参数 |类型 |描述 | |---|---|---| |`success` |Boolean |任务是否成功。

* `true`：成功。请查看 `result` 字段以获取任务结果。

* `false`：失败。请查看 `error` 字段以获取详细错误信息。 | |`result` |Object |包含图像处理结果的对象，仅在 `success` 为 `true` 时返回。详见下文 [Result 对象](https://docs.volcengine.com/docs/6448/2515371#93b2c555)。 | |`error` |Object |错误详情对象，仅在 `success` 为 `false` 时返回。详见下文 [Error 对象](https://docs.volcengine.com/docs/6448/2515371#7de35ab4)。 | |`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`。关于各错误码的详细信息，请参阅[错误码](https://docs.volcengine.com/docs/6448/2300662)。 | |`type` |String |错误的宏观类型。例如：BadRequest。 | |`message` |String |对错误的详细描述，可用于开发调试。 | ### 响应示例成功响应示例： ```JSON { "success": true, "task_id": "amk-tool-crop-image-1234567", "task_type": "crop-image", "result": { "image_url": "https://example.volcvideo.com/cropped_output.png?auth_key=1775271661-...", "image_size": 188080, "image_format": "png", "image_width": 300, "image_height": 200 }, "expires_at": 1778573984, "request_id": "021778401180935fdbd0ff1ce00652c087a478b3f62d63b5dbf0f", "queue_id": "q2a028fa533b7fe6a25b018dccd6284" } ``` 失败响应示例： ```JSON { "success":false, "task_id":"amk-tool-crop-image-940034677250", "task_type": "crop-image", "error":{ "code":"InvalidParameter", "type":"BadRequest", "message":"validating root: required: missing properties: [\"image_url\"]" }, "request_id":"202607291022287DC463A3C5D182BCEE73", "queue_id": "q2a028fa533b7fe6a25b018dccd6284" } ``` ####