本指南介绍 AI MediaKit 提供的一系列同步图像基础编辑工具，涵盖空间几何变换（旋转/翻转/裁剪）、视觉风格调整（锐化/模糊/打码）等。 ## 工具说明 AI MediaKit 提供一系列同步的图像基础编辑 API，调用后可直接在响应体中获取处理结果。 |工具名称 |API 参考 |说明 | |---|---|---| |圆角矩形 |[提交圆角矩形任务 API](https://docs.volcengine.com/docs/6448/2488160) |为图像四角添加正圆或椭圆形的圆角效果。 | |图像旋转 |[提交图像旋转任务 API](https://docs.volcengine.com/docs/6448/2484440) |按指定角度逆时针旋转图像，并可设置空白区域的填充色。 | |图像翻转 |[提交图像翻转任务 API](https://docs.volcengine.com/docs/6448/2484441) |对图像进行水平（左右镜像）或垂直（上下翻转）的翻转。 | |图像锐化 |[提交图像锐化任务 API](https://docs.volcengine.com/docs/6448/2484443) |增强图像的边缘细节与整体清晰度，提供三档强度可选。 | |图像高斯模糊 |[提交图像高斯模糊任务 API](https://docs.volcengine.com/docs/6448/2488166) |对图像进行高斯模糊处理，支持自定义模糊强度。 | |图像打码 |[提交图像打码任务 API](https://docs.volcengine.com/docs/6448/2488164) |对全图或指定矩形区域应用马赛克，可自定义像素格形状与大小。 | |添加图文水印 |[提交图像添加图文水印任务 API](https://docs.volcengine.com/docs/6448/2488163) |在图像上添加文字或图片水印，支持九宫格定位、平铺、透明度等多种自定义设置。 | |图像调整 |[提交图像调整任务 API](https://docs.volcengine.com/docs/6448/2488159) |调整图像的亮度、对比度和饱和度，提供调亮/调暗、增强/减弱对比度、增强/减弱饱和度等效果。 | |图像裁剪 |[提交图像裁剪任务 API](https://docs.volcengine.com/docs/6448/2515371) |对输入图像进行多模式裁剪，包括方向裁剪、定向裁剪、自定义裁剪与内切圆裁剪。 | |图像压缩 |[提交图像压缩任务 API](https://docs.volcengine.com/docs/6448/2515369) |提供一站式图像体积优化方案，支持指定压缩质量、文件体积上限、输出格式转换等。 | |图像缩放 |[提交图像缩放任务 API](https://docs.volcengine.com/docs/6448/2488158) |按指定尺寸或缩放比例对图像进行放大或缩小，支持多种缩放模式。 | |图像负片 |[提交图像负片任务 API](https://docs.volcengine.com/docs/6448/2515368) |将图像的颜色反转，一键生成底片风格的艺术效果。 | |获取图像元信息 |[提交图像元信息获取任务 API](https://docs.volcengine.com/docs/6448/2484301) |查询图像的基础元数据、主题色、透明通道及 BlurHash 等信息。 | ## 准备工作 * **获取访问凭证**：在开始之前，访问 AI MediaKit 控制台 [API Key 管理页面](https://console.volcengine.com/imp/ai-mediakit/settings)，创建并获取 **AI MediaKit API Key**（用于媒体处理功能鉴权）。 * **准备图像文件**：准备一张待处理的图像，并将其上传至公网可访问的服务器或[视频点播服务](https://www.volcengine.com/docs/4/2834?lang=zh)中，以获取可供 API 调用的 URL。 ## 圆角矩形圆角矩形工具可为图像四角添加正圆或椭圆形的圆角效果，适用于头像、卡片、电商主图等场景。 ### 效果预览 |类型 |效果 | |---|---| |圆角为正圆 |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/3bf52f7099484761bdd86ff7b4d55ded) | |圆角为椭圆 |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/2a34974236e246c2bf9f1b6dd61663be) | ### 快速体验：为图片添加半径为 50px 的正圆圆角您需要调用[提交圆角矩形任务 API](https://docs.volcengine.com/docs/6448/2488160)。可直接复制以下 cURL 命令提交任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/round-corner-image' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/input_image.png", "corner_type": "circle", "circle_radius": 50, "output_format": "png" }' ```

说明

将 {Your_API_Key} 替换为您的有效 API Key。

