volcengine/mediakit-cli已通過檢查
SKILL DETAIL
byted-mediakit-image
volcengine/mediakit-cli/byted-mediakit-image
面向单张或批量图片的视觉处理、质量优化、内容理解与基础编辑目标，适用于图片尺寸缩放与体积治理、元信息探测、裁剪旋转翻转与圆角、颜色与锐化清晰度调整、负片、模糊与打码、水印、背景移除、文字识别、画质评估与智能裁剪等。若对象和目标族已明确属于图片优化、图片理解或图片隐私保护，但具体做法不确定，可先加载本 Skill 探索。
安裝量 · 324查看來源
Installation
npx skills add https://github.com/volcengine/mediakit-cli --skill byted-mediakit-image
技能檔案
SKILL.md
最近同步 · 2026年9月11日
LICENSE›
# The MIT License (MIT)
Copyright © 2025 Beijing Volcano Engine Technology Ltd.
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWAREreference/add-image-watermark.md›
# 添加图文水印
## 能力用途
为图片添加图文明水印，适用于版权标识与素材分发防盗链场景。
## 参数填写规则
- 提交一张公网可访问图片 URL，并配置文字或图片水印。watermark_type=image 时必须提供 watermark_image_url；watermark_type=text 时建议提供 watermark_text。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image add-image-watermark`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 使用指南
- 布尔参数（`--enable-tile`）只能写成 `--enable-tile=true` 或 `--enable-tile=false`，也可用裸 `--enable-tile`（等价 true）；禁止空格传值 `--enable-tile true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image add-image-watermark \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `enable_tile` | `--enable-tile` | boolean | 否 | false | - | 默认 false。开启后水印将以固定的间距重复平铺在整个图片上；对于文字水印，会额外应用逆时针 30 度的旋转；对于图片水印，仅进行平铺，不应用旋转。 |
| `image_url` | `--image-url` | string | 是 | - | - | 待处理的图片 URL，支持公网 HTTP/HTTPS URL、本地文件路径、对象存储 tos:// 三种输入协议；仅支持处理静图；建议单张图片不超过 35 MB；支持 .png、.jpg、.jpeg、.webp 等主流图像格式；输入图片宽和高均不得超过 10000 像素。 |
| `output_format` | `--output-format` | string | 否 | "original" | 枚举: ["original","png","jpeg","webp"] | 输出图片格式可为 original、png、jpeg、webp；original 表示保持与原图一致的格式；默认 original。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `watermark_image_opacity` | `--watermark-image-opacity` | integer | 否 | 100 | 最小值: 0；最大值: 100 | 图片水印透明度范围为 [0,100]；值越小越透明；默认 100。 |
| `watermark_image_url` | `--watermark-image-url` | string | 否 | - | - | 图片水印的 URL，必须为公网可访问的 HTTP 或 HTTPS URL；不是无条件必填；建议不超过 5 MB；支持 .jpg、.jpeg、.webp 等常见图像格式。 |
| `watermark_position` | `--watermark-position` | string | 否 | "bottom_right" | 枚举: ["top_left","top_right","bottom_left","bottom_right","left_center","right_center","top_center","bottom_center","center"] | 水印在图片上的九宫格布局位置，可为 top_left、top_center、top_right、left_center、center、right_center、bottom_left、bottom_center、bottom_right；默认 bottom_right；当使用包含 center 的值时，watermark_position_offset_x 和 watermark_position_offset_y 将不生效。 |
| `watermark_position_offset_x` | `--watermark-position-offset-x` | integer | 否 | 0 | 最小值: 0 | 水印在 watermark_position 基础上沿 X 轴的微调距离，单位为像素；默认 0；仅在 watermark_position 取值不包含 center 时生效。 |
| `watermark_position_offset_y` | `--watermark-position-offset-y` | integer | 否 | 0 | 最小值: 0 | 水印在 watermark_position 基础上沿 Y 轴的微调距离，单位为像素；默认 0；仅在 watermark_position 取值不包含 center 时生效。 |
| `watermark_text` | `--watermark-text` | string | 否 | - | 最长长度: 64 | 水印文字内容，不是无条件必填。 |
| `watermark_text_color` | `--watermark-text-color` | string | 否 | "#FFFFFF" | 格式: "^#[0-9a-fA-F]{6}$" | 文字颜色支持十六进制、RGB 等格式；默认 #FFFFFF。 |
| `watermark_text_font` | `--watermark-text-font` | string | 否 | "SourceHanSans-Regular.ttf" | 枚举: ["SourceHanSans-Regular.ttf","SourceHanSans-Bold.ttf","SourceHanSans-ExtraLight.ttf","SourceHanSans-Heavy.ttf","SourceHanSans-Light.ttf","SourceHanSans-Medium.ttf","SourceHanSans-Normal.ttf","SourceHanSerifCN-Regular.ttf","SourceHanSerifCN-Bold.ttf","SourceHanSerifCN-ExtraLight.ttf","SourceHanSerifCN-Heavy.ttf","SourceHanSerifCN-Light.ttf","SourceHanSerifCN-SemiBold.ttf","zcool-heiti.ttf","zcool_gaoduanhei.ttf","zcool_kuaileti.ttf","zcool_huangyou.ttf","FZLTHK.TTF"] | 文字字体支持思源黑体、思源宋体、站酷、方正兰亭黑等系列字体；默认 SourceHanSans-Regular.ttf（思源黑体）。 |
| `watermark_text_font_size` | `--watermark-text-font-size` | integer | 否 | 30 | 最小值: 1；最大值: 200 | 文字字号单位为像素；默认 30。 |
| `watermark_text_opacity` | `--watermark-text-opacity` | integer | 否 | 30 | 最小值: 0；最大值: 100 | 文字水印透明度范围为 [0,100]；值越小越透明；默认 30。 |
| `watermark_type` | `--watermark-type` | string | 否 | "text" | 枚举: ["text","image"] | 水印类型可为 text 和 image；text 表示文字水印，image 表示图片水印；默认 text。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | 生成图像的格式。 |
| `image_height` | integer | 否 | Cloud | 生成图像的高度，单位 px。 |
| `image_size` | integer | 否 | Cloud | 生成图像的大小，单位字节。 |
| `image_url` | string | 否 | Cloud | 处理后的图片文件下载地址，有效期为 24 小时。 |
| `image_width` | integer | 否 | Cloud | 生成图像的宽度，单位 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image add-image-watermark --help
mediakit-cli image add-image-watermark --schema
```
reference/adjust-image-color.md›
# 图像调整
## 能力用途
对输入图像的亮度、对比度和饱和度进行调整，支持调亮、调暗、增强对比度、减弱对比度、增强饱和度、减弱饱和度共 6 种快速调整效果。适用于素材基础优化、统一内容视觉风格、营造庄重、复古等特殊氛围等场景。
## 参数填写规则
- 提交一张图片并指定一种图像调整类型。仅支持公网 URL。adjust_type 为单选枚举，6 个值分别对应 6 个预置模板效果，未传 output_format 时默认保持原图格式。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image adjust-image-color`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `adjust_type` | `--adjust-type` | string | 是 | - | 枚举: ["increase_brightness","decrease_brightness","increase_contrast","decrease_contrast","increase_saturation","decrease_saturation"] | 必填的图像调整类型。支持 increase_brightness（调亮）、decrease_brightness（调暗）、increase_contrast（增强对比度）、decrease_contrast（减弱对比度）、increase_saturation（增强饱和度）、decrease_saturation（减弱饱和度）。一次仅支持选择一种效果。 |
| `image_url` | `--image-url` | string | 是 | - | - | 待处理图片，必填。支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎对象存储 tos:// 三种输入协议；支持 .png、.jpg、.jpeg、.webp 等主流图像格式；仅支持处理静图。建议单张图片不超过 35 MB，输入分辨率的宽和高均不得超过 10000 像素。 |
| `output_format` | `--output-format` | string | 否 | "original" | 枚举: ["original","png","jpeg","webp"] | 输出图片格式，可选。支持 original、png、jpeg、webp；original 表示保持与原图一致的格式，默认 original。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image adjust-image-color \
--image-url <image_url> \
--adjust-type <adjust_type>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | 生成图像的格式。 |
| `image_height` | integer | 否 | Cloud | 生成图像的高度，单位为 px。 |
| `image_size` | integer | 否 | Cloud | 生成图像的大小，单位为字节。 |
| `image_url` | string | 否 | Cloud | 处理后的图片文件下载地址，有效期为 24 小时，请务必及时保存产物。 |
| `image_width` | integer | 否 | Cloud | 生成图像的宽度，单位为 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image adjust-image-color --help
mediakit-cli image adjust-image-color --schema
```
reference/compress-image.md›
# 图像压缩
## 能力用途
支持一站式图像体积优化，覆盖压缩质量、文件体积上限、输出格式转换和 PNG 瘦身；适用于用户上传图片前的体积治理；适用于网站与 App 的图片分发加载优化；适用于 AIGC 与多模态模型的媒体预处理。用户明确给出 quality、max_size 或 output_format，要求格式转换，或明确接受 PNG 有损压缩时选择本工具；压缩率提高可能增加画质损失。
## 相近能力选择
缩小图片文件体积时，先读取 [图片体积治理选择指南](families/image-size-reduction.md)，再决定使用 slim-image 或 compress-image。
## 参数填写规则
- 提交一张图片并指定压缩质量、输出体积上限、PNG 瘦身与输出格式。仅支持公网 URL。未传 output_format 时默认 webp。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 与 `slim-image` 的边界：用户强调尽量不掉画质、质量优先或高质量缩小体积，且未要求精确体积上限、质量值或格式转换时，应优先使用 `slim-image`；若只说压缩或变小且无法判断目标，先澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image compress-image`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 使用指南
- 布尔参数（`--png-lossy`）只能写成 `--png-lossy=true` 或 `--png-lossy=false`，也可用裸 `--png-lossy`（等价 true）；禁止空格传值 `--png-lossy true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image compress-image \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `image_url` | `--image-url` | string | 是 | - | - | 待处理图片的 URL。仅支持静图；支持公网 HTTP/HTTPS URL、本地文件路径和火山引擎对象存储 tos:// 三种输入协议；支持 .png、.jpg、.jpeg、.webp 等主流图像格式。建议单张输入图片不超过 35 MB。输入图像的宽和高分别都不得超过 10000 像素。输出为 avif 时，建议输入图像的宽×高不超过 100,000 像素，否则任务可能失败。输出为 heic 时，建议输入图像分辨率不超过 4K（约4096×4096 像素），否则任务可能失败。 |
| `max_size` | `--max-size` | integer | 否 | - | 最小值: 1 | 输出图像的文件体积上限，单位为字节（Byte）。推荐设为 10,485,760 字节（10 MiB）。仅在 output_format 为 jpeg 或 webp 时生效；设置后，系统自动调整压缩参数以尽可能满足体积限制，手动设置的 quality 会被忽略。 |
| `output_format` | `--output-format` | string | 否 | "webp" | 枚举: ["png","jpeg","webp","avif","heic"] | 输出图片格式。支持 png、jpeg、webp、avif、heic；未提供 output_format 时默认使用 webp。若希望保持原图格式，需要显式传入原格式。 |
| `png_lossy` | `--png-lossy` | boolean | 否 | false | - | 可选开启 PNG 图片有损压缩，以获得更高压缩率；仅在 output_format 为 png 时生效；默认为 false。 |
| `quality` | `--quality` | integer | 否 | 75 | 最小值: 1；最大值: 100 | 压缩质量最小值为 1，最大值为 100，默认为 75。quality 越小，压缩率越高且图像质量损失越大。设置 max_size 时，quality 会被忽略。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | 生成图像的格式。 |
| `image_height` | integer | 否 | Cloud | 生成图像的高度，单位为 px。 |
| `image_size` | integer | 否 | Cloud | 生成图像的大小，单位为字节。 |
| `image_url` | string | 否 | Cloud | 处理后图片文件的下载地址，有效期为 24 小时，用户必须及时保存产物。 |
| `image_width` | integer | 否 | Cloud | 生成图像的宽度，单位为 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image compress-image --help
mediakit-cli image compress-image --schema
```
reference/crop-image.md›
# 图像裁剪
## 能力用途
对输入图像进行多模式裁剪，可执行方向裁剪、定向裁剪、自定义裁剪或内切圆裁剪，适用于多端尺寸适配、主体保留、商品图去边和指定区域截取。
## 参数填写规则
- 输入图片并指定裁剪模式。仅支持公网 URL。未传 crop_mode 时默认 directional，且方向裁剪默认位置为 center。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image crop-image`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `crop_height` | `--crop-height` | integer | 否 | - | 最小值: 0 | directional 模式下，crop_height 表示裁剪后图像的目标高度，单位为 px，且 crop_mode 为 directional 时必须提供 crop_height。crop_mode 为 origin 时，crop_height 表示目标高度，单位为 px。crop_height 为 0 时，高度根据 crop_width 按原图比例自适应。 |
| `crop_mode` | `--crop-mode` | string | 否 | "directional" | 枚举: ["directional","origin","custom","circle"] | 支持 directional、origin、custom、circle 四种模式。directional 根据指定宽度、高度和位置进行方向裁剪；origin 根据指定宽高、偏移量和锚点进行定向裁剪；custom 根据指定左上角和右下角坐标进行自定义裁剪；circle 执行最大内切圆裁剪，无需配置其他参数。裁剪模式决定裁剪行为及所需参数，默认 directional。 |
| `crop_position` | `--crop-position` | string | 否 | "center" | 枚举: ["center","up","down","left","right"] | 指定裁剪区域的位置。支持 center、up、down、left、right，分别表示居中、顶部、底部、左侧、右侧，默认 center。 |
| `crop_width` | `--crop-width` | integer | 否 | - | 最小值: 0 | directional 模式下，crop_width 表示裁剪后图像的目标宽度，单位为 px，且 crop_mode 为 directional 时必须提供 crop_width。crop_mode 为 origin 时，crop_width 表示目标宽度，单位为 px。crop_width 为 0 时，宽度根据 crop_height 按原图比例自适应。directional 模式下，crop_width 与 crop_height 不得同时为 0。 |
| `custom_x1` | `--custom-x1` | integer | 否 | - | - | crop_mode 为 custom 时，custom_x1 表示裁剪区域左上角横坐标（X 轴），单位为 px。 |
| `custom_x2` | `--custom-x2` | integer | 否 | - | - | crop_mode 为 custom 时，custom_x2 表示裁剪区域右下角横坐标（X 轴），单位为 px。 |
| `custom_y1` | `--custom-y1` | integer | 否 | - | - | crop_mode 为 custom 时，custom_y1 表示裁剪区域左上角纵坐标（Y 轴），单位为 px。 |
| `custom_y2` | `--custom-y2` | integer | 否 | - | - | crop_mode 为 custom 时，custom_y2 表示裁剪区域右下角纵坐标（Y 轴），单位为 px。 |
| `image_url` | `--image-url` | string | 是 | - | - | 待处理图片的 URL，仅支持处理静图。支持公网 HTTP/HTTPS URL、本地文件路径和火山引擎对象存储 tos:// 三种输入协议，支持 .png、.jpg、.jpeg、.webp 等主流图像格式。建议单张图片不超过 35 MB。crop_mode 为 circle 时，原图最短边不得超过 2048 px。 |
| `origin_gravity` | `--origin-gravity` | string | 否 | "northwest" | 枚举: ["northwest","north","northeast","west","center","east","southwest","south","southeast"] | 指定定向裁剪的锚点（起始点）。支持 northwest、north、northeast、west、center、east、southwest、south、southeast，默认 northwest，表示左上角。 |
| `origin_x` | `--origin-x` | integer | 否 | - | - | crop_mode 为 origin 时，origin_x 表示相对锚点水平偏移量，单位为 px；正值向右，负值向左。 |
| `origin_y` | `--origin-y` | integer | 否 | - | - | crop_mode 为 origin 时，origin_y 表示相对锚点垂直偏移量，单位为 px；正值向下，负值向上。 |
| `output_format` | `--output-format` | string | 否 | "original" | 枚举: ["original","png","jpeg","webp"] | 指定输出图片格式，默认 original，表示保持原图格式。circle 模式下，为确保背景透明，建议输出为 png 或 webp；输出 jpeg 时，非圆形区域填充为白色。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image crop-image \
--image-url <image_url> \
--crop-width <crop_width> \
--crop-height <crop_height>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | 生成图像的格式。 |
| `image_height` | integer | 否 | Cloud | 生成图像的高度，单位为 px。 |
| `image_size` | integer | 否 | Cloud | 生成图像的大小，单位为字节。 |
| `image_url` | string | 否 | Cloud | 处理后图片的下载地址，有效期为 24 小时，请及时保存产物。 |
| `image_width` | integer | 否 | Cloud | 生成图像的宽度，单位为 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image crop-image --help
mediakit-cli image crop-image --schema
```
reference/enhance-image.md›
# 图像画质增强
## 能力用途
基于图像内容理解进行智能决策，提升图片的分辨率、清晰度与色彩表现。
## 参数填写规则
- 必须至少传入 multiple 或 target_width / target_height，指定倍率或宽高。如果同时传入 multiple 和 target_width / target_height，则 multiple 生效。若不设置则默认倍率为2 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image enhance-image`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `image_url` | `--image-url` | string | 是 | - | - | image_url 是待增强图像的 URL，支持公网 HTTP/HTTPS URL、本地文件路径和火山引擎对象存储 tos:// 三种输入协议；单张输入图片不得超过 10 MB；输入和输出尺寸范围随 tool_version 而不同；支持 .png、.jpg、.jpeg、.webp 等常见主流图像格式。 |
| `multiple` | `--multiple` | number | 否 | - | 最小值: 1；最大值: 30 | multiple 为非必选参数，表示图像处理后相对原图的放大倍数，支持 2 位小数；tool_version 为 standard 时，multiple 的范围是 [1, 8]；tool_version 为 professional 时，multiple 的范围是 [1, 30]；最终生成图像的宽度和高度不能超过所选模型版本支持的最大分辨率。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `target_height` | `--target-height` | integer | 否 | - | 最小值: 64；最大值: 10240 | target_height 为非必选参数，表示处理后的目标高度，单位为 px；可选，通常与 target_width 配合使用，也可单独设置以保持原图宽高比；tool_version 为 standard 时，target_height 的范围是 [原图高度, 6144]，且最终放大倍数不能超过 8 倍；tool_version 为 professional 时，target_height 的范围是 [64, 10240]。 |
| `target_width` | `--target-width` | integer | 否 | - | 最小值: 64；最大值: 10240 | target_width 为非必选参数，表示处理后的目标宽度，单位为 px；target_height 与 target_width 可选搭配使用，也可单独设置以保持原图宽高比；tool_version 为 standard 时，target_width 的范围是 [原图宽度, 6144]，且最终放大倍数不能超过 8 倍；tool_version 为 professional 时，target_width 的范围是 [64, 10240]。 |
| `tool_version` | `--tool-version` | string | 否 | "standard" | 枚举: ["standard","professional"] | tool_version 为非必选参数，用于选择画质增强模型版本，不同版本在效果、处理范围和价格上有所差异；默认是 standard；standard 是标准版，平衡处理速度与画质效果；professional 是专业版，提供发丝级画质增强，效果更佳。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image enhance-image \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | tool_version 为 standard 时，输出图像格式固定为 png；tool_version 为 professional 时，输出图像格式与输入图像格式保持一致。 |
| `image_height` | integer | 否 | Cloud | 生成图像的高度，单位为 px。 |
| `image_size` | integer | 否 | Cloud | 生成图像的大小，单位为字节。 |
| `image_url` | string | 否 | Cloud | image_url 是增强后图片文件的下载地址，有效期为 24 小时，必须及时保存产物。 |
| `image_width` | integer | 否 | Cloud | 生成图像的宽度，单位为 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image enhance-image --help
mediakit-cli image enhance-image --schema
```
reference/erase-image.md›
# 图像擦除修复
## 能力用途
可按不同场景控制自动检测并擦除图片中的文字或常见图标，擦除后的区域通过智能填充技术进行修复，修复后的区域与背景自然融合。
## 参数填写规则
- 提交一张公网可访问图片 URL，可选择标准版擦除修复；标准版支持自动检测、bbox、遮罩和文字擦除。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image erase-image`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `image_url` | `--image-url` | string | 是 | - | - | 待处理图像的 URL；图像来源支持公网 HTTP/HTTPS URL、本地文件路径和火山引擎对象存储 tos:// 三种输入协议；输入图像分辨率不得小于 10x10 像素，且不得超过 2560x1440 像素，顺序为宽x高；单张输入图片大小不得超过 10 MB；输入图片支持 .png、.jpg、.jpeg、.webp、.tiff、.bmp 和 .heic 格式。 |
| `output_format` | `--output-format` | string | 否 | "webp" | 枚举: ["png","jpeg","webp"] | 输出图片的格式，支持 webp、png 和 jpeg；默认 webp。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `standard_erase_text` | `--standard-erase-text` | string | 否 | - | - | standard_erase_text 指定需要擦除的文字内容；仅当 standard_scene 为 full_screen_text_erase 时生效；不提供 standard_erase_text 时会擦除识别到的所有文字。 |
| `standard_scene` | `--standard-scene` | string | 否 | "full_screen_text_erase" | 枚举: ["full_screen_text_erase","full_screen_icon_erase"] | standard_scene 表示标准版擦除场景；仅当 tool_version 为 standard 时生效；支持 full_screen_text_erase 和 full_screen_icon_erase；默认 full_screen_text_erase；full_screen_text_erase 表示全屏文字擦除，在 full_screen_text_erase 场景中，可选用 standard_erase_text 指定要擦除的文字，不指定 standard_erase_text 时默认擦除所有文字内容；full_screen_icon_erase 表示全屏图标擦除。 |
| `tool_version` | `--tool-version` | string | 否 | "standard" | 枚举: ["standard"] | 图像擦除修复选用的模型版本；当前仅支持 standard（标准版）；standard 标准版适用于简单、明确的擦除任务。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image erase-image \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | 生成图像的格式。 |
| `image_height` | integer | 否 | Cloud | 生成图像的高度，单位为像素（px）。 |
| `image_size` | integer | 否 | Cloud | 生成图像的大小，单位为字节。 |
| `image_url` | string | 否 | Cloud | 擦除修复后的图片下载 URL，有效期为 24 小时，必须及时保存对应的产物。 |
| `image_width` | integer | 否 | Cloud | 生成图像的宽度，单位为像素（px）。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image erase-image --help
mediakit-cli image erase-image --schema
```
reference/evaluate-image-quality.md›
# 图像画质评估
## 能力用途
用于图像画质评估，对输入图片进行主客观画质和美学评分，适用于质量监控、低质图筛查、内容审核、推荐排序和训练数据清洗。
## 参数填写规则
- 提交一张公网可访问图片 URL，按 tool_version 选择标准版或专业版画质评估。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image evaluate-image-quality`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 使用指南
- 数组参数（`--standard-evaluate-items`）传多个值时用逗号分隔并整体加引号，例如 `--standard-evaluate-items "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image evaluate-image-quality \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `image_url` | `--image-url` | string | 是 | - | - | image_url 是待评估的图像 URL，支持公网 HTTP/HTTPS URL、本地文件路径和火山引擎对象存储 tos:// 三种输入协议，支持 png、jpeg、webp 和 heic 图像格式，单张图片不得超过 10 MB，图像输入分辨率的长边不得超过 7680 px，短边不得超过 4320 px。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `standard_evaluate_items` | `--standard-evaluate-items` | array<string> | 否 | ["vqscore","noise","aesthetic","blur"] | 元素枚举: ["vqscore","advcolor","blockiness","noise","aesthetic","blur","cg","contrast","texture","brightness","overexposure","hue","saturation","green","cmartifacts"] | standard_evaluate_items 为非必填参数，仅当 tool_version 为 standard 时生效，用于指定需要返回的标准版评估维度。standard_evaluate_items 可选 15 个评估维度：vqscore（图片主观质量，值越高表示质量越好）、advcolor（图片整体色彩质量）、blockiness（块效应（马赛克）严重程度）、noise（图片噪声强度）、aesthetic（综合大众美学的质量评分）、blur（模糊度）、cg（是否为非自然场景，如游戏、录屏）、contrast（对比度）、texture（纹理丰富程度）、brightness（平均亮度）、overexposure（过曝光程度）、hue（色调均衡程度）、saturation（饱和度均衡程度）、green（偏绿或绿幕检测）、cmartifacts（压缩失真检测）。standard_evaluate_items 为空时默认返回 vqscore、noise、aesthetic、blur 四个维度。 CLI 传参时可使用逗号分隔多个值，或重复传递该 flag；不要传 JSON 数组字符串。 |
| `tool_version` | `--tool-version` | string | 否 | "standard" | 枚举: ["standard","professional"] | tool_version 用于选择画质评估所用的模型版本，为非必填参数，支持 standard 和 professional，默认为 standard。standard 提供 15 种基础画质评估维度，可通过 standard_evaluate_items 灵活选择部分或全部维度，在成本和功能灵活性上达到较好的平衡。professional 基于大模型进行评估，直接返回一组固定的综合性评分，提供更优的综合评估效果，适用于对图像品质要求较高的场景，且不支持自定义评估维度。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `advcolor` | number | 否 | Cloud | standard 的 advcolor 表示图片整体色彩质量，值越高表示色彩质量越高，取值范围为 0 到 100：[0, 50] 表示色彩质量差，[50, 60] 表示中，[60, 100] 表示好。 |
| `aesthetic` | number | 否 | Cloud | standard 的 aesthetic 表示综合大众美学的质量评分，值越高表示更具美感，取值范围为 0 到 100。 |
| `aesthetics` | number | 否 | Cloud | professional 的 aesthetics 表示美学评分，评分越高，图像越“好看”，构图、色彩、风格越协调，取值范围为 0 到 100，支持两位小数。 |
| `artifacts` | number | 否 | Cloud | professional 的 artifacts 表示伪影评分，即图像是否存在压缩、AI 生成痕迹、畸变等；评分越高，伪影越少，图像越自然，取值范围为 0 到 100，支持两位小数。 |
| `blockiness` | number | 否 | Cloud | standard 的 blockiness 表示图片的块效应严重程度，值越高图片块效应越强，[0, 50] 表示差，[50, 60] 表示中，[60, 100] 表示好，-1 表示检测图像为非常规图像（如游戏、特效图等）。 |
| `blur` | number | 否 | Cloud | standard 和 professional 的 blur 都表示模糊评分，即图像是否清晰；评分越高，图像越清晰和锐利，取值范围为 0 到 100，支持两位小数。 |
| `brightness` | number | 否 | Cloud | standard 的 brightness 表示平均亮度，值越高表示越亮，取值范围为 0 到 255。 |
| `cg` | number | 否 | Cloud | standard 的 cg 取值范围为 0 到 100，数值接近 0 表示自然场景，接近 100 表示非自然场景（游戏、录屏等）。 |
| `cmartifacts` | number | 否 | Cloud | standard 的 cmartifacts 表示压缩失真强度，分数越高表示压缩失真越显著、画质越差，取值范围为 0 到 100：[0, 30) 表示无或轻微压缩失真，[30, 60) 表示存在压缩失真，[60, 100] 表示存在明显噪声。 |
| `contrast` | number | 否 | Cloud | standard 的 contrast 表示对比度程度，值越低表示对比度越低，取值范围为 0 到 100。 |
| `green` | number | 否 | Cloud | standard 的 green 表示图像绿色区域面积大小；数值越大，绿色区域面积越大，是绿幕的概率越大，取值范围为 0 到 255。 |
| `hue` | number | 否 | Cloud | standard 的 hue 表示色调的均衡程度，值越高表示色调越均衡，取值范围为 0 到 100。 |
| `noise` | number | 否 | Cloud | standard 和 professional 的 noise 都表示噪声评分，即图像中是否存在颗粒感或随机噪声；评分越高，图像越干净，取值范围为 0 到 100，支持两位小数。 |
| `overall` | number | 否 | Cloud | professional 的 overall 表示综合以上指标的总评分，评分越高，图像画质越好，取值范围为 0 到 100，支持两位小数。 |
| `overexposure` | number | 否 | Cloud | standard 的 overexposure 表示过曝光面积大小程度，值越高越可能存在过曝光，取值范围为 0 到 100。 |
| `saturation` | number | 否 | Cloud | standard 的 saturation 表示饱和度的均衡程度，值越高表示饱和度越均衡，取值范围为 0 到 100。 |
| `texture` | number | 否 | Cloud | standard 的 texture 表示纹理的丰富程度，值越高表示纹理越丰富，取值范围为 0 到 255。 |
| `tool_version` | string | 否 | Cloud | result.tool_version 在 standard 结果中固定为 standard，在 professional 结果中固定为 professional。 |
| `vqscore` | number | 否 | Cloud | standard 的 vqscore 表示图片主观质量，值越高表示质量越好，取值范围为 0 到 100。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image evaluate-image-quality --help
mediakit-cli image evaluate-image-quality --schema
```
reference/face-blur-image.md›
# 图像人脸打码
## 能力用途
自动检测图片中的所有人脸区域并进行马赛克处理，用于一键保护图片中的人脸隐私。支持社交平台内容审核、街景或监控画面脱敏、新闻媒体素材处理以及 AI 训练数据集脱敏等批量人脸隐私保护场景。
## 参数填写规则
- 提交一张公网可访问图片 Url，自动检测并对图中所有人脸做马赛克打码；可选配置打码形状、像素格大小、检测置信度阈值与输出格式。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image face-blur-image`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `blur_shape` | `--blur-shape` | string | 否 | "circle" | 枚举: ["circle","rectangle"] | 人脸模糊区域的形状，支持 circle 或 rectangle：circle 表示圆形，rectangle 表示矩形；默认 circle。 |
| `face_detect_thresh` | `--face-detect-thresh` | number | 否 | 0.9 | 大于: 0；小于: 1 | 人脸检测置信度阈值必须大于 0 且小于 1；越高过滤越严格，过低可能误判非人脸区域，过高可能漏检人脸；默认 0.9。 |
| `image_url` | `--image-url` | string | 是 | - | - | 待打码的图像 URL，支持公网 HTTP/HTTPS URL、本地文件路径和火山引擎对象存储 tos:// 三种输入协议；支持 .png、.jpg、.jpeg、.webp、.avif 等主流图像格式，不支持动图。建议图像文件大小不超过 35 MB；图片文件过大可能导致处理失败；图片宽度和高度的乘积不得超过 4 亿像素。 |
| `mosaic_step` | `--mosaic-step` | integer | 否 | 12 | 最小值: 5；最大值: 100 | 马赛克像素格大小，单位 px，必须为正整数；越大，马赛克颗粒越大且脱敏强度越高；建议范围为 [5, 100]；默认 12。 |
| `output_format` | `--output-format` | string | 否 | "webp" | 枚举: ["png","jpeg","webp"] | 输出图片格式，支持 png、jpeg 或 webp；默认 webp。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image face-blur-image \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `face_count` | integer | 否 | Cloud | 检测到并已打码的人脸数量；为 0 表示未检测到人脸且原图未做处理；大于 0 表示已对对应数量的人脸完成打码。 |
| `face_location` | array<object> | 否 | Cloud | 每张检测出的人脸信息对象数组；未检测到人脸时为空数组。 |
| `face_location[].bottom_right_x` | integer | 否 | Cloud | 人脸检测框右下角横坐标，单位 px。 |
| `face_location[].bottom_right_y` | integer | 否 | Cloud | 人脸检测框右下角纵坐标，单位 px。 |
| `face_location[].confidence` | number | 否 | Cloud | 人脸检测置信度，必须大于 0 且小于 1。 |
| `face_location[].top_left_x` | integer | 否 | Cloud | 人脸检测框左上角横坐标，单位 px。 |
| `face_location[].top_left_y` | integer | 否 | Cloud | 人脸检测框左上角纵坐标，单位 px。 |
| `image_format` | string | 否 | Cloud | 处理后图片格式。 |
| `image_height` | integer | 否 | Cloud | 处理后图片高度，单位 px。 |
| `image_size` | integer | 否 | Cloud | 处理后图片大小，单位字节。 |
| `image_url` | string | 否 | Cloud | 人脸打码后的图片文件下载地址，有效期为 24 小时，务必及时保存对应的产物。 |
| `image_width` | integer | 否 | Cloud | 处理后图片宽度，单位 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image face-blur-image --help
mediakit-cli image face-blur-image --schema
```
reference/families/image-size-reduction.md›
# 图片体积治理选择指南
## 共同目标
缩小图片文件体积。
## 选择边界
- [slim-image](../slim-image.md)：用户强调尽量不掉画质、质量优先或高质量缩小体积，且未要求精确体积上限或质量值时优先选择；默认保持原格式，并通过 AI 修复毛刺、彩噪和块效应、增强边缘与纹理细节。
- [compress-image](../compress-image.md)：用户明确给出 quality、max_size 或 output_format，要求格式转换，或明确接受 PNG 有损压缩时选择；压缩率提高可能增加画质损失。
## 澄清边界
如果用户只说压缩或变小，无法判断是质量优先还是需要精确体积、质量或格式控制，先澄清，不得仅凭工具名猜测。
reference/flip-image.md›
# 图像翻转
## 能力用途
支持对单张图片执行水平或竖直翻转。
## 参数填写规则
- 提交一张图片并指定翻转方向。仅支持公网 URL。未传 output_format 时默认保持原图格式。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image flip-image`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `flip_type` | `--flip-type` | string | 是 | - | 枚举: ["horizontal","vertical"] | 翻转方向包括 horizontal 和 vertical：horizontal 表示水平翻转（左右镜像），vertical 表示竖直翻转（上下翻转）。 |
| `image_url` | `--image-url` | string | 是 | - | - | 待处理图片仅支持处理静图，支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎对象存储 tos:// 三种输入协议；支持 .png、.jpg、.jpeg、.webp 等主流图像格式；建议单张图片不超过 35 MB，输入图片的宽和高均不得超过 10000 像素。 |
| `output_format` | `--output-format` | string | 否 | "original" | 枚举: ["original","png","jpeg","webp"] | 输出图片格式，非必选；默认为 original，表示保持与原图一致的格式；另有 png、jpeg、webp。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image flip-image \
--image-url <image_url> \
--flip-type <flip_type>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | 生成图像的格式，例如 jpeg。 |
| `image_height` | integer | 否 | Cloud | 生成图像的高度，单位为 px。 |
| `image_size` | integer | 否 | Cloud | 生成图像的大小，单位为字节。 |
| `image_url` | string | 否 | Cloud | 处理后的图片文件下载地址，有效期为 24 小时。 |
| `image_width` | integer | 否 | Cloud | 生成图像的宽度，单位为 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image flip-image --help
mediakit-cli image flip-image --schema
```
reference/gaussian-blur-image.md›
# 图像高斯模糊
## 能力用途
用于图像高斯模糊；通过设定模糊强度快速对图片进行模糊处理，适用于隐私信息弱化、背景氛围化、生成预览图及封面背景等场景。
## 参数填写规则
- 输入一张图片并指定高斯模糊强度。blur_strength 范围为 1~100，数值越大越模糊，默认 10；推荐值为 10（轻度）、30（中度）、100（重度）。output_format 默认 original 表示保持原图格式。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image gaussian-blur-image`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `blur_strength` | `--blur-strength` | integer | 否 | 10 | 最小值: 1；最大值: 100 | 高斯模糊强度，数值越大越模糊，范围 1 到 100，默认 10。推荐 10 为轻度模糊，推荐 30 为中度模糊，推荐 100 为重度模糊。 |
| `image_url` | `--image-url` | string | 是 | - | - | 待处理图片 URL，支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎对象存储 tos:// 三种输入协议；仅支持处理静图；支持 .png、.jpg、.jpeg、.webp 等主流图像格式。输入图像的宽和高均不得超过 10000 像素，建议单张图片不超过 35 MB。 |
| `output_format` | `--output-format` | string | 否 | "original" | 枚举: ["original","png","jpeg","webp"] | 输出图片格式，original 表示保持与原图一致的格式；支持 original、png、jpeg、webp，默认 original。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image gaussian-blur-image \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | 生成图像的格式，例如 jpeg。 |
| `image_height` | integer | 否 | Cloud | 生成图像的高度，单位为 px。 |
| `image_size` | integer | 否 | Cloud | 生成图像的大小，单位为字节。 |
| `image_url` | string | 否 | Cloud | 处理后的图片文件下载地址，有效期为 24 小时，请务必及时保存产物。 |
| `image_width` | integer | 否 | Cloud | 生成图像的宽度，单位为 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image gaussian-blur-image --help
mediakit-cli image gaussian-blur-image --schema
```
reference/image-ocr.md›
# 图像文字识别OCR
## 能力用途
用于通用印刷体文字识别（OCR），识别图片中的简体中文和英文，并提供文本块位置坐标与置信度参考。
## 参数填写规则
- 提交一张包含通用印刷体文字的公网可访问图片 URL，识别图片中的简体中文和英文文本。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image image-ocr`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 使用指南
- `image_url` 有宽高与体积限制：长边不得超过 3840 px，短边不得超过 2160 px，单张文件大小不得超过 10 MB。为避免超限导致调用失败，提交 OCR 前可先用本域能力做前置探测与治理：
1. 用 `probe-image-metadata`（默认 `info_type=metadata`）探测宽高与文件大小，判断是否可能超限；
2. 若宽高超限，先用 `resize-image` 等比缩放到合规尺寸；详见 [resize-image.md](resize-image.md)；
3. 若体积超限，先用 `compress-image` 压缩到 10 MB 以内；详见 [compress-image.md](compress-image.md)；
4. 将预处理返回的 `image_url` 再作为本工具的 `--image-url` 输入。探测详见 [probe-image-metadata.md](probe-image-metadata.md)。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `image_url` | `--image-url` | string | 是 | - | - | 待识别的图像 URL。图像来源支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎对象存储 (tos://) 三种输入协议；图像长边不得超过 3840 px，短边不得超过 2160 px，单张图片文件大小不得超过 10 MB；支持 .png、.jpg、.jpeg、.webp、.tiff、.bmp 和 .heic 格式。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image image-ocr \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `ocr_result` | array<object> | 否 | Cloud | 通用印刷体文字识别结果列表，每个元素代表一个识别出的文本块。 |
| `ocr_result[].bottom_right_x` | number | 否 | Cloud | 文字框右下角横坐标，单位 px。 |
| `ocr_result[].bottom_right_y` | number | 否 | Cloud | 文字框右下角纵坐标，单位 px。 |
| `ocr_result[].confidence` | number | 否 | Cloud | 识别置信度，取值范围 [0,1]。 |
| `ocr_result[].content` | string | 否 | Cloud | 识别出的文字内容。 |
| `ocr_result[].top_left_x` | number | 否 | Cloud | 文字框左上角横坐标，单位 px。 |
| `ocr_result[].top_left_y` | number | 否 | Cloud | 文字框左上角纵坐标，单位 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image image-ocr --help
mediakit-cli image image-ocr --schema
```
reference/invert-image.md›
# 图像负片
## 能力用途
用于图像负片，对输入图像执行负片（反相）效果，将图像的明暗关系与颜色映射为原图的相反效果，即明暗反转、色彩转为补色。
## 参数填写规则
- 提交一张图片即可生成负片（反相）效果图，无需任何效果调参。output_format 默认 original 表示保持原图格式。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image invert-image`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `image_url` | `--image-url` | string | 是 | - | - | 待处理的图片 URL，支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎对象存储（tos://）三种输入协议；支持 .png、.jpg、.jpeg、.webp 等主流图像格式，且仅支持处理静图；建议单张图片不超过 35 MB，输入图像的宽和高均不得超过 10000 像素。 |
| `output_format` | `--output-format` | string | 否 | "original" | 枚举: ["original","png","jpeg","webp"] | 输出图片的格式，支持 png、jpeg、webp，默认使用 original 保持与原图一致的格式。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image invert-image \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | 生成图像的格式，例如 webp。 |
| `image_height` | integer | 否 | Cloud | 生成图像的高度，单位为 px。 |
| `image_size` | integer | 否 | Cloud | 生成图像的大小，单位为字节。 |
| `image_url` | string | 否 | Cloud | 处理后的图片文件下载地址，有效期为 24 小时。 |
| `image_width` | integer | 否 | Cloud | 生成图像的宽度，单位为 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image invert-image --help
mediakit-cli image invert-image --schema
```
reference/mosaic-image.md›
# 图像打码
## 能力用途
支持对整张图像或指定矩形区域进行马赛克打码，可调整像素格形状与大小。支持用于遮挡人脸、证件信息、车牌、聊天记录等敏感内容。
## 参数填写规则
- 输入一张图片并配置打码方式。默认执行全图打码：mosaic_type=full-image、mosaic_step_x=12、mosaic_step_y=12、output_format=original。指定区域打码时设置 mosaic_type=specify-region，并传入 1-3 组 mosaic_regions 坐标。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image mosaic-image`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 使用指南
- 对象或对象数组参数（`--mosaic-regions`）需传合法 JSON 字符串并整体加单引号，例如 `--mosaic-regions '[{...}]'`；字段名与层级必须与上表“枚举/范围/结构”及子字段说明一致。
- 不要用逗号分隔或裸文本传该参数。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image mosaic-image \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `image_url` | `--image-url` | string | 是 | - | - | 仅支持处理静图；建议单张图片不超过 35 MB；输入图像的宽和高均不得超过 10000 像素。支持 .png、.jpg、.jpeg、.webp 等主流图像格式。支持公网 HTTP/HTTPS URL、本地文件路径和火山引擎对象存储（tos://）三种输入协议。 |
| `mosaic_regions` | `--mosaic-regions` | array<object> | 否 | - | 最少项数: 1；最多项数: 3 | 最多支持 3 个矩形区域。 |
| `mosaic_regions[].bottom_right_x` | - | integer | 是 | - | 最小值: 0 | 框选区域右下角的 X 轴坐标，单位为 px，坐标原点为图像左上角。 |
| `mosaic_regions[].bottom_right_y` | - | integer | 是 | - | 最小值: 0 | 框选区域右下角的 Y 轴坐标，单位为 px，坐标原点为图像左上角。 |
| `mosaic_regions[].top_left_x` | - | integer | 是 | - | 最小值: 0 | 框选区域左上角的横 X 轴坐标，单位为 px，坐标原点为图像左上角。 |
| `mosaic_regions[].top_left_y` | - | integer | 是 | - | 最小值: 0 | 框选区域左上角的 Y 轴坐标，单位为 px，坐标原点为图像左上角。 |
| `mosaic_shape` | `--mosaic-shape` | string | 否 | "circle" | 枚举: ["circle","rectangle"] | 默认使用 circle。支持 circle 和 rectangle：circle 表示圆形/椭圆像素格，视觉更柔和；rectangle 表示矩形像素格，遮挡更规整。 |
| `mosaic_step_x` | `--mosaic-step-x` | integer | 否 | 12 | 最小值: 1 | 控制打码像素格的宽度，单位为 px；数值越大，马赛克颗粒感越强。默认值为 12。 |
| `mosaic_step_y` | `--mosaic-step-y` | integer | 否 | 12 | 最小值: 1 | 控制打码像素格的高度，单位为 px；数值越大，马赛克颗粒感越强。默认值为 12。 |
| `mosaic_type` | `--mosaic-type` | string | 否 | "full-image" | 枚举: ["full-image","specify-region"] | 默认使用 full-image，对整张图片打码。支持 full-image 和 specify-region：full-image 对整张图片打码；specify-region 仅对 mosaic_regions 指定的区域打码。 |
| `output_format` | `--output-format` | string | 否 | "original" | 枚举: ["original","png","jpeg","webp"] | 支持 png、jpeg、webp，也支持并默认使用 original，保持与原图一致的格式。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | 返回生成图像的格式。 |
| `image_height` | integer | 否 | Cloud | 生成图像的高度，单位为 px。 |
| `image_size` | integer | 否 | Cloud | 生成图像的大小，单位为字节。 |
| `image_url` | string | 否 | Cloud | 处理后的图片文件下载地址有效期为 24 小时，必须及时保存产物。 |
| `image_width` | integer | 否 | Cloud | 生成图像的宽度，单位为 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image mosaic-image --help
mediakit-cli image mosaic-image --schema
```
reference/probe-image-metadata.md›
# 图像元信息获取
## 能力用途
支持查询 metadata、avghue、alpha、blurhash 四种图像信息。
## 参数填写规则
- 提交一张公网可访问图片 URL，并指定查询信息类型；未传 info_type 时默认返回 metadata。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image probe-image-metadata`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `image_url` | `--image-url` | string | 是 | - | - | 待探测的图片 URL。支持公网 HTTP/HTTPS URL、本地文件路径 与火山引擎对象存储 tos:// 三种输入协议；支持 .png、.jpg、.jpeg、.webp 等主流图像格式。图片输入分辨率的宽和高均不得超过 10000 像素，建议单张图片文件大小不超过 35 MB。 |
| `info_type` | `--info-type` | string | 否 | "metadata" | 枚举: ["metadata","avghue","alpha","blurhash"] | 查询信息类型。metadata 获取图像的基本元信息；avghue 提取图像的主题色；alpha 分析图像的 Alpha 透明通道；blurhash 生成图像的 BlurHash 值。默认 metadata。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image probe-image-metadata \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `aigc` | object / null | 否 | Cloud | AIGC 元数据。 |
| `alpha_ratio` | number | 否 | Cloud | Alpha 像素（完全透明或半透明）在整张图片中的占比。 |
| `blurhash` | string | 否 | Cloud | BlurHash 编码字符串。 |
| `color` | string | 否 | Cloud | 十六进制格式的主题色，例如 #RRGGBB。 |
| `color_model` | string | 否 | Cloud | 色彩模型，例如 yuv420p。 |
| `duration` | number | 否 | Cloud | 动图时长，单位为秒；静态图此字段可能不存在。 |
| `exif` | object / null | 否 | Cloud | EXIF 元数据。 |
| `format` | string | 否 | Cloud | 图片格式，例如 jpeg。 |
| `frame_count` | number | 否 | Cloud | 图片帧数，对于静态图通常为 1。 |
| `has_alpha` | boolean | 否 | Cloud | 是否包含 Alpha 透明通道。 |
| `height` | number | 否 | Cloud | 图片高度，单位为 px。 |
| `is_animation` | boolean | 否 | Cloud | 是否为动图。 |
| `md5` | string | 否 | Cloud | 图片的 MD5 值。 |
| `orientation` | object / array / string / number / boolean / null | 否 | Cloud | 图片方向信息。 |
| `quality` | number | 否 | Cloud | 压缩质量参数。 |
| `size` | number | 否 | Cloud | 图片大小，单位为 Byte。 |
| `width` | number | 否 | Cloud | 图片宽度，单位为 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image probe-image-metadata --help
mediakit-cli image probe-image-metadata --schema
```
reference/remove-image-background.md›
# 图像背景移除
## 能力用途
自动识别并保留图像主体，移除背景后生成背景透明的图片，用于图像背景移除（抠图）。
## 参数填写规则
- 提交一张公网可访问图片 URL，并指定背景移除场景；general 适合未知主体，human/product 支持描边和透明背景裁剪。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image remove-image-background`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 使用指南
- 布尔参数（`--need-contour`、`--need-crop-background`）只能写成 `--need-contour=true` 或 `--need-contour=false`，也可用裸 `--need-contour`（等价 true）；禁止空格传值 `--need-contour true`，否则该值会被当作位置参数。
- 布尔参数取默认值时直接省略，不要显式重复默认值。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image remove-image-background \
--image-url <image_url> \
--scene <scene>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `contour_color` | `--contour-color` | string | 否 | "#FFFFFF" | 格式: "^#[0-9a-fA-F]{6}$" | 主体描边颜色，使用十六进制 RGB，默认 #FFFFFF；仅当 need_contour 为 true 且 scene 为 human 或 product 时生效。 |
| `contour_size` | `--contour-size` | integer | 否 | 10 | 最小值: 1；最大值: 100 | 主体描边宽度，单位 px，范围 1 至 100，默认 10；仅当 need_contour 为 true 且 scene 为 human 或 product 时生效。 |
| `image_url` | `--image-url` | string | 是 | - | - | 待处理的图像 URL，支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎对象存储 tos:// 三种输入协议；支持 .png、.jpg、.jpeg、.webp、.tiff、.bmp 和 .heic 格式；单张图片不得超过 10 MB，图像输入分辨率的长边不得超过 7680 px、短边不得超过 4320 px。 |
| `need_contour` | `--need-contour` | boolean | 否 | false | - | 是否为主体生成描边，默认 false；仅在 scene 为 human 或 product 时生效，在 general 场景下会被忽略。 |
| `need_crop_background` | `--need-crop-background` | boolean | 否 | false | - | 是否将输出图片的透明背景裁剪到刚好包裹住主体，默认 false；仅在 scene 为 human 或 product 时生效，在 general 场景下会被忽略。 |
| `output_format` | `--output-format` | string | 否 | "png" | 枚举: ["png","jpeg","webp"] | 输出图片格式可用 png、jpeg、webp，默认 png；png 支持透明背景，webp 支持透明背景，jpeg 不支持透明背景，jpeg 的透明区域将填充为黑色。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `scene` | `--scene` | string | 是 | - | 枚举: ["general","human","product"] | 背景移除场景可用 general、human、product；general 为通用场景，适用于期望抠出图像主体但不确定该主体所属分类的场景；human 为人像抠图场景，适用于仅需抠出图像中的人像主体的场景；product 为商品抠图场景，适用于仅需抠出图像中的商品主体的场景。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | 生成图像的格式。 |
| `image_height` | integer | 否 | Cloud | 生成图像的高度，单位 px。 |
| `image_size` | integer | 否 | Cloud | 生成图像的大小，单位为字节。 |
| `image_url` | string | 否 | Cloud | 背景移除后的图片下载 URL，有效期 24 小时。 |
| `image_width` | integer | 否 | Cloud | 生成图像的宽度，单位 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image remove-image-background --help
mediakit-cli image remove-image-background --schema
```
reference/resize-image.md›
# 图像缩放
## 能力用途
用于图像缩放，支持按指定宽高精确缩放，也可按长边、短边或等比模式缩放，适用于多端素材适配、封面与缩略图生成及批量图片预处理。
## 参数填写规则
- 输入一张图片并指定缩放策略。仅支持公网 URL。未传 resize_mode 时默认 contain，未传 resize_adaptive 时默认同时启用 enlarge 与 shrink。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image resize-image`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 使用指南
- 数组参数（`--resize-adaptive`）传多个值时用逗号分隔并整体加引号，例如 `--resize-adaptive "url1,url2"`。
- 单个值中的文件名或 URL 不能包含逗号（`,`），否则会被 CLI 当成多个元素拆开。遇到这种情况时，先向用户澄清，请其提供不含逗号的文件名或对应 URL 后再调用。
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image resize-image \
--image-url <image_url> \
--resize-long <resize_long>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `image_url` | `--image-url` | string | 是 | - | - | image_url 是待处理图片的 URL，图片来源支持公网 HTTP/HTTPS URL、本地文件路径和火山引擎对象存储 tos:// 三种输入协议；输入支持 .png、.jpg、.jpeg、.webp 等主流图像格式；输入仅支持静图；建议单张输入图片不超过 35 MB，输入图像的宽和高均不得超过 10000 像素。 |
| `output_format` | `--output-format` | string | 否 | "original" | 枚举: ["original","png","jpeg","webp"] | output_format 指定输出图片格式；支持 original、png、jpeg、webp，original 表示输出保持与原图一致的格式；默认 original。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `resize_adaptive` | `--resize-adaptive` | array<string> | 否 | ["enlarge","shrink"] | 最少项数: 1；元素枚举: ["enlarge","shrink"] | resize_adaptive 控制仅在特定条件下执行缩放；支持 enlarge、shrink；enlarge 仅在原图尺寸小于目标尺寸时执行放大，shrink 仅在原图尺寸大于目标尺寸时执行缩小；默认 enlarge、shrink，即总是执行缩放。 CLI 传参时可使用逗号分隔多个值，或重复传递该 flag；不要传 JSON 数组字符串。 |
| `resize_long` | `--resize-long` | integer | 否 | - | 最小值: 0 | resize_long 表示目标图像的长边尺寸，单位为像素；仅设置 resize_long，或将 resize_short 设为 0 时，图像按原始比例缩放，使长边匹配 resize_long；resize_long 与 resize_short 同时设置时，缩放行为由 resize_mode 决定。 |
| `resize_mode` | `--resize-mode` | string | 否 | "contain" | 枚举: ["exact","contain","cover"] | resize_mode 定义同时指定 resize_long 和 resize_short 时的缩放行为；支持 exact、contain、cover；exact 强制将图像精确缩放到 resize_long x resize_short，可能导致拉伸或压缩变形；contain 保持原始宽高比，使图像完整包含在 resize_long x resize_short 矩形框内，最终宽高均不超过指定值；cover 保持原始宽高比，使图像完全填满 resize_long x resize_short 矩形框，并居中裁剪超出部分；默认 contain。 |
| `resize_short` | `--resize-short` | integer | 否 | - | 最小值: 0 | resize_short 表示目标图像的短边尺寸，单位为像素；仅设置 resize_short，或将 resize_long 设为 0 时，图像按原始比例缩放，使短边匹配 resize_short；resize_short 与 resize_long 同时设置时，缩放行为由 resize_mode 决定。 |
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | image_format 表示生成图像的格式。 |
| `image_height` | integer | 否 | Cloud | image_height 表示生成图像的高度，单位为 px。 |
| `image_size` | integer | 否 | Cloud | image_size 表示生成图像的大小，单位为字节。 |
| `image_url` | string | 否 | Cloud | image_url 是处理后图片文件的下载地址，有效期为 24 小时，请务必及时保存下载地址对应的产物。 |
| `image_width` | integer | 否 | Cloud | image_width 表示生成图像的宽度，单位为 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image resize-image --help
mediakit-cli image resize-image --schema
```
reference/rotate-image.md›
# 图像旋转
## 能力用途
通过设置旋转角度和旋转背景样式对图片进行旋转处理，适用于图片方向校正、创意编辑和批量图像处理。
## 参数填写规则
- 输入图片并指定旋转角度、旋转背景样式和输出格式。仅支持公网 URL。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image rotate-image`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `fill_color` | `--fill-color` | string | 否 | "Black" | 枚举: ["Black","White","Transparent"] | fill_color 用于填充旋转后因非正交角度产生的空白区域，支持 Black、White、Transparent。Black 表示黑色填充，White 表示白色填充，Transparent 表示透明填充，建议配合 png 格式输出，fill_color 默认为 Black。 |
| `image_url` | `--image-url` | string | 是 | - | - | 待处理图片的 URL。支持公网 HTTP/HTTPS URL、本地文件路径和对象存储 tos:// 三种输入协议，支持 .png、.jpg、.jpeg、.webp 等主流图像格式，仅支持处理静图。输入图片宽度和高度均不得超过 10000 像素，建议单张图片不超过 35 MB。 |
| `output_format` | `--output-format` | string | 否 | "webp" | 枚举: ["original","png","jpeg","webp"] | output_format 用于指定输出图片格式，支持 original、png、jpeg、webp。original 表示保持与原图一致的格式，output_format 默认为 webp。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `rotate_angle` | `--rotate-angle` | integer | 是 | - | 最小值: 1；最大值: 359 | rotate_angle 表示图像逆时针旋转的角度，必须大于 0 且必须小于 360。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image rotate-image \
--image-url <image_url> \
--rotate-angle <rotate_angle>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | image_format 表示生成图像的格式。 |
| `image_height` | integer | 否 | Cloud | image_height 表示生成图像的高度，单位为 px。 |
| `image_size` | integer | 否 | Cloud | image_size 表示生成图像的大小，单位为字节。 |
| `image_url` | string | 否 | Cloud | image_url 是处理后图片文件的下载地址，有效期为 24 小时，请务必及时保存该地址指向的产物。 |
| `image_width` | integer | 否 | Cloud | image_width 表示生成图像的宽度，单位为 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image rotate-image --help
mediakit-cli image rotate-image --schema
```
reference/round-corner-image.md›
# 圆角矩形
## 能力用途
为图片四角快速添加正圆或椭圆圆角，适用于头像、卡片、电商主图等常见视觉编辑场景。
## 参数填写规则
- 提交待处理图片，并按圆角类型配置半径参数。corner_type=circle 时必须传 radius；corner_type=ellipse 时必须同时传 radius_x 和 radius_y。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image round-corner-image`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `circle_radius` | `--circle-radius` | integer | 否 | 50 | 最小值: 0 | 正圆圆角半径，单位为 px，取值范围为 [0, 原图最小边/2]；超过该范围时按最大内切圆半径处理。 |
| `corner_type` | `--corner-type` | string | 否 | "circle" | 枚举: ["circle","ellipse"] | 圆角类型支持 circle 和 ellipse。circle 表示正圆圆角，半径通过 circle_radius 配置；ellipse 表示椭圆圆角，X 轴和 Y 轴半径分别通过 ellipse_radius_x 和 ellipse_radius_y 配置。默认 circle。 |
| `ellipse_radius_x` | `--ellipse-radius-x` | integer | 否 | 40 | 最小值: 0 | 椭圆圆角 X 轴（水平）半径，单位为 px，取值大于等于 0。 |
| `ellipse_radius_y` | `--ellipse-radius-y` | integer | 否 | 60 | 最小值: 0 | 椭圆圆角 Y 轴（垂直）半径，单位为 px，取值大于等于 0。 |
| `image_url` | `--image-url` | string | 是 | - | - | 待处理图片的 URL，支持公网 HTTP/HTTPS URL、本地文件路径和火山引擎对象存储 tos:// 三种输入协议；支持 .png、.jpg、.jpeg、.webp 等主流图像格式，仅支持处理静图。建议单张图片不超过 35 MB，输入图片的宽和高均不得超过 10000 像素。 |
| `output_format` | `--output-format` | string | 否 | "webp" | 枚举: ["original","png","jpeg","webp"] | 输出图片格式支持 original、png、webp 和 jpeg，默认 webp。original 保持原图格式；png 和 webp 会对圆角外区域进行透明填充，jpeg 会对圆角外区域进行白色填充。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image round-corner-image \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | 生成图像的格式 |
| `image_height` | integer | 否 | Cloud | 生成图像的高度，单位为 px |
| `image_size` | integer | 否 | Cloud | 生成图像的大小，单位为字节 |
| `image_url` | string | 否 | Cloud | 处理后的图片文件下载地址，有效期为 24 小时，必须及时保存指向的产物。 |
| `image_width` | integer | 否 | Cloud | 生成图像的宽度，单位为 px |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image round-corner-image --help
mediakit-cli image round-corner-image --schema
```
reference/sharpen-image.md›
# 图像锐化
## 能力用途
用于图像锐化，通过对输入图像进行锐化处理，有效增强图像的边缘细节与整体清晰度。适用于电商素材优化、UGC 画质增强、封面海报二创等场景。
## 参数填写规则
- 输入一张图片并指定锐化强度档位。锐化强度 sharpen_level 支持 low / medium / high 三档，默认 low。output_format 默认 original 表示保持原图格式。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image sharpen-image`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `image_url` | `--image-url` | string | 是 | - | - | 待处理图片 URL，支持 .png、.jpg、.jpeg、.webp 等主流图像格式；支持公网 HTTP/HTTPS URL、本地文件路径、火山引擎对象存储 tos:// 三种输入协议；仅支持处理静图；输入图像的宽和高均不得超过 10000 像素；建议单张图片不超过 35 MB。 |
| `output_format` | `--output-format` | string | 否 | "original" | 枚举: ["original","png","jpeg","webp"] | 输出图片格式，默认并支持 original，表示保持与原图一致的格式；也支持 png、jpeg、webp。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `sharpen_level` | `--sharpen-level` | string | 否 | "low" | 枚举: ["low","medium","high"] | 锐化强度档位，支持 low（轻度锐化）、medium（中度锐化）和 high（重度锐化），默认 low。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image sharpen-image \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | 生成图像的格式。 |
| `image_height` | integer | 否 | Cloud | 生成图像的高度，单位为 px。 |
| `image_size` | integer | 否 | Cloud | 生成图像的大小，单位为字节。 |
| `image_url` | string | 否 | Cloud | 处理后的图片文件下载地址，有效期为 24 小时。 |
| `image_width` | integer | 否 | Cloud | 生成图像的宽度，单位为 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image sharpen-image --help
mediakit-cli image sharpen-image --schema
```
reference/slim-image.md›
# 集智瘦身
## 能力用途
集智瘦身通过 AI 大幅缩小图片体积，修复毛刺、彩噪和块效应等问题，增强图像边缘与纹理细节，输出更轻量且更清晰的图片。用户强调尽量不掉画质、质量优先或高质量缩小体积，且未要求精确体积上限、质量值或格式转换时，优先选择本工具。
## 相近能力选择
缩小图片文件体积时，先读取 [图片体积治理选择指南](families/image-size-reduction.md)，再决定使用 slim-image 或 compress-image。
## 参数填写规则
- 提交一张公网可访问的图片 URL 并指定输出格式。当前版本仅开放 URL 输入 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 与 `compress-image` 的边界：本工具用于质量优先的图片瘦身；若用户明确给出 `quality`、`max_size`、`output_format`，要求格式转换，或明确接受 PNG 有损压缩，应改用 `compress-image`；若只说压缩或变小且无法判断目标，先澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image slim-image`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `image_url` | `--image-url` | string | 是 | - | - | 待处理图片 URL，支持公网 HTTP/HTTPS URL、本地文件路径和火山引擎对象存储 tos:// 三种输入协议。输入图片支持 jpeg、jpg、png、heic、avif 和 webp 格式，暂不支持动图输入。建议单张输入图片不超过 50 MB；输入图像的宽度不得超过 10000 像素，高度不得超过 10000 像素。当输入图像格式为 avif 时，建议宽与高的乘积不要超过 100,000；当 avif 输入图像的宽与高乘积超过建议的 100,000 时，处理可能失败。 |
| `output_format` | `--output-format` | string | 否 | "original" | 枚举: ["original","png","jpeg","webp"] | 输出图片格式，默认 original；original 表示输出保持与原图一致的格式，支持 original、png、jpeg 或 webp。输入和输出格式均为 JPEG 时，部分已高度压缩的源文件处理后体积可能无明显变化；JPEG 输入输出时体积可能不降或略增，与原图压缩参数及 JPEG 重新编码特性有关，属于正常现象；输入和输出格式均为 JPEG 时，少数情况下处理后体积甚至会略微增大。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image slim-image \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | 生成图像的格式。 |
| `image_height` | integer | 否 | Cloud | 生成图像的高度，单位为 px。 |
| `image_size` | integer | 否 | Cloud | 生成图像的大小，单位为字节。 |
| `image_url` | string | 否 | Cloud | 集智瘦身后的结果图片下载 URL，有效期 24 小时，必须及时保存指向的产物。 |
| `image_width` | integer | 否 | Cloud | 生成图像的宽度，单位为 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image slim-image --help
mediakit-cli image slim-image --schema
```
reference/smart-crop-image.md›
# 图像智能裁剪
## 能力用途
自动识别图像中的主体人脸区域，并适配指定尺寸进行裁剪；支持普通人脸和动漫人脸场景。未识别到人脸时，可按预设的降级策略输出结果。
## 参数填写规则
- 提交一张公网可访问图片 URL，并指定目标宽高、裁剪场景和未找到人脸时的降级裁剪策略。 可选参数仅在用户明确指定，或可从用户意图准确确定时填写；不得伪造。不能准确确定时省略，确为正确完成任务所必需时先向用户澄清。
- 文档派生的 Cloud 公共请求字段只在用户明确提供时传递；不得由 Agent 生成、推断或补写。
## Cloud
### 命令与生命周期
- 命令：`mediakit-cli image smart-crop-image`
- 生命周期：同步
- 返回方式：直接返回 Cloud 业务结果。
### 参数
| 参数路径 | CLI flag | 类型 | 必填 | 默认值 | 枚举/范围/结构 | 说明 |
| --- | --- | --- | --- | --- | --- | --- |
| `crop_strategy` | `--crop-strategy` | string | 否 | "top_crop" | 枚举: ["top_crop","center_crop","frosted_glass_fill"] | 可选。裁剪后图片与目标宽高比例不一致时，使用降级裁剪策略；支持三种策略：top_crop（从图像顶部开始并水平居中裁剪，默认）、center_crop（从图像正中心开始向四周裁剪）、frosted_glass_fill（保持原图完整，并在两侧或上下添加毛玻璃背景以达到目标尺寸）。 |
| `frosted_glass_strength` | `--frosted-glass-strength` | number | 否 | 100 | 最小值: 1 | 可选。毛玻璃填充的模糊强度，数值越大，模糊效果越强；仅在 crop_strategy 为 frosted_glass_fill 时生效。默认 100，推荐取值范围为 [10, 100]。 |
| `image_url` | `--image-url` | string | 是 | - | - | 待处理图片的 URL。支持公网 HTTP/HTTPS URL、本地文件路径和火山引擎对象存储 tos:// 三种输入协议；支持 .png、.jpg、.jpeg、.webp、.tiff、.bmp、.heic 等主流图像格式。图片宽和高均不得超过 6000 px，建议单张输入图片不超过 10 MB。 |
| `queue_id` | `--queue-id` | string | 否 | - | - | 任务提交的目标队列 ID。如不传，默认使用系统自动创建的队列 ID。可将不同业务或优先级的任务提交到不同队列，以实现按队列对应的项目分账。队列可创建和管理，系统会自动为队列分配队列 ID。 仅在用户明确提供该值时传递；不得由 Agent 生成、推断或补写。 |
| `scene` | `--scene` | string | 否 | "person_face" | 枚举: ["person_face","cartoon_face"] | 可选。用于指定识别主体的裁剪场景模型；支持 person_face 和 cartoon_face 两种场景。person_face 表示普通人脸裁剪；cartoon_face 表示动漫人脸裁剪。默认 person_face。 |
| `target_height` | `--target-height` | integer | 否 | 100 | 最小值: 1 | 可选。裁剪后的目标高度，单位 px；默认 100。 |
| `target_width` | `--target-width` | integer | 否 | 100 | 最小值: 1 | 可选。裁剪后的目标宽度，单位 px；默认 100。 |
### 调用示例
```bash
MEDIAKIT_RUNTIME=<当前宿主> \
mediakit-cli image smart-crop-image \
--image-url <image_url>
```
仅使用用户真实输入替换占位符；可选 flag 遵守参数填写规则，不得编造 URL、文件、枚举或业务参数。
### 返回结果
| 字段路径 | 类型 | 必含 | 模式 | 说明 |
| --- | --- | --- | --- | --- |
| `image_format` | string | 否 | Cloud | 生成图像的格式。 |
| `image_height` | integer | 否 | Cloud | 生成图像的高度，单位 px。 |
| `image_size` | integer | 否 | Cloud | 生成图像的大小，单位字节。 |
| `image_url` | string | 否 | Cloud | 智能裁剪后图片文件的下载地址，有效期为 24 小时，务必及时保存指向的产物。 |
| `image_width` | integer | 否 | Cloud | 生成图像的宽度，单位 px。 |
### 机器合同
以下命令只读取本模式的实时 help/schema，不发起业务调用：
```bash
mediakit-cli image smart-crop-image --help
mediakit-cli image smart-crop-image --schema
```
SKILL.md›
---
name: byted-mediakit-image
version: "0.2.1"
license: "MIT"
description: "面向单张或批量图片的视觉处理、质量优化、内容理解与基础编辑目标，适用于图片尺寸缩放与体积治理、元信息探测、裁剪旋转翻转与圆角、颜色与锐化清晰度调整、负片、模糊与打码、水印、背景移除、文字识别、画质评估与智能裁剪等。若对象和目标族已明确属于图片优化、图片理解或图片隐私保护，但具体做法不确定，可先加载本 Skill 探索。"
permissions:
- shell
metadata:
requires:
bins: ["mediakit-cli"]
cliHelp: "mediakit-cli image --help"
product: mediakit-cli/skills
domain: image
capability_count: 21
---
# image MediaKit Skill
## 使用规则
1. 先读取 `../byted-mediakit-shared/SKILL.md`，执行统一前置检查；该 Skill 缺失时停止并提示安装。
2. 只从下表选择 `image` 域工具；相似能力按各工具“能力描述”和参数边界区分。
3. 执行前按需读取对应 reference；参数与结果说明来自同一份已审核文案，完整机器合同以当前 CLI `--schema` 为准。
4. 缺少必填参数、鉴权环境变量或真实输入资源时，向用户索取；通用可选字段只能透传用户明确提供的值，其他可选字段可由明确意图准确确定，但不得伪造。
5. 执行时设置 `MEDIAKIT_SURFACE=skill`，指定调用来源是 Skill。
6. 执行时把 `MEDIAKIT_RUNTIME` 设置为当前 Agent 宿主，避免 CLI 无法可靠识别父级 Agent。
## 图片体积治理与跨域路由
- 用户强调“尽量不掉画质”“质量优先”“高质量缩小体积”，且没有给出精确体积上限、质量值或格式转换要求时，先读取 [reference/families/image-size-reduction.md](reference/families/image-size-reduction.md)，优先选择 slim-image。
- 用户明确给出 quality、max_size、output_format，要求格式转换，或明确接受 PNG 有损压缩时，按同一 family guide 选择 compress-image。
- 用户只说“压缩”“变小”且无法判断质量优先还是精确体积、质量或格式控制时，先澄清。
- 若只说有图片而未说明业务目标，应先澄清。把多张图片做成视频、给视频叠图或视频画面裁剪应路由到 editing；视频抽帧、视频理解、视频增强或视频字幕擦除应路由到 video。
## 工具列表
| 工具 | 说明 | 支持模式 | 命令 | 参考 |
| --- | --- | --- | --- | --- |
| add-image-watermark | 为图片添加图文明水印，适用于版权标识与素材分发防盗链场景。 | Cloud | `mediakit-cli image add-image-watermark` | [reference/add-image-watermark.md](reference/add-image-watermark.md) |
| adjust-image-color | 对输入图像的亮度、对比度和饱和度进行调整，支持调亮、调暗、增强对比度、减弱对比度、增强饱和度、减弱饱和度共 6 种快速调整效果。适用于素材基础优化、统一内容视觉风格、营造庄重、复古等特殊氛围等场景。 | Cloud | `mediakit-cli image adjust-image-color` | [reference/adjust-image-color.md](reference/adjust-image-color.md) |
| compress-image | 有损图像压缩与格式转换工具；用户明确给出 quality、max_size、output_format、要求格式转换，或明确接受 PNG 有损压缩时选择。若用户强调尽量不掉画质、质量优先或高质量缩小体积，应优先选择 slim-image。 | Cloud | `mediakit-cli image compress-image` | [reference/compress-image.md](reference/compress-image.md) |
| crop-image | 对输入图像进行多模式裁剪，可执行方向裁剪、定向裁剪、自定义裁剪或内切圆裁剪，适用于多端尺寸适配、主体保留、商品图去边和指定区域截取。 | Cloud | `mediakit-cli image crop-image` | [reference/crop-image.md](reference/crop-image.md) |
| enhance-image | 基于图像内容理解进行智能决策，提升图片的分辨率、清晰度与色彩表现。 | Cloud | `mediakit-cli image enhance-image` | [reference/enhance-image.md](reference/enhance-image.md) |
| erase-image | 可按不同场景控制自动检测并擦除图片中的文字或常见图标，擦除后的区域通过智能填充技术进行修复，修复后的区域与背景自然融合。 | Cloud | `mediakit-cli image erase-image` | [reference/erase-image.md](reference/erase-image.md) |
| evaluate-image-quality | 用于图像画质评估，对输入图片进行主客观画质和美学评分，适用于质量监控、低质图筛查、内容审核、推荐排序和训练数据清洗。 | Cloud | `mediakit-cli image evaluate-image-quality` | [reference/evaluate-image-quality.md](reference/evaluate-image-quality.md) |
| face-blur-image | 自动检测图片中的所有人脸区域并进行马赛克处理，用于一键保护图片中的人脸隐私。支持社交平台内容审核、街景或监控画面脱敏、新闻媒体素材处理以及 AI 训练数据集脱敏等批量人脸隐私保护场景。 | Cloud | `mediakit-cli image face-blur-image` | [reference/face-blur-image.md](reference/face-blur-image.md) |
| flip-image | 支持对单张图片执行水平或竖直翻转。 | Cloud | `mediakit-cli image flip-image` | [reference/flip-image.md](reference/flip-image.md) |
| gaussian-blur-image | 用于图像高斯模糊；通过设定模糊强度快速对图片进行模糊处理，适用于隐私信息弱化、背景氛围化、生成预览图及封面背景等场景。 | Cloud | `mediakit-cli image gaussian-blur-image` | [reference/gaussian-blur-image.md](reference/gaussian-blur-image.md) |
| image-ocr | 用于通用印刷体文字识别（OCR），识别图片中的简体中文和英文，并提供文本块位置坐标与置信度参考。 | Cloud | `mediakit-cli image image-ocr` | [reference/image-ocr.md](reference/image-ocr.md) |
| invert-image | 用于图像负片，对输入图像执行负片（反相）效果，将图像的明暗关系与颜色映射为原图的相反效果，即明暗反转、色彩转为补色。 | Cloud | `mediakit-cli image invert-image` | [reference/invert-image.md](reference/invert-image.md) |
| mosaic-image | 支持对整张图像或指定矩形区域进行马赛克打码，可调整像素格形状与大小。支持用于遮挡人脸、证件信息、车牌、聊天记录等敏感内容。 | Cloud | `mediakit-cli image mosaic-image` | [reference/mosaic-image.md](reference/mosaic-image.md) |
| probe-image-metadata | 支持查询 metadata、avghue、alpha、blurhash 四种图像信息。 | Cloud | `mediakit-cli image probe-image-metadata` | [reference/probe-image-metadata.md](reference/probe-image-metadata.md) |
| remove-image-background | 自动识别并保留图像主体，移除背景后生成背景透明的图片，用于图像背景移除（抠图）。 | Cloud | `mediakit-cli image remove-image-background` | [reference/remove-image-background.md](reference/remove-image-background.md) |
| resize-image | 用于图像缩放，支持按指定宽高精确缩放，也可按长边、短边或等比模式缩放，适用于多端素材适配、封面与缩略图生成及批量图片预处理。 | Cloud | `mediakit-cli image resize-image` | [reference/resize-image.md](reference/resize-image.md) |
| rotate-image | 通过设置旋转角度和旋转背景样式对图片进行旋转处理，适用于图片方向校正、创意编辑和批量图像处理。 | Cloud | `mediakit-cli image rotate-image` | [reference/rotate-image.md](reference/rotate-image.md) |
| round-corner-image | 为图片四角快速添加正圆或椭圆圆角，适用于头像、卡片、电商主图等常见视觉编辑场景。 | Cloud | `mediakit-cli image round-corner-image` | [reference/round-corner-image.md](reference/round-corner-image.md) |
| sharpen-image | 用于图像锐化，通过对输入图像进行锐化处理，有效增强图像的边缘细节与整体清晰度。适用于电商素材优化、UGC 画质增强、封面海报二创等场景。 | Cloud | `mediakit-cli image sharpen-image` | [reference/sharpen-image.md](reference/sharpen-image.md) |
| slim-image | 质量优先的图片瘦身工具；用户强调尽量不掉画质、质量优先或高质量缩小体积，且未要求精确体积上限、质量值或格式转换时优先选择。 | Cloud | `mediakit-cli image slim-image` | [reference/slim-image.md](reference/slim-image.md) |
| smart-crop-image | 自动识别图像中的主体人脸区域，并适配指定尺寸进行裁剪；支持普通人脸和动漫人脸场景。未识别到人脸时，可按预设的降级策略输出结果。 | Cloud | `mediakit-cli image smart-crop-image` | [reference/smart-crop-image.md](reference/smart-crop-image.md) |