将 image_url 替换为您真实的图片地址。

由于是同步接口，请求成功后，您会直接在响应中收到包含处理结果的响应。您可以从 `result.image_url` 字段获取圆角化处理后图片的下载地址（有效期为 24 小时）。响应示例如下： ```JSON { "success": true, "task_id": "amk-tool-round-corner-image-12345", "result": { "image_url": "https://example.volcvideo.com/rounded_output.png?auth_key=...", "image_size": 98765, "image_format": "png", "image_width": 800, "image_height": 600 }, "request_id": "20240521..." } ``` ## 图像旋转图像旋转工具可将图片按指定角度逆时针旋转图像，并支持设置空白区域的填充色，适用于校正图片方向或进行创意编辑。 ### 效果预览 |原图 |将原图旋转 180 度 |将原图旋转 60 度，指定不规则区域填充色为白色 | |---|---|---| |![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_1f7921f0d3ed3dcea5c248d84bb23b55.jpeg) |![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_0304ba5af54502b48030305e3b06a3e5.png) |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/fae9133967f64a19992b98ba0f3524db) | ### 快速体验：图像逆时针旋转 90 度，并将空白区域填充为白色您需要调用[提交图像旋转任务 API](https://docs.volcengine.com/docs/6448/2484440)。可直接复制以下 cURL 命令提交任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/rotate-image' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/input_image.jpg", "rotate_angle": 90, "fill_color": "White", "output_format": "png" }' ```

说明

将 {Your_API_Key} 替换为您的有效 API Key。

将 image_url 替换为您真实的图片地址。

由于是同步接口，请求成功后，您会直接在响应中收到包含处理结果的响应。您可以从 `result.image_url` 字段获取旋转处理后图片的下载地址（有效期为 24 小时）。响应示例如下： ```JSON { "success": true, "task_id": "amk-tool-rotate-image-12346", "result": { "image_url": "https://example.volcvideo.com/rotated_output.png?auth_key=...", "image_size": 102480, "image_format": "png", "image_width": 600, "image_height": 800 }, "request_id": "20240521..." } ``` ## 图像翻转图像翻转工具可将图片进行水平或垂直翻转，适用于图像纠偏、素材镜像加工等场景。 ### 效果预览 |原图 |水平翻转 |竖直反转 | |---|---|---| |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/12c6aaa942f944a4b511df7731507ecd) |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/52ba6a4aa30745b3930d87b856ebdc95) |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/134be674bb6e417aaa0ca1092030f925) | ### 快速体验：图像水平翻转您需要调用[提交图像翻转任务 API](https://docs.volcengine.com/docs/6448/2484441)。可直接复制以下 cURL 命令提交任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/flip-image' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/input_image.jpg", "flip_type": "horizontal", "output_format": "jpeg" }' ```

说明

将 {Your_API_Key} 替换为您的有效 API Key。

将 image_url 替换为您真实的图片地址。

翻转模式支持以下两种：

horizontal：水平翻转（左右镜像）。

vertical：垂直翻转（上下翻转）。

由于是同步接口，请求成功后，您会直接在响应中收到包含处理结果的响应。您可以从 `result.image_url` 字段获取翻转处理后图片的下载地址（有效期为 24 小时）。响应示例如下： ```JSON { "success": true, "task_id": "amk-tool-flip-image-12347", "result": { "image_url": "https://example.volcvideo.com/flipped_output.jpeg?auth_key=...", "image_size": 85432, "image_format": "jpeg", "image_width": 800, "image_height": 600 }, "request_id": "20240521..." } ``` ## 图像锐化该功能可以提升图像的清晰度，使细节更加突出。 ### 效果预览 |原图 |中度锐化 | |---|---| |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/c81863e069db422e94c7c33fd540a7ce) |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/f5adf69ed8494bea9bbd58ca66c69b0a) | ### 快速体验：对图像执行中等强度的锐化您需要调用[提交图像锐化任务 API](https://docs.volcengine.com/docs/6448/2484443)。可直接复制以下 cURL 命令提交任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/sharpen-image' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/input_image.jpg", "sharpen_level": "medium", "output_format": "jpeg" }' ```

说明

将 {Your_API_Key} 替换为您的有效 API Key。

将 image_url 替换为您真实的图片地址。

通过 sharpen_level 参数控制锐化强度：

low：轻度锐化（默认）

medium：中度锐化

high：重度锐化

由于是同步接口，请求成功后，您会直接在响应中收到包含处理结果的响应。您可以从 `result.image_url` 字段获取锐化处理后图片的下载地址（有效期为 24 小时）。响应示例如下： ```JSON { "success": true, "task_id": "amk-tool-sharpen-image-12348", "result": { "image_url": "https://example.volcvideo.com/sharpened_output.jpeg?auth_key=...", "image_size": 95123, "image_format": "jpeg", "image_width": 800, "image_height": 600 }, "request_id": "20240521..." } ``` ## 图像高斯模糊该功能可对整张图片应用高斯模糊效果，常用于背景虚化或信息弱化。 ### 效果预览 |原图 |轻度模糊 |中度模糊 | |---|---|---| |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/4f491cfd2b2d4b2d9c0264aed6cc3ed9) |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/32bc01632a7e4a76be54fb15766b3175) |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/deb8f3b73e484583b7742bd62ede6d9e) | ### 快速体验：对图像应用中等强度的高斯模糊您需要调用[提交图像高斯模糊任务 API](https://docs.volcengine.com/docs/6448/2488166)。可直接复制以下 cURL 命令提交任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/gaussian-blur-image' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/input_image.jpg", "blur_strength": 30, "output_format": "jpeg" }' ```

说明

将 {Your_API_Key} 替换为您的有效 API Key。

将 image_url 替换为您真实的图片地址。

通过 blur_strength 参数控制高斯模糊强度，数值越大，模糊效果越明显。推荐以下参考值：

10：轻度模糊

30：中度模糊

100：重度模糊

由于是同步接口，请求成功后，您会直接在响应中收到包含处理结果的响应。您可以从 `result.image_url` 字段获取高斯模糊处理后图片的下载地址（有效期为 24 小时）。响应示例如下： ```JSON { "success": true, "task_id": "amk-tool-gaussian-blur-image-12349", "result": { "image_url": "https://example.volcvideo.com/blurred_output.jpeg?auth_key=...", "image_size": 79854, "image_format": "jpeg", "image_width": 800, "image_height": 600 }, "request_id": "20240521..." } ``` ## 图像打码该功能可以对图片进行马赛克处理，支持全图或指定区域打码。 ### 效果预览 |原图 |局部打码效果图 | |---|---| |![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d420057390d6f8bbcdf74c6fe6330c91.png) |![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b54ce98c35a293f2efe9221fb9b08834.png) | ### 快速体验：对指定坐标的矩形区域应用马赛克您需要调用[提交图像打码任务 API](https://docs.volcengine.com/docs/6448/2488164)。可直接复制以下 cURL 命令提交任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/mosaic-image' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/privacy_image.jpg", "mosaic_type": "specify-region", "mosaic_regions": [ { "top_left_x": 100, "top_left_y": 150, "bottom_right_x": 300, "bottom_right_y": 250 } ], "mosaic_shape": "rectangle", "mosaic_step_x": 16, "mosaic_step_y": 16, "output_format": "jpeg" }' ```

说明

将 {Your_API_Key} 替换为您的有效 API Key。

将 image_url 替换为您真实的图片地址。

打码范围：通过 mosaic_type 选择 full-image（全图）或 specify-region（指定区域）。

像素格形状：通过 mosaic_shape 选择 circle（圆形）或 rectangle（矩形）。

颗粒大小：通过 mosaic_step_x 和 mosaic_step_y 控制马赛克像素格的宽高，数值越大颗粒感越强。

由于是同步接口，请求成功后，您会直接在响应中收到包含处理结果的响应。您可以从 `result.image_url` 字段获取打码处理后图片的下载地址（有效期为 24 小时）。响应示例如下： ```JSON { "success": true, "task_id": "amk-tool-mosaic-image-12350", "result": { "image_url": "https://example.volcvideo.com/mosaicked_output.jpeg?auth_key=...", "image_size": 88765, "image_format": "jpeg", "image_width": 800, "image_height": 600 }, "request_id": "20240521..." } ``` ## 添加图文水印添加图文水印工具支持在图像的任意位置添加文字或图片水印，可自定义水印的内容、字体、大小、颜色、透明度、位置、偏移量，并支持平铺水印模式，适用于版权保护、品牌宣传、素材防盗等多种场景。 ### 快速体验：在图片右下角添加半透明的红色文字水印您需要调用[提交图像添加图文水印任务 API](https://docs.volcengine.com/docs/6448/2488163)。可直接复制以下 cURL 命令提交任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/add-image-watermark' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/background.jpg", "watermark_type": "text", "watermark_text": "© MyBrand", "watermark_text_font_size": 24, "watermark_text_color": "#FF0000", "watermark_text_opacity": 50, "watermark_position": "bottom_right", "watermark_position_offset_x": 20, "watermark_position_offset_y": 20 }' ```

说明

将 {Your_API_Key} 替换为您的有效 API Key。

将 image_url 替换为您真实的图片地址。

通过 watermark_type 参数指定水印类型，text 为文字水印，image 为图片水印。更多参数请参阅 API 文档。

由于是同步接口，请求成功后，您会直接在响应中收到包含处理结果的响应。您可以从 `result.image_url` 字段获取添加水印后图片的下载地址（有效期为 24 小时）。响应示例如下： ```JSON { "success": true, "task_id": "amk-tool-add-image-watermark-1234567", "result": { "image_url": "https://example.volcvideo.com/watermarked_output.jpeg?auth_key=1775271661-...", "image_size": 310450, "image_format": "jpeg", "image_width": 1920, "image_height": 1080 }, "request_id": "021778401180935fdbd0ff1ce00652c087a478b3f62d63b5dbf0f" } ``` ## 图像调整该功能用于调整图像的视觉风格，支持对亮度、对比度和饱和度进行增强或减弱，以满足素材优化或艺术化处理的需求。 ### 效果预览 |原图 |效果图 || |---|---|---| |

|**亮度** || ||调亮 |调暗 | ||![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/6cf66b4376254d7a99b65b764cb67d05) |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/de503fc5a1e1464098950a1ebd86d819) | ||**对比度** || ||增强对比度 |减弱对比度 | ||![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/af9dc01f9f9b483d87e3ccc2e84eb6a9) |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/a5937d8efefa47e7b3c6bbd514fc8239) | ||**饱和度** || ||增强饱和度 |减弱饱和度 | ||![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/31988ace0adb4adaa64bc952b1d3dab9) |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/eb10532f061147ff8f9b57cffa5e3c28) | ### 快速体验：对图像执行增强对比度操作您需要调用[提交图像调整任务 API](https://docs.volcengine.com/docs/6448/2488159)。可直接复制以下 cURL 命令提交任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/adjust-image-color' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/input_image.png", "adjust_type": "increase_contrast", "output_format": "jpeg" }' ```

说明

将 {Your_API_Key} 替换为您的有效 API Key。

将 image_url 替换为您真实的图片地址。

通过 adjust_type 参数选择调整类型，例如 increase_brightness（调亮）、decrease_saturation（减弱饱和度）等。

由于是同步接口，请求成功后，您会直接在响应中收到包含处理结果的响应。您可以从 `result.image_url` 字段获取调整后图片的下载地址（有效期为 24 小时）。响应示例如下： ```JSON { "success": true, "task_id": "amk-tooladjust-image-color-1234567", "result": { "image_url": "https://example.volcvideo.com/adjusted_output.jpeg?auth_key=1775271661-...", "image_size": 245310, "image_format": "jpeg", "image_width": 1280, "image_height": 720 }, "request_id": "021778401180935fdbd0ff1ce00652c087a478b3f62d63b5dbf0f" } ``` ## 图像缩放该功能支持按指定尺寸或比例对图像进行放大或缩小，可应用于生成多规格缩略图、内容合规性检查前的尺寸预处理等场景。 ### 缩放模式说明当您同时指定 `resize_long` 和 `resize_short` 时，由 `resize_mode` 参数控制图像如何缩放至 `resize_long` × `resize_short` 的目标矩形。以下示例均以 500×300（宽高比 5:3）的原图和 350×240 的目标矩形为例。 |缩放模式 |说明 |示例 | |---|---|---| |`exact` |**强制缩放**。将图像精确缩放到目标尺寸。该方式不保持原图宽高比，可能导致图像拉伸或压缩变形。 |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/3a136b6886a441ae8a64e83a65d8d0f5)

将 500×300 原图强制缩放为 350×240。由于宽、高按不同比例缩放，图像发生变形。 | |`contain`（默认） |**等比缩放（完整包含）** 。保持原图宽高比进行缩放，使图像完整地被包含在目标矩形内。最终图像的宽、高均不超过目标值，因此某一边可能小于矩形。 |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/cca1161b62f945af8c3e4de8139494ef)

按 0.70× 等比缩放使长边匹配 350，结果图为 350×210，完整包含在 350×240 矩形内，无裁剪。 | |`cover` |**等比缩放（裁剪填充）** 。保持原图宽高比进行缩放，使图像完全填满目标矩形，再将超出的部分居中裁剪。最终图像尺寸恰好等于目标尺寸。 |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/d247a264f4fa4aaeaa03e69f6e69e26d)

按 0.80× 等比缩放为 400×240 以填满矩形，再将水平方向多出的 50px 居中裁剪，最终图像为 350×240。 | ### 快速体验：将图像按比例缩放至宽度为 200px 您需要调用[提交图像缩放任务 API](https://docs.volcengine.com/docs/6448/2488158)。可直接复制以下 cURL 命令提交任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/resize-image' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/input_image.jpg", "width": 200 }' ```

说明

将 {Your_API_Key} 替换为您的有效 API Key。

将 image_url 替换为您真实的图片地址。

支持通过 width、height 或 scale 参数进行缩放。若只指定宽度或高度，将默认等比缩放。

由于是同步接口，请求成功后，您会直接在响应中收到包含处理结果的响应。您可以从 `result.image_url` 字段获取缩放后图片的下载地址（有效期为 24 小时）。响应示例如下： ```JSON { "success": true, "task_id": "amk-tool-resize-image-12345", "result": { "image_url": "https://example.volcvideo.com/scaled_output.jpeg?auth_key=...", "image_size": 25432, "image_format": "jpeg", "image_width": 200, "image_height": 150 }, "request_id": "20240521..." } ``` ## 图像负片图像负片工具可将输入图像的所有颜色进行反转，一键生成具有底片风格的艺术效果，适用于创意视觉、内容二次创作等场景。 ### 效果预览 |原图 |负片效果 | |---|---| |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/1d5fab2918d54cd58747a2342568a243) |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/89456e32436549069e955d6754185ef1) | ### 快速体验：一键生成图像负片效果您需要调用[提交图像负片任务 API](https://docs.volcengine.com/docs/6448/2515368) 。该功能无需配置复杂的参数，可直接复制以下 cURL 命令提交任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/invert-image' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/input_image.jpg" }' ```

说明

将 {Your_API_Key} 替换为您的有效 API Key。

将 image_url 替换为您真实的图片地址。

您还可以通过可选的 output_format 参数指定输出格式（如 webp）。

由于是同步接口，请求成功后，您会直接在响应中收到包含处理结果的响应。您可以从 `result.image_url` 字段获取负片处理后图片的下载地址（有效期为 24 小时）。响应示例如下： ```JSON { "success": true, "task_id": "amk-tool-invert-image-1234567", "result": { "image_url": "https://example.volcvideo.com/inverted_output.jpg?auth_key=1775271661-...", "image_size": 910234, "image_format": "jpeg", "image_width": 1920, "image_height": 1080 }, "request_id": "021778401180935fdbd0ff1ce00652c087a478b3f62d63b5dbf0f", "expires_at": 1775271661 } ``` ## 图像裁剪图像裁剪工具可对输入图像进行多模式裁剪，包括方向裁剪、定向裁剪、自定义裁剪与内切圆裁剪，适用于多端尺寸适配、主体保留、商品图去边以及指定区域截取等多种场景。 ### 裁剪模式说明通过 `crop_mode` 参数，您可以选择以下四种裁剪模式之一： #### 方向裁剪 (`crop_mode: directional`) 根据指定的目标宽高，从图像的特定方位（如居中、顶部、底部等）进行裁剪。此模式常用于生成固定尺寸的视图，同时保留特定方向的画面内容。 * **工作原理**：您需要提供裁剪后图像的目标宽度 (`crop_width`) 和高度 (`crop_height`)，并指定一个裁剪位置 (`crop_position`)。系统会以该位置为基准，从原图中截取相应尺寸的区域。 * **参数说明**： * `crop_width` / `crop_height`：定义裁剪区域的尺寸。若其中一个设为 0，则会按原图比例自适应缩放。 * `crop_position`：裁剪的基准位置，如下图所示。例如，选择 `up` 会优先保留图像顶部内容。 ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/f311c97b43044c89b153dd25dea2308d) * **示例**：以下示例将基于一张 1024x684 像素的原图进行演示。 |**场景** |**请求参数设置** |**效果图** | |---|---|---| |**居中裁剪，生成方形缩略图：** 将原图从中心区域裁剪为一个 600x600 像素的方形图片。 |* `"crop_position": "center"`

* `"crop_width": 600`

* `"crop_height": 600` |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/a14643a0de524cfd86d1b358883514fd) | |**居上裁剪，保留顶部内容：** 从原图顶部开始，裁剪一个 600x300 像素的矩形，常用于制作横幅或标题图。 |* `"crop_position": "up"`

* `"crop_width": 600`

* `"crop_height": 300` |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/f2b46ae73ede4d5a83486eaa9d2d3e3f) | |**居右裁剪，仅指定宽度：** 从原图右侧开始，裁剪出一个宽度为 600 像素的图片，高度保持不变。 |* `"crop_position": "right"`

* `"crop_width": 600`

* `crop_height` 不传或设为 0。 |![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/1e28fa64241048bfa4404197401c6192) | #### 定向裁剪 (`crop_mode: origin`) 此模式提供最灵活的控制。您可以先在图像上设定一个锚点（九宫格之一），然后基于该锚点进行水平和垂直偏移，最后从偏移后的新起点开始截取指定宽高的矩形区域。 * **工作原理**：通过锚点 (`origin_gravity`)、偏移量 (`origin_x`, `origin_y`) 和目标尺寸 (`crop_width`, `crop_height`) 精准定义裁剪框。 ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/c296f5f2e0974a75a6f745c4ad24601e) * **示例**：下图演示了将裁剪锚点设置在左上角 (`northwest`)，然后水平向右偏移 100px、垂直向下偏移 200px，最后从新起点 (100, 200) 截取一个 600x400 px 的区域。 ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/6068277ec72c4fd5ab61c267ae5791cf) #### 自定义裁剪 (`crop_mode: custom`) 通过直接指定裁剪区域左上角和右下角的坐标来定义一个矩形进行裁剪。坐标原点 (0, 0) 为图像的左上角。 * **工作原理**：使用 `custom_x1`, `custom_y1` 定义裁剪框的左上角坐标，使用 `custom_x2`, `custom_y2` 定义右下角坐标。 * **示例**：下图演示了截取由左上角坐标 (100, 40) 和右下角坐标 (400, 400) 所限定的矩形区域。裁剪后的图像尺寸为 300x360 px。 ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/9e926745a50d42dbb6c26dd1b091ad94) #### 内切圆裁剪 (`crop_mode: circle`) 自动将图像裁剪为以其中心为圆心、以短边为直径的最大内切圆形。 * **工作原理**：此模式下无需配置其他裁剪参数，系统会自动计算并裁剪出最大内切圆。 * **输出格式建议**：为确保圆形外的区域透明，建议将输出格式 (`output_format`) 设置为 `png` 或 `webp`。如果输出为 `jpeg`，非圆形区域将被默认填充为白色。 ![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/51387a114b50455688cabd45afe83ee3) ### 快速体验：自定义裁剪图像指定区域您需要调用[提交图像裁剪任务 API](https://docs.volcengine.com/docs/6448/2515371)。以下示例演示了如何截取由左上角坐标 (100, 150) 和右下角坐标 (400, 350) 限定的矩形区域。可直接复制以下 cURL 命令提交任务。 ```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" }' ```

说明

将 {Your_API_Key} 替换为您的有效 API Key。

将 image_url 替换为您真实的图片地址。

通过 crop_mode 参数选择裁剪模式。示例中使用的 custom 表示根据指定的左上角和右下角坐标进行裁剪。

由于是同步接口，请求成功后，您会直接在响应中收到包含处理结果的响应。您可以从 result.image_url 字段获取裁剪后图片的下载地址（有效期为 24 小时）。响应示例如下： ```JSON { "success": true, "task_id": "amk-tool-crop-image-1234567", "result": { "image_url": "https://example.volcvideo.com/cropped_output.png?auth_key=...", "image_size": 188080, "image_format": "png", "image_width": 300, "image_height": 200 }, "request_id": "20240521..." } ``` ## 图像压缩图像压缩工具提供一站式的图像体积优化方案，支持指定压缩质量、文件体积上限、输出格式转换（如 WebP, AVIF, HEIC），适用于网站与 App 的图片分发加载优化、用户上传图片治理等场景。 ### 快速体验：将图片压缩为 WebP 格式您需要调用[提交图像压缩任务 API](https://docs.volcengine.com/docs/6448/2515369)。以下示例演示了如何将一张图片压缩并转换为 WebP 格式，同时指定压缩质量为 80。可直接复制以下 cURL 命令提交任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/compress-image' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/large_image.png", "output_format": "webp", "quality": 80 }' ```

说明

将 {Your_API_Key} 替换为您的有效 API Key。

将 image_url 替换为您真实的图片地址。

通过 quality 参数指定压缩质量（1\-100），或通过 max_size 参数指定文件体积上限。两者同时设置时，max_size 优先。

由于是同步接口，请求成功后，您会直接在响应中收到包含处理结果的响应。您可以从 result.image_url 字段获取压缩后图片的下载地址（有效期为 24 小时）。响应示例如下： ```JSON { "success": true, "task_id": "amk-tool-compress-image-1234567", "result": { "image_url": "https://example.volcvideo.com/compressed_output.webp?auth_key=...", "image_size": 98765, "image_format": "webp", "image_width": 1920, "image_height": 1080 }, "request_id": "20240521..." } ``` ## 获取图像元信息获取图像元信息工具可用于查询图像的基础元数据（如尺寸、格式、AIGC 信息）、提取主题色、分析透明通道以及生成 BlurHash 预览图，广泛应用于素材管理、元数据识别、UI 自适应配色等多种场景。您通过 `info_type` 参数指定查询的信息类型，不同类型会返回不同的结果。 * `metadata`：获取图像的基础元数据，包括尺寸、格式、大小、MD5、色彩模型、帧数（动图）、时长（动图）、AIGC 元数据等。 * `avghue`：提取图像的主题色，返回一个十六进制颜色值（如 `#3B5998`）。 * `alpha`：分析图像的 Alpha 透明通道，返回是否包含透明通道、透明像素占比等信息。 * `blurhash`：生成图像的 BlurHash 字符串，用于实现低成本、高性能的图片加载占位符。 ### 快速体验：获取一张图片的基础元数据您需要调用[提交图像元信息获取任务 API](https://docs.volcengine.com/docs/6448/2484301)。可直接复制以下 cURL 命令提交任务。 ```Bash curl -X POST 'https://mediakit.cn-beijing.volces.com/api/v1/tools-sync/probe-image-metadata' \ -H 'Authorization: Bearer {Your_API_Key}' \ -H 'Content-Type: application/json' \ -d '{ "image_url": "https://example.com/your_image.jpg", "info_type": "metadata" }' ```

说明

将 {Your_API_Key} 替换为您的有效 API Key。

将 image_url 替换为您真实的图片地址。

由于是同步接口，请求成功后，您会直接在响应中收到包含元数据信息的 JSON 结果。响应示例如下： ```JSON { "success": true, "task_id": "amk-tool-probe-image-metadata-123456", "result": { "width": 1920, "height": 1080, "format": "jpeg", "size": 256000, "md5": "d41d8cd98f00b204e9800998ecf8427e", "frame_count": 1, "color_model": "gray", "orientation": 0, "quality": 75, "exif": null, "aigc": null }, "request_id": "20240523100000AABBCCDDEEFF001122" } ``` ## 圆角矩形 ## 参考信息 ### 使用限制所有图像基础编辑工具均遵循以下统一的输入限制： |限制项 |说明 | |---|---| |图像来源 |支持公网 HTTP/HTTPS URL、本地上传 (`mediakit://`)、火山引擎对象存储 (`tos://`) 三种输入协议。关于各协议的具体说明和使用示例，请参阅[多源媒体输入与本地上传](https://docs.volcengine.com/docs/6448/2536893)。 | |文件大小 |建议单张图片不超过 35 MB。过大文件可能导致处理超时或失败。 | |输入分辨率 |图像的宽度和高度均不得超过 10000 像素。 | |支持格式 |支持 `.png`、`.jpg`、`.jpeg`、`.webp` 等主流图像格式。不支持处理动图。 |