External/SnapOtter
1
0
Fork 0
mirror of https://github.com/snapotter-hq/SnapOtter.git synced 2026-08-03 07:46:42 +02:00
Code Issues Packages Projects Releases Wiki Activity

feat(docs-i18n): translate all documentation into 20 languages

Browse Source 
All 181 docs markdown files translated into 20 languages (apps/docs/<locale>/**). Companion to the i18n code PR; admin-merged because the file count exceeds GitHub's per-PR CI trigger limit. Validated by pnpm i18n:check (all surfaces, 0 stale/missing) and a clean all-locale docs build.
This commit is contained in:
SnapOtter
2026-07-11 13:52:47 +08:00
committed by GitHub
parent 00b651c9f8
commit 4963ab3bbd
3620 changed files with 306134 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/zh-CN/tools/image/adjust-colors.md
+71
View File
@@ -0,0 +1,71 @@
---
description: "调整亮度、对比度、饱和度、色温、色相、通道，并应用色彩效果。"
i18n_source_hash: 41b35fe5c2ba
i18n_provenance: human
i18n_output_hash: 9ced0c9b42f2
---
# Adjust Colors {#adjust-colors}
综合性的色彩调整工具，在单一端点中集合了亮度、对比度、曝光、饱和度、色温、着色、色相旋转、逐通道级别以及一键效果（灰度、棕褐、反相）。
## API Endpoint {#api-endpoint}
`POST /api/v1/tools/image/adjust-colors`
接受包含图像文件和一个 JSON `settings` 字段的 multipart 表单数据。
## Parameters {#parameters}
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| brightness | number | 否 | `0` | 亮度调整（-100 到 100） |
| contrast | number | 否 | `0` | 对比度调整（-100 到 100） |
| exposure | number | 否 | `0` | 曝光 / 中间调伽马（-100 到 100） |
| saturation | number | 否 | `0` | 色彩饱和度（-100 到 100） |
| temperature | number | 否 | `0` | 白平衡：冷/蓝到暖/橙（-100 到 100） |
| tint | number | 否 | `0` | 着色偏移：绿到品红（-100 到 100） |
| hue | number | 否 | `0` | 色相旋转（角度，-180 到 180） |
| sharpness | number | 否 | `0` | 锐化强度（0 到 100） |
| red | number | 否 | `100` | 红色通道级别（0 到 200，100 = 不变） |
| green | number | 否 | `100` | 绿色通道级别（0 到 200，100 = 不变） |
| blue | number | 否 | `100` | 蓝色通道级别（0 到 200，100 = 不变） |
| effect | string | 否 | `"none"` | 色彩效果：`none`、`grayscale`、`sepia`、`invert` |
## Example Request {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/adjust-colors \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"brightness": 20, "contrast": 10, "saturation": -30, "effect": "none"}'
```
应用温暖的复古效果：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/adjust-colors \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"temperature": 40, "saturation": -15, "contrast": 10, "effect": "sepia"}'
```
## Example Response {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
"originalSize": 2450000,
"processedSize": 2380000
}
```
## Notes {#notes}
- 所有参数都默认为中性值，因此你只需调整所需的部分。
- 调整按以下顺序应用：亮度、对比度、曝光、饱和度/色相、色温/着色、锐化、通道、效果。
- 色温在蓝橙轴和绿品红轴上使用 3x3 色彩重组矩阵。
- 曝光映射到 Sharp 的伽马函数（正值提亮中间调，负值压暗它们）。
- 此端点也响应旧路径 `/api/v1/tools/image/brightness-contrast`、`/api/v1/tools/image/saturation`、`/api/v1/tools/image/color-channels` 和 `/api/v1/tools/image/color-effects`。它们都使用相同的 schema。
- 输出格式与输入格式一致。HEIC、RAW、PSD 和 SVG 输入在处理前会自动解码。
apps/docs/zh-CN/tools/image/ai-canvas-expand.md
+84
View File
@@ -0,0 +1,84 @@
---
description: "使用 AI 外绘扩展图像画布，向任意方向延伸并填充与原图匹配的新区域。"
i18n_source_hash: 1b00db4ed40d
i18n_provenance: human
i18n_output_hash: a0402622243c
---
# AI Canvas Expand {#ai-canvas-expand}
使用 AI 驱动的填充（外绘）扩展图像画布。向任意方向延伸图像，并用与现有图像匹配的 AI 生成内容填充新区域。
## API Endpoint {#api-endpoint}
`POST /api/v1/tools/image/ai-canvas-expand`
**处理方式：** 异步（返回 202，通过 SSE 轮询 `/api/v1/jobs/{jobId}/progress` 获取状态）
**模型包：** `object-eraser-colorize`（1-2 GB）
## Parameters {#parameters}
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 图像文件（multipart） |
| extendTop | integer | 否 | `0` | 顶部要扩展的像素数 |
| extendRight | integer | 否 | `0` | 右侧要扩展的像素数 |
| extendBottom | integer | 否 | `0` | 底部要扩展的像素数 |
| extendLeft | integer | 否 | `0` | 左侧要扩展的像素数 |
| tier | string | 否 | `"balanced"` | 质量档位：`fast`、`balanced`、`high` |
| format | string | 否 | `"auto"` | 输出格式：`auto`、`png`、`jpg`、`jpeg`、`webp`、`tiff`、`gif`、`avif`、`heic`、`heif`、`jxl` |
| quality | integer | 否 | `95` | 输出质量（1-100） |
至少有一个扩展方向必须大于 0。
## Example Request {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/ai-canvas-expand \
-F "file=@photo.jpg" \
-F 'settings={"extendTop":200,"extendBottom":200,"extendLeft":100,"extendRight":100,"tier":"balanced"}'
```
## Response {#response}
### Initial Response (202 Accepted) {#initial-response-202-accepted}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"async": true
}
```
### Progress (SSE at `/api/v1/jobs/{jobId}/progress`) {#progress-sse-at-api-v1-jobs-jobid-progress}
```
event: progress
data: {"phase":"processing","stage":"Expanding canvas...","percent":50}
```
### Final Result (via SSE) {#final-result-via-sse}
```json
{
"phase": "complete",
"percent": 100,
"result": {
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/photo_extended.png",
"previewUrl": "/api/v1/download/{jobId}/preview.webp",
"originalSize": 300000,
"processedSize": 520000
}
}
```
## Notes {#notes}
- 需要安装 `object-eraser-colorize` 模型包（1-2 GB）。
- 使用基于 LaMa 的外绘为扩展区域生成内容。
- `tier` 参数在速度和质量之间权衡：`fast` 能快速产出结果但可能有瑕疵，`high` 耗时更长但能产出更平滑、更连贯的填充。
- 扩展值以像素为单位。最终图像尺寸将为：原始宽度 + extendLeft + extendRight 乘以 原始高度 + extendTop + extendBottom。
- 对于浏览器无法预览的输出格式（HEIC、JXL、TIFF），会在主输出旁生成一个 WebP 预览。
- 通过自动解码支持 HEIC/HEIF、RAW、TGA、PSD、EXR 和 HDR 输入格式。
apps/docs/zh-CN/tools/image/background-replace.md
+55
View File
@@ -0,0 +1,55 @@
---
description: "使用 AI 将图像背景替换为纯色或渐变。"
i18n_source_hash: 930fe8890e55
i18n_provenance: human
i18n_output_hash: cab14964451d
---
# Background Replace {#background-replace}
将图像背景替换为纯色或渐变。AI 模型会检测主体、移除原始背景，并将主体合成到你选择的背景上。
## API Endpoint {#api-endpoint}
`POST /api/v1/tools/image/background-replace`
接受包含图像文件和一个 JSON `settings` 字段的 multipart 表单数据。
## Parameters {#parameters}
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| backgroundType | string | 否 | `"color"` | 背景模式：`color` 或 `gradient` |
| color | string | 否 | `"#ffffff"` | 背景十六进制颜色（当 backgroundType 为 `color` 时） |
| gradientColor1 | string | 否 | - | 第一个渐变十六进制颜色 |
| gradientColor2 | string | 否 | - | 第二个渐变十六进制颜色 |
| gradientAngle | integer | 否 | `180` | 渐变角度（度，0-360） |
| feather | integer | 否 | `0` | 边缘羽化半径（0-20） |
| format | string | 否 | `"png"` | 输出格式：`png` 或 `webp` |
## Example Request {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/background-replace \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"backgroundType": "color", "color": "#2563eb", "feather": 2}'
```
## Example Response {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"async": true
}
```
通过 `GET /api/v1/jobs/{jobId}/progress` 处的 SSE 跟踪进度。任务完成后，SSE 流会发出一个带下载 URL 的 `completed` 事件。
## Notes {#notes}
- 这是一个 AI 驱动的工具，返回 `202 Accepted` 并异步处理。连接到 SSE 端点以接收进度更新和最终结果。
- 需要安装 **background-removal** 功能包。如果该包不可用，则返回 `501`。
- HEIC、RAW、PSD 和 SVG 输入在处理前会自动解码。
- 输出默认为 PNG，以保留主体周围的透明度。
apps/docs/zh-CN/tools/image/barcode-generate.md
+52
View File
@@ -0,0 +1,52 @@
---
description: "生成 Code 128、EAN-13、UPC-A、Code 39、ITF-14 和 Data Matrix 格式的条形码。"
i18n_source_hash: e84b1df40c7e
i18n_provenance: human
i18n_output_hash: 7106840d576a
---
# Barcode Generator {#barcode-generator}
从文本输入生成条形码图像。支持 Code 128、EAN-13、UPC-A、Code 39、ITF-14 和 Data Matrix 格式。
## API Endpoint {#api-endpoint}
`POST /api/v1/tools/image/barcode-generate`
接受一个 `application/json` 请求体（而非 multipart）。条形码由提供的文本生成，而不是由上传的文件生成。
## Parameters {#parameters}
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| text | string | 是 | - | 要编码到条形码中的文本（1-256 个字符） |
| type | string | 否 | `"code128"` | 条形码格式：`code128`、`ean13`、`upca`、`code39`、`itf14`、`datamatrix` |
| scale | integer | 否 | `3` | 图像缩放系数（1-8） |
| includeText | boolean | 否 | `true` | 是否在条形码下方渲染文本 |
## Example Request {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/barcode-generate \
-H "Authorization: Bearer si_your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "5901234123457", "type": "ean13", "scale": 4}'
```
## Example Response {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/barcode.png",
"originalSize": 0,
"processedSize": 4520
}
```
## Notes {#notes}
- 与大多数工具不同，此端点接受 JSON 请求体而非 multipart 表单数据，因为条形码是从文本生成的，而不是从上传的文件生成的。
- EAN-13 要求恰好 12 或 13 位数字。UPC-A 要求恰好 11 或 12 位数字。如果省略校验位，则会自动计算。
- Code 128 是最灵活的格式，支持完整的 ASCII 字符集。
- Data Matrix 生成二维条形码，适合在紧凑的方形中编码较长的字符串。
apps/docs/zh-CN/tools/image/barcode-read.md
+97
View File
@@ -0,0 +1,97 @@
---
description: "扫描图像中的二维码、条形码和 2D 码，并输出带标注的结果。"
i18n_source_hash: 97c9d395c257
i18n_provenance: human
i18n_output_hash: bd849112663a
---
# Barcode Reader {#barcode-reader}
扫描上传图像中的所有类型条形码和二维码。为每个检测到的码返回解码文本、条形码类型和位置数据。还会生成一张带标注的图像，在检测到的码周围绘制彩色边界框。
## API Endpoint {#api-endpoint}
`POST /api/v1/tools/image/barcode-read`
接受包含图像文件和一个可选 JSON `settings` 字段的 multipart 表单数据。
## Parameters {#parameters}
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| tryHarder | boolean | 否 | `true` | 为更难读取的条形码启用激进扫描模式（更慢但更彻底） |
## Example Request {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/barcode-read \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@receipt.jpg" \
-F 'settings={"tryHarder": true}'
```
## Example Response {#example-response}
```json
{
"filename": "receipt.jpg",
"barcodes": [
{
"type": "QRCode",
"text": "https://example.com/product/123",
"position": {
"topLeft": { "x": 100, "y": 50 },
"topRight": { "x": 250, "y": 50 },
"bottomLeft": { "x": 100, "y": 200 },
"bottomRight": { "x": 250, "y": 200 }
}
},
{
"type": "EAN-13",
"text": "5901234123457",
"position": {
"topLeft": { "x": 50, "y": 400 },
"topRight": { "x": 300, "y": 400 },
"bottomLeft": { "x": 50, "y": 450 },
"bottomRight": { "x": 300, "y": 450 }
}
}
],
"annotatedUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/annotated-receipt.png",
"previewUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/annotated-receipt.png"
}
```
## Response Fields {#response-fields}
| Field | Type | Description |
|-------|------|-------------|
| filename | string | 原始文件名 |
| barcodes | array | 检测到的条形码对象数组 |
| annotatedUrl | string 或 null | 下载带标注图像的 URL（未找到条形码时为 null） |
| previewUrl | string 或 null | 与 annotatedUrl 相同（用于前端预览兼容） |
### Barcode Object {#barcode-object}
| Field | Type | Description |
|-------|------|-------------|
| type | string | 条形码格式（QRCode、EAN-13、Code128、DataMatrix、PDF417 等） |
| text | string | 条形码的解码内容 |
| position | object | 带有 topLeft、topRight、bottomLeft、bottomRight 坐标的边界框 |
## Supported Barcode Types {#supported-barcode-types}
1D 条形码：Code128、Code39、Code93、Codabar、EAN-8、EAN-13、ITF、UPC-A、UPC-E
2D 条形码：QRCode、DataMatrix、PDF417、Aztec、MaxiCode
## Notes {#notes}
- 使用 zxing-wasm 库进行条形码检测。
- 带标注的图像会在每个检测到的条形码上叠加彩色多边形边界框和编号标签。
- 单张图像中最多可检测 255 个条形码。
- 如果未找到条形码，`barcodes` 为空数组，`annotatedUrl` 为 null。
- `tryHarder` 模式以处理时间为代价进行更彻底的扫描。对于干净、对齐良好的条形码，可禁用它以加快处理速度。
- 带标注的输出始终为 PNG 格式。
- HEIC、RAW、PSD 和 SVG 输入在扫描前会自动解码。
- EXIF 方向会在处理前自动应用。
apps/docs/zh-CN/tools/image/beautify.md
+85
View File
@@ -0,0 +1,85 @@
---
description: "将普通截图变成精致的图像，加上渐变背景、设备框架、阴影和社交媒体尺寸。"
i18n_source_hash: 8fd8a930a45e
i18n_provenance: human
i18n_output_hash: b9abf471fb21
---
# Beautify Screenshot {#beautify-screenshot}
为截图添加渐变背景、设备框架、阴影、水印和社交媒体尺寸。非常适合为产品营销、社交媒体和文档创建精致的图像。
## API Endpoint {#api-endpoint}
`POST /api/v1/tools/image/beautify`
## Parameters {#parameters}
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| backgroundType | string | 否 | `"linear-gradient"` | 背景类型：`solid`、`linear-gradient`、`radial-gradient`、`image`、`transparent` |
| backgroundColor | string | 否 | `"#667eea"` | 纯色背景颜色（当 `backgroundType` 为 `solid` 时使用） |
| gradientStops | array | 否 | `[{"color":"#667eea","position":0},{"color":"#764ba2","position":100}]` | 渐变色标（至少 2 个）。每个色标有 `color`（十六进制）和 `position`（0-100）。 |
| gradientAngle | number | 否 | 135 | 渐变角度（度，0 到 360） |
| padding | number | 否 | 64 | 图像周围的内边距（像素，0 到 256） |
| borderRadius | number | 否 | 12 | 截图的圆角半径（0 到 64） |
| shadowPreset | string | 否 | `"subtle"` | 阴影预设：`none`、`subtle`、`medium`、`dramatic`、`custom` |
| shadowBlur | number | 否 | 20 | 自定义阴影模糊半径（0 到 100，当 `shadowPreset` 为 `custom` 时使用） |
| shadowOffsetX | number | 否 | 0 | 自定义阴影水平偏移（-50 到 50） |
| shadowOffsetY | number | 否 | 10 | 自定义阴影垂直偏移（-50 到 50） |
| shadowColor | string | 否 | `"#000000"` | 自定义阴影颜色（十六进制） |
| shadowOpacity | number | 否 | 30 | 自定义阴影不透明度（0 到 100） |
| frame | string | 否 | `"none"` | 设备或窗口框架：`none`、`macos-light`、`macos-dark`、`windows-light`、`windows-dark`、`browser-light`、`browser-dark`、`iphone`、`iphone-dark`、`macbook`、`macbook-dark`、`ipad`、`ipad-dark` |
| frameTitle | string | 否 | - | 显示在窗口框架标题栏中的标题文本 |
| socialPreset | string | 否 | `"none"` | 调整到社交媒体尺寸：`none`、`twitter`、`linkedin`、`instagram-square`、`instagram-story`、`facebook`、`producthunt` |
| watermarkText | string | 否 | - | 可选的水印文本叠加 |
| watermarkPosition | string | 否 | `"bottom-right"` | 水印位置：`top-left`、`top-right`、`bottom-left`、`bottom-right`、`center` |
| watermarkOpacity | number | 否 | 50 | 水印不透明度（0 到 100） |
| outputFormat | string | 否 | `"png"` | 输出格式：`png`、`jpeg`、`webp` |
## Example Request {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/beautify \
-F "file=@screenshot.png" \
-F 'settings={"backgroundType":"linear-gradient","gradientStops":[{"color":"#667eea","position":0},{"color":"#764ba2","position":100}],"gradientAngle":135,"padding":64,"borderRadius":12,"shadowPreset":"medium","frame":"macos-dark","socialPreset":"twitter"}'
```
### With Background Image {#with-background-image}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/beautify \
-F "file=@screenshot.png" \
-F "backgroundImage=@bg-texture.jpg" \
-F 'settings={"backgroundType":"image","padding":80,"borderRadius":16,"shadowPreset":"dramatic"}'
```
## Example Response {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/screenshot.png",
"originalSize": 234567,
"processedSize": 567890
}
```
## Notes {#notes}
- 接受两个文件字段：`file`（必填，主截图）和 `backgroundImage`（可选，当 `backgroundType` 为 `image` 时使用）。
- 支持 HEIC、RAW、PSD 和 SVG 输入格式（自动解码）。
- 阴影预设映射到特定的值：
- `subtle`：模糊 20，offsetY 4，不透明度 20%
- `medium`：模糊 40，offsetY 10，不透明度 35%
- `dramatic`：模糊 80，offsetY 20，不透明度 50%
- 社交媒体预设使用 `contain` 模式将最终输出调整为适配目标尺寸：
- `twitter`：1600x900
- `linkedin`：1200x627
- `instagram-square`：1080x1080
- `instagram-story`：1080x1920
- `facebook`：1200x630
- `producthunt`：1270x760
- 设备框架（`iphone`、`macbook`、`ipad`）会在图像周围应用硬件边框，并跳过 `borderRadius` 设置。
- 当需要透明度时（阴影、圆角、设备框架或透明背景），即使选择了 `jpeg`，输出也会被强制为 PNG。
- 图像背景在管道/批处理模式下不受支持。
apps/docs/zh-CN/tools/image/blur-background.md
+51
View File
@@ -0,0 +1,51 @@
---
description: "使用 AI 在保持主体清晰的同时模糊背景。"
i18n_source_hash: 9073f10e6e9d
i18n_provenance: human
i18n_output_hash: 9e168c490af4
---
# Blur Background {#blur-background}
在保持主体清晰的同时模糊图像背景。AI 模型会隔离主体，对原始背景应用模糊，然后将清晰的主体合成到上方。
## API Endpoint {#api-endpoint}
`POST /api/v1/tools/image/blur-background`
接受包含图像文件和一个 JSON `settings` 字段的 multipart 表单数据。
## Parameters {#parameters}
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| intensity | integer | 否 | `50` | 模糊强度（1-100） |
| feather | integer | 否 | `0` | 边缘羽化半径（0-20） |
| format | string | 否 | `"png"` | 输出格式：`png` 或 `webp` |
## Example Request {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/blur-background \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"intensity": 75, "feather": 3}'
```
## Example Response {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"async": true
}
```
通过 `GET /api/v1/jobs/{jobId}/progress` 处的 SSE 跟踪进度。任务完成后，SSE 流会发出一个带下载 URL 的 `completed` 事件。
## Notes {#notes}
- 这是一个 AI 驱动的工具，返回 `202 Accepted` 并异步处理。连接到 SSE 端点以接收进度更新和最终结果。
- 需要安装 **background-removal** 功能包。如果该包不可用，则返回 `501`。
- 更高的强度值会产生更强的模糊效果。超过 80 的值会营造出明显的类似焦外虚化的分离感。
- HEIC、RAW、PSD 和 SVG 输入在处理前会自动解码。
apps/docs/zh-CN/tools/image/blur-faces.md
+96
View File
@@ -0,0 +1,96 @@
---
description: "使用 AI 人脸检测自动识别并模糊图像中的人脸，用于隐私保护和符合 GDPR 的匿名化。"
i18n_source_hash: fb861c12aea5
i18n_provenance: human
i18n_output_hash: 3a0007f60b8a
---
# Face / PII Blur {#face-pii-blur}
使用 AI 驱动的人脸检测（MediaPipe）自动识别并模糊图像中的人脸。
## API Endpoint {#api-endpoint}
`POST /api/v1/tools/image/blur-faces`
**处理方式：** 异步（返回 202，通过 SSE 轮询 `/api/v1/jobs/{jobId}/progress` 获取状态）
**模型包：** `face-detection`（200-300 MB）
## Parameters {#parameters}
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 图像文件（multipart） |
| blurRadius | number | 否 | `30` | 应用于检测到人脸的模糊半径（1-100） |
| sensitivity | number | 否 | `0.5` | 人脸检测灵敏度（0-1）。值越低，检测到的人脸越少但置信度越高 |
## Example Request {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/blur-faces \
-F "file=@group-photo.jpg" \
-F 'settings={"blurRadius":40,"sensitivity":0.3}'
```
## Response {#response}
### Initial Response (202 Accepted) {#initial-response-202-accepted}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"async": true
}
```
### Progress (SSE at `/api/v1/jobs/{jobId}/progress`) {#progress-sse-at-api-v1-jobs-jobid-progress}
```
event: progress
data: {"phase":"processing","stage":"Detecting faces...","percent":40}
```
### Final Result (via SSE) {#final-result-via-sse}
```json
{
"phase": "complete",
"percent": 100,
"result": {
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/group-photo_blurred.jpg",
"originalSize": 450000,
"processedSize": 420000,
"facesDetected": 3,
"faces": [
{"x": 100, "y": 50, "w": 80, "h": 80},
{"x": 300, "y": 60, "w": 75, "h": 75},
{"x": 500, "y": 55, "w": 85, "h": 85}
]
}
}
```
### No Faces Detected {#no-faces-detected}
如果未找到人脸，结果会包含一条警告：
```json
{
"phase": "complete",
"percent": 100,
"result": {
"facesDetected": 0,
"warning": "No faces detected in this image. Try increasing detection sensitivity."
}
}
```
## Notes {#notes}
- 需要安装 `face-detection` 模型包（200-300 MB）。
- 输出格式会自动与输入格式一致。
- `faces` 数组包含每个检测到人脸的边界框坐标（x、y、width、height）。
- 提高 `sensitivity`（接近 1.0）可检测更多人脸，包括部分遮挡的人脸。
- 通过自动解码支持 HEIC/HEIF、RAW、TGA、PSD、EXR 和 HDR 输入格式。
apps/docs/zh-CN/tools/image/border.md
+58
View File
@@ -0,0 +1,58 @@
---
description: "以可预测、可控的顺序为图像添加边框、内边距、圆角和投影。"
i18n_source_hash: 8845150736a9
i18n_provenance: human
i18n_output_hash: 55125f0d3031
---
# Border & Frame {#border-frame}
为图像添加边框、内边距、圆角和投影。该工具按顺序应用效果：内边距、边框、圆角，然后是阴影。
## API Endpoint {#api-endpoint}
`POST /api/v1/tools/image/border`
## Parameters {#parameters}
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| borderWidth | number | 否 | 10 | 边框厚度（像素，0 到 2000） |
| borderColor | string | 否 | `"#000000"` | 边框颜色（十六进制，例如 `#FF0000`） |
| padding | number | 否 | 0 | 图像与边框之间的内边距（像素，0 到 200） |
| paddingColor | string | 否 | `"#FFFFFF"` | 内边距填充颜色（十六进制） |
| cornerRadius | number | 否 | 0 | 圆角半径（像素，0 到 2000） |
| shadow | boolean | 否 | `false` | 是否添加投影 |
| shadowBlur | number | 否 | 15 | 阴影模糊半径（1 到 200） |
| shadowOffsetX | number | 否 | 0 | 阴影水平偏移（-50 到 50） |
| shadowOffsetY | number | 否 | 5 | 阴影垂直偏移（-50 到 50） |
| shadowColor | string | 否 | `"#000000"` | 阴影颜色（十六进制） |
| shadowOpacity | number | 否 | 40 | 阴影不透明度百分比（0 到 100） |
## Example Request {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/border \
-F "file=@photo.jpg" \
-F 'settings={"borderWidth":20,"borderColor":"#333333","cornerRadius":16,"shadow":true,"shadowBlur":25,"shadowOpacity":50}'
```
## Example Response {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.png",
"originalSize": 456789,
"processedSize": 523456
}
```
## Notes {#notes}
- 使用标准的 `createToolRoute` 工厂。通过 multipart 上传接受单个图像文件。
- 支持 HEIC、RAW、PSD 和 SVG 输入格式（自动解码）。
- 处理顺序：先添加内边距，然后边框环绕，接着应用圆角，最后合成阴影。
- 当启用 `cornerRadius` 或 `shadow` 时，输出会被强制为 PNG（无论输入格式如何）以保留透明度。支持 alpha 的格式（PNG、WebP、AVIF）保持其原始格式。
- 阴影会感知形状：它会跟随圆角，而不是创建矩形阴影。
- 将 `borderWidth` 设为 0 并仅使用 `cornerRadius` + `shadow`，可创建无框圆角阴影效果。
apps/docs/zh-CN/tools/image/bulk-rename.md
+75
View File
@@ -0,0 +1,75 @@
---
description: "使用模式模板重命名多个文件并以 ZIP 下载。"
i18n_source_hash: 2776dcc2f71c
i18n_provenance: human
i18n_output_hash: 4b35a9b3af6b
---
# Bulk Rename {#bulk-rename}
使用带有索引、补零索引和原始文件名占位符的模式模板重命名多个文件。返回一个包含所有重命名文件的 ZIP 归档。
## API Endpoint {#api-endpoint}
`POST /api/v1/tools/image/bulk-rename`
接受包含多个文件和一个 JSON `settings` 字段的 multipart 表单数据。
## Parameters {#parameters}
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| pattern | string | 否 | `"image-{{index}}"` | 带占位符的命名模式（最多 1000 个字符） |
| startIndex | number | 否 | `1` | 起始索引编号 |
### Pattern Placeholders {#pattern-placeholders}
| Placeholder | Description | Example |
|-------------|-------------|---------|
| `{{index}}` | 从 `startIndex` 开始的顺序编号 | `1`、`2`、`3` |
| `{{padded}}` | 补零的顺序编号 | `01`、`02`、`03` |
| `{{original}}` | 不含扩展名的原始文件名 | `photo`、`IMG_001` |
原始文件扩展名始终会被保留。
## Example Request {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/bulk-rename \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo1.jpg" \
-F "file=@photo2.jpg" \
-F "file=@photo3.jpg" \
-F 'settings={"pattern": "vacation-{{padded}}", "startIndex": 1}'
```
这会产生：`vacation-1.jpg`、`vacation-2.jpg`、`vacation-3.jpg`
使用原始文件名：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/bulk-rename \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@IMG_001.jpg" \
-F "file=@IMG_002.jpg" \
-F 'settings={"pattern": "2024-trip-{{original}}-{{index}}"}'
```
这会产生：`2024-trip-IMG_001-1.jpg`、`2024-trip-IMG_002-2.jpg`
## Example Response {#example-response}
响应是直接流式传输的 ZIP 文件（不是 JSON 响应）。响应标头为：
```
Content-Type: application/zip
Content-Disposition: attachment; filename="renamed-a1b2c3d4.zip"
```
## Notes {#notes}
- 此工具不处理图像。它只重命名文件并将其打包成 ZIP 归档。
- `{{padded}}` 的补零宽度会根据文件总数自动确定（例如 100 个文件会使用 3 位补零：`001`、`002` 等）。
- 文件扩展名会从原始文件名中保留。
- 文件名会被清理以移除不安全字符。
- 至少必须提供一个文件。
apps/docs/zh-CN/tools/image/circle-crop.md
+55
View File
@@ -0,0 +1,55 @@
---
description: "将图像裁剪为居中的圆形，四角透明。"
i18n_source_hash: 06c50ccd96b2
i18n_provenance: human
i18n_output_hash: 5cbadfef92bf
---
# Circle Crop {#circle-crop}
将图像裁剪为居中的圆形，四角透明。支持可调的缩放、偏移、边框和输出尺寸。
## API Endpoint {#api-endpoint}
`POST /api/v1/tools/image/circle-crop`
接受包含图像文件和一个 JSON `settings` 字段的 multipart 表单数据。
## Parameters {#parameters}
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| zoom | number | 否 | `1` | 缩放系数（1-5）；值越高裁剪越紧 |
| offsetX | number | 否 | `0.5` | 水平中心位置（0-1） |
| offsetY | number | 否 | `0.5` | 垂直中心位置（0-1） |
| borderWidth | integer | 否 | `0` | 边框宽度（像素，0-200） |
| borderColor | string | 否 | `"#ffffff"` | 边框十六进制颜色 |
| background | string | 否 | `"transparent"` | 四角填充：`"transparent"` 或十六进制颜色 |
| outputSize | integer | 否 | - | 最终正方形尺寸（像素，16-4096） |
## Example Request {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/circle-crop \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"zoom": 1.2, "borderWidth": 4, "borderColor": "#333333"}'
```
## Example Response {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.png",
"originalSize": 2450000,
"processedSize": 185000
}
```
## Notes {#notes}
- 输出始终为 PNG 以保留透明的四角（除非 `background` 被设为纯色）。
- 圆形内切于图像较短的一边。使用 `zoom` 裁剪更紧，使用 `offsetX`/`offsetY` 平移可见区域。
- 当提供 `outputSize` 时，结果会在裁剪后调整为该正方形尺寸。
- HEIC、RAW、PSD 和 SVG 输入在处理前会自动解码。
apps/docs/zh-CN/tools/image/collage.md
+92
View File
@@ -0,0 +1,92 @@
---
description: "使用 25 多种模板将多张图片合成为网格拼贴，可调整间距与圆角，并支持逐单元格平移与缩放。"
i18n_source_hash: 96f2055717df
i18n_provenance: human
i18n_output_hash: a4e5c1913881
---
# 拼贴 / 网格 {#collage-grid}
使用 25 多种模板将多张图片合成为精美的网格拼贴。支持 2-9 张图片的布局，可自定义间距、圆角半径、背景颜色，以及逐单元格的平移/缩放控制。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/collage`
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| templateId | string | 是 | - | 模板布局 ID（例如 `2-h-equal`、`3-left-large`、`4-grid`、`9-grid`） |
| cells | array | 否 | - | 逐单元格设置数组，包含 `imageIndex`、`panX`、`panY`、`zoom`、`objectFit` |
| cells[].imageIndex | integer | 是 | - | 放置到该单元格中的图片索引（从 0 开始） |
| cells[].panX | number | 否 | 0 | 水平平移偏移（-100 至 100） |
| cells[].panY | number | 否 | 0 | 垂直平移偏移（-100 至 100） |
| cells[].zoom | number | 否 | 1 | 缩放级别（1 至 10） |
| cells[].objectFit | string | 否 | `"cover"` | 图片填充单元格的方式：`cover` 或 `contain` |
| gap | number | 否 | 8 | 单元格之间的间距，单位像素（0 至 500） |
| cornerRadius | number | 否 | 0 | 每个单元格的圆角半径，单位像素（0 至 500） |
| backgroundColor | string | 否 | `"#FFFFFF"` | 背景颜色，十六进制或 `"transparent"` |
| aspectRatio | string | 否 | `"free"` | 画布宽高比：`free`、`1:1`、`4:3`、`3:2`、`16:9`、`9:16`、`4:5` |
| outputFormat | string | 否 | `"png"` | 输出格式：`png`、`jpeg`、`webp`、`avif`、`jxl` |
| quality | number | 否 | 90 | 输出质量（1 至 100） |
## 可用模板 {#available-templates}
| 模板 ID | 图片数 | 布局 |
|-------------|--------|--------|
| `2-h-equal` | 2 | 两列等宽 |
| `2-v-equal` | 2 | 两行等高 |
| `2-h-left-large` | 2 | 左侧 2/3，右侧 1/3 |
| `2-h-right-large` | 2 | 左侧 1/3，右侧 2/3 |
| `3-left-large` | 3 | 左侧大图，右侧上下两张 |
| `3-right-large` | 3 | 左侧上下两张，右侧大图 |
| `3-top-large` | 3 | 上方大图，下方两列 |
| `3-h-equal` | 3 | 三列等宽 |
| `3-v-equal` | 3 | 三行等高 |
| `4-grid` | 4 | 2x2 网格 |
| `4-left-large` | 4 | 左侧大图，右侧上下三张 |
| `4-top-large` | 4 | 上方大图，下方三列 |
| `4-bottom-large` | 4 | 上方三列，下方大图 |
| `5-top2-bottom3` | 5 | 上方两张，下方三张 |
| `5-top3-bottom2` | 5 | 上方三张，下方两张 |
| `5-left-large` | 5 | 左侧大图，右侧上下四张 |
| `5-center-large` | 5 | 中央大图，四角环绕 |
| `6-grid-2x3` | 6 | 2 列 x 3 行 |
| `6-grid-3x2` | 6 | 3 列 x 2 行 |
| `6-top-large` | 6 | 上方大图，下方五列 |
| `7-mosaic` | 7 | 马赛克布局 |
| `8-mosaic` | 8 | 马赛克布局 |
| `9-grid` | 9 | 3x3 网格 |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/collage \
-F "file=@photo1.jpg" \
-F "file=@photo2.jpg" \
-F "file=@photo3.jpg" \
-F "file=@photo4.jpg" \
-F 'settings={"templateId":"4-grid","gap":12,"cornerRadius":8,"backgroundColor":"#F5F5F5","outputFormat":"png","quality":90}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/collage.png",
"originalSize": 2456789,
"processedSize": 1823456
}
```
## 注意事项 {#notes}
- 在 multipart 请求中上传多个图片文件。图片按上传顺序分配到模板单元格。
- 如果上传的图片数量超过模板支持的数量，多余的图片会被忽略。
- 支持 HEIC、RAW、PSD 和 SVG 输入格式（自动解码）。
- 画布基础尺寸为最长边 2400px，并按所选宽高比缩放。
- 当 `aspectRatio` 为 `"free"` 时，画布默认为 4:3（2400x1800）。
- 逐单元格的 `panX`/`panY` 值会在单元格内移动裁剪窗口。值为 100 时完全移向一侧边缘，-100 则移向另一侧。
- `"transparent"` 背景颜色仅在 `png`、`webp` 或 `avif` 输出格式下才会保留。
apps/docs/zh-CN/tools/image/color-blindness.md
+62
View File
@@ -0,0 +1,62 @@
---
description: "模拟不同类型色觉障碍者眼中图片的呈现效果。"
i18n_source_hash: 0b537628ba79
i18n_provenance: human
i18n_output_hash: 20d2cb319160
---
# 色盲模拟 {#color-blindness-simulation}
模拟色觉障碍（CVD），预览各类色盲人群眼中图片的呈现效果。适用于设计、图表和 UI 的无障碍测试。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/color-blindness`
接受 multipart 表单数据，包含一个图片文件和一个 JSON `settings` 字段。
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| simulationType | string | 否 | `"deuteranomaly"` | 要模拟的色觉障碍类型 |
### 模拟类型 {#simulation-types}
| 值 | 状况 | 说明 |
|-------|-----------|-------------|
| `protanopia` | 红色盲 | 完全缺失红色视锥细胞 |
| `deuteranopia` | 绿色盲 | 完全缺失绿色视锥细胞 |
| `tritanopia` | 蓝色盲 | 完全缺失蓝色视锥细胞 |
| `protanomaly` | 红色弱 | 红色视锥细胞敏感度降低 |
| `deuteranomaly` | 绿色弱 | 绿色视锥细胞敏感度降低（最常见） |
| `tritanomaly` | 蓝色弱 | 蓝色视锥细胞敏感度降低 |
| `achromatopsia` | 全色盲 | 完全缺失色觉 |
| `blueConeMonochromacy` | 仅蓝色视锥 | 仅蓝色视锥细胞有功能 |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/color-blindness \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@design.png" \
-F 'settings={"simulationType": "deuteranopia"}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/design.png",
"originalSize": 1850000,
"processedSize": 1820000
}
```
## 注意事项 {#notes}
- 绿色弱（deuteranomaly）是默认选项，因为它是最常见的色觉障碍形式，约影响 6% 的男性。
- 该模拟使用颜色变换矩阵，建模视锥感光细胞减弱或缺失如何改变所感知的颜色。
- 此工具是非破坏性的，仅生成预览。它不会为了无障碍目的而修改原始图片。
- 输出格式与输入格式一致。HEIC、RAW、PSD 和 SVG 输入在处理前会自动解码。
apps/docs/zh-CN/tools/image/color-palette.md
+75
View File
@@ -0,0 +1,75 @@
---
description: "从图片中提取主色，作为调色板输出。"
i18n_source_hash: 65ab22dd75a9
i18n_provenance: human
i18n_output_hash: 6fbe48cf4d59
---
# 调色板 {#color-palette}
从图片中提取主色，并以十六进制颜色值返回。使用量化频率分析来识别最突出且视觉上最具区分度的颜色。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/color-palette`
接受 multipart 表单数据，包含一个图片文件和一个可选的 JSON `settings` 字段。
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| count | integer | 否 | `8` | 要提取的颜色数量（2-16） |
| format | string | 否 | `"hex"` | 颜色格式：`hex`、`rgb`、`hsl` |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/color-palette \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"count": 6, "format": "hex"}'
```
## 响应示例 {#example-response}
```json
{
"filename": "photo.jpg",
"colors": [
"#304080",
"#e0a060",
"#f0f0f0",
"#203020",
"#a0c0e0",
"#806040"
],
"hex": [
"#304080",
"#e0a060",
"#f0f0f0",
"#203020",
"#a0c0e0",
"#806040"
],
"count": 6
}
```
## 响应字段 {#response-fields}
| 字段 | 类型 | 说明 |
|-------|------|-------------|
| filename | string | 净化后的文件名 |
| colors | array | 按请求格式返回的颜色字符串数组，按主导程度排序（出现最频繁的在前） |
| hex | array | 十六进制颜色字符串数组（无论 `format` 设置如何，始终为十六进制） |
| count | number | 提取到的颜色数量 |
## 注意事项 {#notes}
- 最多返回 `count` 种主色（默认 8，范围 2-16），按频率排序（最常见的在前）。
- 图片在分析时会在内部缩放为 100x100 像素，因此调色板反映的是整体颜色分布，而非细小的细节。
- 颜色使用中位切分量化提取，该方法沿取值范围最宽的通道递归拆分像素群。
- 分析前会移除 alpha 通道，因此透明区域不会被纳入考虑。
- 这是一个只读端点。它不会生成可下载的输出文件或 `jobId`。
- HEIC、RAW、PSD 和 SVG 输入在分析前会自动解码。
apps/docs/zh-CN/tools/image/colorize.md
+80
View File
@@ -0,0 +1,80 @@
---
description: "使用 DDColor AI 模型自动为黑白或灰度照片上色。"
i18n_source_hash: 688aa3abbdae
i18n_provenance: human
i18n_output_hash: 2a1f7ac8236f
---
# AI 上色 {#ai-colorization}
使用 AI（DDColor 模型，以 OpenCV DNN 作为回退方案）将黑白或灰度照片转换为全彩。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/colorize`
**处理方式：** 异步（返回 202，通过 SSE 轮询 `/api/v1/jobs/{jobId}/progress` 获取状态）
**模型包：** `object-eraser-colorize`（1-2 GB）
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 图片文件（multipart） |
| intensity | number | 否 | `1.0` | 颜色强度（0-1）。较低的值会产生更柔和的上色效果 |
| model | string | 否 | `"auto"` | 使用的模型：`auto`、`ddcolor`、`opencv` |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/colorize \
-F "file=@old-bw-photo.jpg" \
-F 'settings={"intensity":0.9,"model":"auto"}'
```
## 响应 {#response}
### 初始响应（202 Accepted） {#initial-response-202-accepted}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"async": true
}
```
### 进度（SSE 位于 `/api/v1/jobs/{jobId}/progress`） {#progress-sse-at-api-v1-jobs-jobid-progress}
```
event: progress
data: {"phase":"processing","stage":"Colorizing...","percent":55}
```
### 最终结果（通过 SSE） {#final-result-via-sse}
```json
{
"phase": "complete",
"percent": 100,
"result": {
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/old-bw-photo_colorized.jpg",
"previewUrl": "/api/v1/download/{jobId}/preview.webp",
"originalSize": 180000,
"processedSize": 210000,
"width": 1920,
"height": 1080,
"method": "ddcolor"
}
}
```
## 注意事项 {#notes}
- 需要安装 `object-eraser-colorize` 模型包（1-2 GB）。
- DDColor 产生更高质量的结果但较慢；OpenCV DNN 更快，质量略低。`auto` 在可用时使用 DDColor，并以 OpenCV 作为回退方案。
- `intensity` 参数在原始灰度与 AI 上色结果之间进行混合。使用 1.0 获得全彩效果，较低的值可获得部分去饱和的复古外观。
- 输出格式会自动与输入格式一致。
- 对于无法在浏览器中预览的输出格式，会在主输出旁一并生成 WebP 预览。
- 通过自动解码支持 HEIC/HEIF、RAW、TGA、PSD、EXR 和 HDR 输入格式。
apps/docs/zh-CN/tools/image/compare.md
+68
View File
@@ -0,0 +1,68 @@
---
description: "并排比较两张图片，进行像素级差异可视化并给出相似度评分。"
i18n_source_hash: cc0a02bd75c6
i18n_provenance: human
i18n_output_hash: e5ea400c8d8b
---
# 图片比较 {#image-compare}
上传两张图片以计算像素级差异图和数值相似度百分比。输出是一张用红色高亮标出变化区域的差异图。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/compare`
接受 multipart 表单数据，包含**两个**图片文件。无需 settings 字段。
## 参数 {#parameters}
此工具没有可配置的参数。请恰好上传两个图片文件。
| 字段 | 类型 | 必填 | 说明 |
|-------|------|----------|-------------|
| file（第一张） | file | 是 | 第一张图片 |
| file（第二张） | file | 是 | 第二张图片 |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/compare \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@original.jpg" \
-F "file=@modified.jpg"
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"similarity": 94.52,
"dimensions": { "width": 1920, "height": 1080 },
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/diff.png",
"originalSize": 4900000,
"processedSize": 280000
}
```
## 响应字段 {#response-fields}
| 字段 | 类型 | 说明 |
|-------|------|-------------|
| jobId | string | 用于下载差异图的作业标识符 |
| similarity | number | 两张图片之间的相似度百分比（0 至 100） |
| dimensions | object | 用于比较的宽度和高度 |
| downloadUrl | string | 下载生成的差异图的 URL |
| originalSize | number | 两张输入图片的合计大小，单位字节 |
| processedSize | number | 差异输出图片的大小，单位字节 |
## 注意事项 {#notes}
- 两张图片在比较前会被缩放到相同尺寸（取各轴的最大值）。
- 差异图以红色高亮标出差异，透明度与变化幅度成正比。相同或几乎相同的像素（差异 < 10）显示为原图的半透明版本。
- 相似度按所有像素平均像素差异的反值计算，并以百分比表示。
- 相似度为 100% 表示两张图片逐像素相同（在比较分辨率下）。
- 无论输入格式如何，差异输出始终为 PNG 格式。
- 两张图片在比较前都会被验证并解码（支持 HEIC、RAW、PSD、SVG）。
- 处理前会在两张图片上自动应用 EXIF 方向。
apps/docs/zh-CN/tools/image/compose.md
+87
View File
@@ -0,0 +1,87 @@
---
description: "使用位置、不透明度和混合模式对图片进行分层合成。"
i18n_source_hash: c5d09eb13fde
i18n_provenance: human
i18n_output_hash: e8457c20e348
---
# 图片合成 {#image-composition}
将叠加图片放在底图之上，并可配置位置、不透明度和混合模式。适用于合成 Logo、图形，或将多张图片组合在一起。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/compose`
接受 multipart 表单数据，包含**两个**图片文件和一个 JSON `settings` 字段。
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| x | number | 否 | `0` | 叠加图相对左上角的水平偏移，单位像素（最小 0） |
| y | number | 否 | `0` | 叠加图相对左上角的垂直偏移，单位像素（最小 0） |
| opacity | number | 否 | `100` | 叠加图不透明度百分比（0 至 100） |
| blendMode | string | 否 | `"over"` | 合成混合模式 |
### 混合模式 {#blend-modes}
| 值 | 说明 |
|-------|-------------|
| `over` | 普通叠加（默认） |
| `multiply` | 通过相乘像素值使画面变暗 |
| `screen` | 通过反相、相乘再反相使画面变亮 |
| `overlay` | 根据底图亮度结合正片叠底与滤色 |
| `darken` | 保留每一层中较暗的像素 |
| `lighten` | 保留每一层中较亮的像素 |
| `hard-light` | 强对比叠加 |
| `soft-light` | 柔和对比叠加 |
| `difference` | 各层之间的绝对差值 |
| `exclusion` | 类似差值，但对比度较低 |
### 文件字段 {#file-fields}
| 字段名 | 必填 | 说明 |
|------------|----------|-------------|
| file | 是 | 底图/背景图片 |
| overlay | 是 | 叠加图/前景图片 |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/compose \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@background.jpg" \
-F "overlay=@graphic.png" \
-F 'settings={"x": 100, "y": 50, "opacity": 80, "blendMode": "over"}'
```
使用正片叠底混合模式：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/compose \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F "overlay=@texture.jpg" \
-F 'settings={"x": 0, "y": 0, "opacity": 50, "blendMode": "multiply"}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/background.jpg",
"originalSize": 3200000,
"processedSize": 3450000
}
```
## 注意事项 {#notes}
- 两张图片在合成前都会被验证并解码（支持 HEIC、RAW、PSD、SVG）。
- 叠加图会被放置在由 `x` 和 `y` 指定的精确像素坐标处。它不会被缩放以适配。
- 如果不透明度小于 100，在混合前会对叠加图应用一个 alpha 蒙版。
- 叠加图可以超出底图边界（超出部分会被裁剪）。
- 处理前会在两张图片上自动应用 EXIF 方向。
- 输出尺寸与底图尺寸一致。
apps/docs/zh-CN/tools/image/compress.md
+62
View File
@@ -0,0 +1,62 @@
---
description: "按质量级别或目标文件大小减小图片文件体积。"
i18n_source_hash: af4685da7e64
i18n_provenance: human
i18n_output_hash: e50a856e4af0
---
# 压缩 {#compress}
通过指定质量级别或以千字节为单位的目标文件大小来减小图片文件体积。该工具使用迭代二分搜索来精确命中目标大小。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/compress`
接受 multipart 表单数据，包含一个图片文件和一个 JSON `settings` 字段。
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| mode | string | 否 | `"quality"` | 压缩模式：`quality` 或 `targetSize` |
| quality | number | 否 | `80` | 质量级别（1-100）。在 mode 为 `quality` 时使用。 |
| targetSizeKb | number | 否 | - | 目标文件大小，单位千字节。在 mode 为 `targetSize` 时使用。 |
## 请求示例 {#example-request}
压缩到质量 60：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/compress \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"mode": "quality", "quality": 60}'
```
压缩到目标大小 200 KB：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/compress \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"mode": "targetSize", "targetSizeKb": 200}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
"originalSize": 2450000,
"processedSize": 204800
}
```
## 注意事项 {#notes}
- 在 `quality` 模式下，较低的值会产生更小的文件，但压缩伪影更多。值为 80 对网页用途来说是一个不错的默认值。
- 在 `targetSize` 模式下，引擎会执行迭代压缩，在不超过目标的前提下尽可能接近目标大小。
- 输出格式与输入格式一致。压缩应用于该格式的原生编码（例如 JPEG 文件使用 JPEG 质量，WebP 文件使用 WebP 质量）。
- 如果默认质量（80）可以接受，你可以完全省略 `quality` 参数。
apps/docs/zh-CN/tools/image/content-aware-resize.md
+64
View File
@@ -0,0 +1,64 @@
---
description: "基于接缝裁剪的缩放，沿低重要性路径增删像素，以保留关键内容和人脸。"
i18n_source_hash: f383b28ab62a
i18n_provenance: human
i18n_output_hash: 94de49a9eacf
---
# 内容感知缩放 {#content-aware-resize}
基于接缝裁剪的缩放，智能地沿视觉重要性最低的路径删除或增加像素，保留重要内容并可选地保护人脸。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/content-aware-resize`
**处理方式：** 同步（直接返回结果）
**模型包：** 基本操作无需模型包。如果启用人脸保护，则使用 `face-detection` 模型包（200-300 MB）。
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 图片文件（multipart） |
| width | number | 否 | - | 目标宽度，单位像素 |
| height | number | 否 | - | 目标高度，单位像素 |
| protectFaces | boolean | 否 | `false` | 检测并保护人脸，避免被接缝删除 |
| blurRadius | number | 否 | `4` | 用于能量计算的预处理模糊半径（0-20） |
| sobelThreshold | number | 否 | `2` | Sobel 边缘检测阈值（1-20）。值越高算法越激进 |
| square | boolean | 否 | `false` | 缩放为正方形（使用较小的一边） |
必须至少指定 `width`、`height` 或 `square` 之一。
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/content-aware-resize \
-F "file=@landscape.jpg" \
-F 'settings={"width":800,"protectFaces":true}'
```
## 响应（200 OK） {#response-200-ok}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/landscape_seam.png",
"originalSize": 450000,
"processedSize": 380000,
"width": 800,
"height": 600
}
```
## 注意事项 {#notes}
- 此自定义路由目前返回同步的 200 响应。
- 使用 `caire` 接缝裁剪库进行内容感知缩放。
- 仅缩小尺寸（删除接缝）。无法将图片扩展到超过其原始尺寸。
- `protectFaces` 选项使用 AI 人脸检测将人脸区域标记为高能量，防止接缝穿过人脸。
- `blurRadius` 控制能量图计算前的平滑程度。较高的值会使能量图更均匀，这有助于处理噪点较多的图片。
- `sobelThreshold` 影响边缘检测的激进程度。较低的值会保留更多细微的边缘。
- 输出始终为 PNG 格式。
- 通过自动解码支持 HEIC/HEIF、RAW、TGA、PSD、EXR 和 HDR 输入格式。
apps/docs/zh-CN/tools/image/convert.md
+84
View File
@@ -0,0 +1,84 @@
---
description: "在各种格式之间转换图片，包括 AVIF、JXL 和 HEIC 等现代格式。"
i18n_source_hash: 562f8270e8c3
i18n_provenance: human
i18n_output_hash: 238017f07183
---
# 转换 {#convert}
在各种格式之间转换图片。支持常见的网页格式，以及 HEIC、JXL、BMP、ICO、JP2、QOI 和 PSD 等专业格式。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/convert`
接受 multipart 表单数据，包含一个图片文件和一个 JSON `settings` 字段。
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| format | string | 是 | - | 目标格式：`jpg`、`png`、`webp`、`avif`、`tiff`、`gif`、`heic`、`heif`、`jxl`、`bmp`、`ico`、`jp2`、`qoi`、`psd`、`ppm`、`eps`、`tga` |
| quality | number | 否 | - | 输出质量（1-100）。适用于 jpg、webp、avif、heic 等有损格式。 |
## 支持的输出格式 {#supported-output-formats}
| 格式 | 类型 | 说明 |
|--------|------|-------|
| jpg | 有损 | JPEG，兼容性最佳 |
| png | 无损 | 支持透明 |
| webp | 两者 | 现代网页格式，压缩效果好 |
| avif | 有损 | 下一代格式，压缩效果极佳 |
| tiff | 两者 | 印刷/出版工作流 |
| gif | 无损 | 限于 256 种颜色 |
| heic / heif | 有损 | Apple 生态系统格式 |
| jxl | 两者 | JPEG XL，下一代格式 |
| bmp | 无损 | 未压缩位图 |
| ico | 无损 | Windows 图标格式 |
| jp2 | 有损 | JPEG 2000 |
| qoi | 无损 | Quite OK Image 格式 |
| psd | 分层 | Adobe Photoshop（需要 ImageMagick） |
| ppm | 无损 | Portable Pixmap（PPM/PGM/PBM） |
| eps | 矢量 | Encapsulated PostScript |
| tga | 无损 | Targa 图片格式 |
## 请求示例 {#example-request}
转换为 WebP：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/convert \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"format": "webp", "quality": 85}'
```
转换为 PNG（无损）：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/convert \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"format": "png"}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.webp",
"originalSize": 2450000,
"processedSize": 680000
}
```
## 注意事项 {#notes}
- 输出文件名的扩展名会自动更新以匹配目标格式。
- SVG 输入在转换前会以 300 DPI 光栅化。
- PSD 转换需要在服务器上安装 ImageMagick。
- BMP、EPS、ICO、JP2、JXL、PPM、QOI 和 TGA 使用专门的 CLI 编码器，并绕过 Sharp 处理。
- HEIC/HEIF 编码使用系统的 HEIC 编码器库。
- 输入格式范围很广：JPEG、PNG、WebP、AVIF、TIFF、GIF、HEIC、RAW（CR2、NEF、ARW 等）、PSD、SVG、BMP 等。
apps/docs/zh-CN/tools/image/crop.md
+62
View File
@@ -0,0 +1,62 @@
---
description: "通过指定位置和尺寸的区域裁剪图片。"
i18n_source_hash: aab38ccd7c53
i18n_provenance: human
i18n_output_hash: 6d45b3b09301
---
# 裁剪 {#crop}
通过位置和尺寸定义一个矩形区域来裁剪图片。支持像素和百分比两种单位。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/crop`
接受 multipart 表单数据，包含一个图片文件和一个 JSON `settings` 字段。
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| left | number | 是 | - | 裁剪区域的 X 偏移（从左边缘起） |
| top | number | 是 | - | 裁剪区域的 Y 偏移（从上边缘起） |
| width | number | 是 | - | 裁剪区域的宽度 |
| height | number | 是 | - | 裁剪区域的高度 |
| unit | string | 否 | `"px"` | 这些值的单位：`px` 或 `percent` |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/crop \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"left": 100, "top": 50, "width": 800, "height": 600}'
```
使用百分比值裁剪：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/crop \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"left": 10, "top": 10, "width": 80, "height": 80, "unit": "percent"}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
"originalSize": 2450000,
"processedSize": 1200000
}
```
## 注意事项 {#notes}
- 裁剪区域必须位于图片边界之内。如果区域超出图片范围，请求将失败。
- 使用 `percent` 单位时，这些值表示图片尺寸的百分比（例如 `left: 10` 表示从左边缘起 10%）。
- 输出格式与输入格式一致。
- 裁剪前会自动应用 EXIF 方向，因此坐标对应于视觉上正确的方向。
apps/docs/zh-CN/tools/image/duotone.md
+50
View File
@@ -0,0 +1,50 @@
---
description: "应用双色调效果，可自定义阴影色和高光色。"
i18n_source_hash: ab99c4f0152c
i18n_provenance: human
i18n_output_hash: 26094fc96843
---
# 双色调 {#duotone}
为图片应用双色调效果。图片先被转换为灰度，然后映射到阴影色（暗部色调）与高光色（亮部色调）之间的渐变。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/duotone`
接受 multipart 表单数据，包含一个图片文件和一个 JSON `settings` 字段。
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| shadow | string | 否 | `"#1e3a8a"` | 阴影十六进制颜色（应用于暗部色调） |
| highlight | string | 否 | `"#fbbf24"` | 高光十六进制颜色（应用于亮部色调） |
| intensity | integer | 否 | `100` | 效果强度（0-100）；0 返回原图，100 应用完整双色调 |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/duotone \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"shadow": "#0f172a", "highlight": "#f97316", "intensity": 80}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
"originalSize": 2450000,
"processedSize": 1870000
}
```
## 注意事项 {#notes}
- 输出格式与输入格式一致。HEIC、RAW、PSD 和 SVG 输入在处理前会自动解码。
- `intensity` 小于 100 时会将双色调结果与原始图片混合，从而获得更柔和的效果。
- 常见的双色调搭配包括藏青/金、青绿/珊瑚，以及紫色/粉色。
apps/docs/zh-CN/tools/image/edit-metadata.md
+108
View File
@@ -0,0 +1,108 @@
---
description: "编辑图片中的 EXIF、IPTC、GPS 和 XMP 元数据字段，无需重新编码像素。"
i18n_source_hash: a37746db11c3
i18n_provenance: human
i18n_output_hash: 7b3853980f3b
---
# 编辑元数据 {#edit-metadata}
编辑图片的元数据字段，包括 EXIF、IPTC、GPS 坐标、日期和关键词。底层使用 ExifTool，因此元数据是就地写入的，无需重新编码像素，从而完整保留图片质量。
## API 端点 {#api-endpoints}
### 编辑元数据 {#edit-metadata-1}
`POST /api/v1/tools/image/edit-metadata`
将元数据字段写入图片并返回修改后的文件。
### 检查元数据 {#inspect-metadata}
`POST /api/v1/tools/image/edit-metadata/inspect`
通过 ExifTool 以 JSON 形式返回图片的完整元数据。不会修改图片。
## 参数（编辑） {#parameters-edit}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| title | string | 否 | - | 图片标题（XMP/EXIF） |
| author | string | 否 | - | 作者姓名 |
| artist | string | 否 | - | 艺术家姓名（EXIF Artist 标签） |
| copyright | string | 否 | - | 版权声明 |
| imageDescription | string | 否 | - | 图片描述（EXIF） |
| software | string | 否 | - | 软件标签 |
| dateTime | string | 否 | - | EXIF DateTime 值 |
| dateTimeOriginal | string | 否 | - | EXIF DateTimeOriginal 值 |
| setAllDates | string | 否 | - | 一次性设置所有日期字段 |
| dateShift | string | 否 | - | 按偏移量平移所有日期（格式：`+HH:MM` 或 `-HH:MM`） |
| clearGps | boolean | 否 | `false` | 移除所有 GPS 数据 |
| gpsLatitude | number | 否 | - | 设置 GPS 纬度（-90 至 90） |
| gpsLongitude | number | 否 | - | 设置 GPS 经度（-180 至 180） |
| gpsAltitude | number | 否 | - | 设置 GPS 海拔，单位米 |
| keywords | string[] | 否 | - | 要添加或设置的关键词/标签 |
| keywordsMode | string | 否 | `"add"` | 关键词处理方式：`add`（追加）或 `set`（替换） |
| fieldsToRemove | string[] | 否 | `[]` | 要移除的特定元数据字段名列表 |
| iptcTitle | string | 否 | - | IPTC 对象名称 |
| iptcHeadline | string | 否 | - | IPTC 标题 |
| iptcCity | string | 否 | - | IPTC 城市 |
| iptcState | string | 否 | - | IPTC 省/州 |
| iptcCountry | string | 否 | - | IPTC 国家 |
## 请求示例 {#example-request}
设置作者和版权：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/edit-metadata \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"author": "Jane Smith", "copyright": "2024 Jane Smith"}'
```
设置 GPS 坐标：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/edit-metadata \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"gpsLatitude": 48.8566, "gpsLongitude": 2.3522, "gpsAltitude": 35}'
```
移除 GPS 并添加关键词：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/edit-metadata \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"clearGps": true, "keywords": ["landscape", "sunset"], "keywordsMode": "add"}'
```
检查元数据：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/edit-metadata/inspect \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg"
```
## 响应示例（编辑） {#example-response-edit}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
"originalSize": 2450000,
"processedSize": 2452000
}
```
## 注意事项 {#notes}
- 此工具需要在服务器上安装 ExifTool。Docker 镜像中已包含它。
- 元数据是就地写入的，因此不会发生像素重新编码。文件大小的变化极小（仅为元数据字节）。
- `dateShift` 参数按指定偏移量平移所有日期字段，适用于修正时区错误（例如 `+02:00` 或 `-05:30`）。
- 如果未请求任何更改（所有参数都省略或为空），则原始文件将原样返回。
- 支持的格式：JPEG、PNG、WebP、AVIF、TIFF、GIF、HEIC/HEIF。
- 对于无法在浏览器中预览的格式（HEIF、TIFF），响应会包含一个 `previewUrl` 字段，附带 WebP 预览。
apps/docs/zh-CN/tools/image/enhance-faces.md
+85
View File
@@ -0,0 +1,85 @@
---
description: "使用 GFPGAN 和 CodeFormer AI 模型修复并锐化图片中模糊或低质量的人脸。"
i18n_source_hash: 7f9f6af8ebda
i18n_provenance: human
i18n_output_hash: e599fd8468f7
---
# 人脸增强 {#face-enhancement}
使用 AI 模型（GFPGAN/CodeFormer）修复并增强图片中的人脸。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/enhance-faces`
**处理方式：** 异步（返回 202，通过 SSE 轮询 `/api/v1/jobs/{jobId}/progress` 获取状态）
**模型包：** `upscale-enhance`（5-6 GB）和 `face-detection`（200-300 MB）
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 图片文件（multipart） |
| model | string | 否 | `"auto"` | 使用的模型：`auto`、`gfpgan`、`codeformer` |
| strength | number | 否 | `0.8` | 增强强度（0-1）。值越高增强越强 |
| onlyCenterFace | boolean | 否 | `false` | 仅增强最居中/最突出的人脸 |
| sensitivity | number | 否 | `0.5` | 人脸检测灵敏度（0-1） |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/enhance-faces \
-F "file=@portrait.jpg" \
-F 'settings={"model":"codeformer","strength":0.7,"onlyCenterFace":false}'
```
## 响应 {#response}
### 初始响应（202 Accepted） {#initial-response-202-accepted}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"async": true
}
```
### 进度（SSE 位于 `/api/v1/jobs/{jobId}/progress`） {#progress-sse-at-api-v1-jobs-jobid-progress}
```
event: progress
data: {"phase":"processing","stage":"Enhancing faces...","percent":60}
```
### 最终结果（通过 SSE） {#final-result-via-sse}
```json
{
"phase": "complete",
"percent": 100,
"result": {
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/portrait_enhanced.png",
"previewUrl": "/api/v1/download/{jobId}/preview.webp",
"originalSize": 350000,
"processedSize": 600000,
"facesDetected": 2,
"faces": [
{"x": 120, "y": 80, "w": 100, "h": 100},
{"x": 350, "y": 90, "w": 95, "h": 95}
],
"model": "codeformer"
}
}
```
## 注意事项 {#notes}
- 需要同时安装 `upscale-enhance` 模型包（5-6 GB）和 `face-detection` 模型包（200-300 MB）。
- GFPGAN 产生更激进的增强；CodeFormer 更好地保留身份特征。`auto` 会为输入选择最佳模型。
- 输出始终为 PNG 格式，以获得最高质量。
- 会在全分辨率输出旁一并生成 WebP 预览，以加快前端显示。
- `strength` 参数将增强后的人脸与原始人脸混合。使用较低的值（0.3-0.5）获得细微改善，使用较高的值（0.7-1.0）获得更强的修复。
- 通过自动解码支持 HEIC/HEIF、RAW、TGA、PSD、EXR 和 HDR 输入格式。
apps/docs/zh-CN/tools/image/erase-object.md
+79
View File
@@ -0,0 +1,79 @@
---
description: "使用 AI 图像修复（LaMa）从图片中移除不需要的对象，由标注要擦除区域的蒙版引导。"
i18n_source_hash: 8e2e42a5e4f9
i18n_provenance: human
i18n_output_hash: 15f31fd8bd25
---
# 对象擦除 {#object-eraser}
使用 AI 图像修复（LaMa 模型）从图片中移除不需要的对象。接受一张图片和一张标注要擦除区域的蒙版。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/erase-object`
**处理方式：** 异步（返回 202，通过 SSE 轮询 `/api/v1/jobs/{jobId}/progress` 获取状态）
**模型包：** `object-eraser-colorize`（1-2 GB）
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 源图片文件（multipart） |
| mask | file | 是 | - | 蒙版图片（白色 = 要擦除的区域，黑色 = 保留）。必须以字段名 `mask` 上传 |
| format | string | 否 | `"auto"` | 输出格式：`auto`、`png`、`jpg`、`jpeg`、`webp`、`tiff`、`gif`、`avif`、`heic`、`heif`、`jxl` |
| quality | integer | 否 | `95` | 输出质量（1-100） |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/erase-object \
-F "file=@photo.jpg" \
-F "mask=@mask.png" \
-F "format=png" \
-F "quality=95"
```
## 响应 {#response}
### 初始响应（202 Accepted） {#initial-response-202-accepted}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"async": true
}
```
### 进度（SSE 位于 `/api/v1/jobs/{jobId}/progress`） {#progress-sse-at-api-v1-jobs-jobid-progress}
```
event: progress
data: {"phase":"processing","stage":"Inpainting...","percent":70}
```
### 最终结果（通过 SSE） {#final-result-via-sse}
```json
{
"phase": "complete",
"percent": 100,
"result": {
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/photo_erased.png",
"previewUrl": "/api/v1/download/{jobId}/preview.webp",
"originalSize": 245000,
"processedSize": 230000
}
}
```
## 注意事项 {#notes}
- 需要安装 `object-eraser-colorize` 模型包（1-2 GB）。
- 蒙版必须与源图片尺寸相同。白色像素表示要擦除的区域；AI 会用合理的内容填充这些区域。
- 使用 LaMa（Large Mask Inpainting，大蒙版图像修复）实现高质量的对象移除。
- 对于无法在浏览器中预览的输出格式，会在主输出旁一并生成 WebP 预览。
- 通过自动解码支持 HEIC/HEIF、RAW、TGA、PSD、EXR 和 HDR 输入格式。
apps/docs/zh-CN/tools/image/favicon.md
+93
View File
@@ -0,0 +1,93 @@
---
description: "从源图像生成所有标准的 favicon 和应用图标尺寸。"
i18n_source_hash: 3a6451a94b7a
i18n_provenance: human
i18n_output_hash: e05c94ba7ba2
---
# Favicon 生成器 {#favicon-generator}
从源图像生成一整套 favicon 和应用图标文件。生成浏览器、Apple 设备和 Android 所需的所有标准尺寸，并附带一个 web manifest 和一段 HTML 代码片段。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/favicon`
接受包含一个或多个图像文件的 multipart 表单数据，以及一个可选的 JSON `settings` 字段。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| background | string | 否 | - | 背景十六进制颜色（例如 `"#ffffff"`）。设置后，图标会被平整到此颜色上。 |
| padding | integer | 否 | `0` | 图标内容周围的内边距百分比（0 到 40） |
| radius | integer | 否 | `0` | 圆角图标的圆角半径百分比（0 到 50） |
| sizes | integer[] | 否 | - | 将输出限制为指定的像素尺寸（例如 `[16, 32, 180]`）。省略则生成所有标准尺寸。 |
| themeColor | string | 否 | `"#ffffff"` | web manifest 的主题色十六进制值 |
## 生成的文件 {#generated-files}
对于每张输入图像，会生成以下文件：
| 文件 | 尺寸 | 用途 |
|------|------|---------|
| `favicon-16x16.png` | 16x16 | 浏览器标签页图标 |
| `favicon-32x32.png` | 32x32 | 浏览器标签页图标（HiDPI） |
| `favicon-48x48.png` | 48x48 | 桌面快捷方式 |
| `apple-touch-icon.png` | 180x180 | iOS 主屏幕 |
| `android-chrome-192x192.png` | 192x192 | Android 主屏幕 |
| `android-chrome-512x512.png` | 512x512 | Android 启动画面 |
| `favicon.ico` | 32x32 | 传统 ICO 格式 |
| `manifest.json` | - | 带图标引用的 Web 应用 manifest |
| `favicon-snippet.html` | - | 即用型 HTML link 标签 |
## 请求示例 {#example-request}
带圆角和内边距的单个源图像：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/favicon \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@logo.png" \
-F 'settings={"padding": 10, "radius": 20, "themeColor": "#0a0a0a"}'
```
多个源图像（每个都会在子文件夹中获得自己的一套文件）：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/favicon \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@logo-light.png" \
-F "file=@logo-dark.png"
```
## 响应示例 {#example-response}
响应是直接流式传输的 ZIP 文件。响应头为：
```
Content-Type: application/zip
Content-Disposition: attachment; filename="favicons-a1b2c3d4.zip"
```
## 包含的 HTML 代码片段 {#html-snippet-included}
ZIP 中包含一个 `favicon-snippet.html` 文件，你可以将其粘贴到 HTML 的 `<head>` 中：
```html
<!-- Favicons -->
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="48x48" href="/favicon-48x48.png">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
<link rel="manifest" href="/manifest.json">
```
## 说明 {#notes}
- 源图像使用 `cover` 适配模式进行缩放，也就是说会被裁剪以填满每个方形尺寸。为获得最佳效果，请使用方形源图像。
- 上传多个文件时，每个文件都会在 ZIP 中获得自己的子文件夹（以源文件命名）。
- 对于单个文件上传，所有输出都位于 ZIP 的根目录，没有子文件夹。
- 验证或解码失败的文件会被跳过，ZIP 中会包含一个 `skipped-files.txt` 来说明相关问题。
- 支持的输入格式：JPEG、PNG、WebP、AVIF、TIFF、GIF、HEIC、SVG、RAW、PSD 等。
- 在缩放前会自动应用 EXIF 方向信息。
apps/docs/zh-CN/tools/image/find-duplicates.md
+115
View File
@@ -0,0 +1,115 @@
---
description: "使用感知哈希检测重复和近似重复的图像。"
i18n_source_hash: 4e1f4413f90f
i18n_provenance: human
i18n_output_hash: 2cf60b9dc81a
---
# 查找重复项 {#find-duplicates}
上传多张图像，使用感知哈希（dHash）检测重复和近似重复的图像。将相似图像分组，识别每组中质量最佳的版本，并计算可节省的潜在空间。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/find-duplicates`
接受包含多个图像文件的 multipart 表单数据，以及一个可选的 JSON `settings` 字段。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| threshold | number | 否 | `8` | 将图像视为重复项的最大汉明距离（0 到 20）。值越小匹配越严格 |
### 文件字段 {#file-fields}
在 multipart 请求中上传至少 2 个图像文件（全部使用 `file` 字段名，或对文件部分使用任意字段名）。
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/find-duplicates \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo1.jpg" \
-F "file=@photo2.jpg" \
-F "file=@photo3.jpg" \
-F "file=@photo4.jpg" \
-F 'settings={"threshold": 8}'
```
## 响应示例 {#example-response}
```json
{
"totalImages": 4,
"duplicateGroups": [
{
"groupId": 1,
"files": [
{
"filename": "photo1.jpg",
"similarity": 100,
"width": 4032,
"height": 3024,
"fileSize": 2450000,
"format": "jpeg",
"isBest": true,
"thumbnail": "data:image/jpeg;base64,/9j/..."
},
{
"filename": "photo2.jpg",
"similarity": 96.88,
"width": 1920,
"height": 1440,
"fileSize": 850000,
"format": "jpeg",
"isBest": false,
"thumbnail": "data:image/jpeg;base64,/9j/..."
}
]
}
],
"uniqueImages": 2,
"spaceSaveable": 850000,
"skippedFiles": []
}
```
## 响应字段 {#response-fields}
| 字段 | 类型 | 说明 |
|-------|------|-------------|
| totalImages | number | 成功分析的图像数量 |
| duplicateGroups | array | 重复图像的分组 |
| uniqueImages | number | 不属于任何重复分组的图像数量 |
| spaceSaveable | number | 移除非最佳重复项后可节省的总字节数 |
| skippedFiles | array | 无法处理的文件（含文件名和原因） |
### 重复分组对象 {#duplicate-group-object}
| 字段 | 类型 | 说明 |
|-------|------|-------------|
| groupId | number | 分组标识符 |
| files | array | 此重复分组中的图像 |
### 文件对象（分组内） {#file-object-within-a-group}
| 字段 | 类型 | 说明 |
|-------|------|-------------|
| filename | string | 原始文件名 |
| similarity | number | 与参考图像（分组中的第一张）的相似度百分比 |
| width | number | 图像宽度（像素） |
| height | number | 图像高度（像素） |
| fileSize | number | 文件大小（字节） |
| format | string | 图像格式 |
| isBest | boolean | 是否为质量最高的版本（像素最多、文件最大） |
| thumbnail | string 或 null | 用于预览的 Base64 JPEG 缩略图（200px 宽） |
## 说明 {#notes}
- 使用 128 位 dHash（64 位行 + 64 位列）进行感知相似度检测。即使经过缩放、重新压缩和轻微编辑，也能识别出重复项。
- 阈值表示两个哈希之间的最大汉明距离。默认值 8 可捕获近似重复项，同时避免误报。使用 0 表示仅识别像素完全相同的图像，使用 15-20 表示非常宽松的匹配。
- 每组中的“最佳”图像是像素最多（宽 x 高）的那张，以文件大小作为决胜依据。
- 至少需要 2 张图像。验证或解码失败的文件会在 `skippedFiles` 中报告，而不会导致整个请求失败。
- 缩略图是编码为 data URI 的 200px 宽 JPEG 预览图。
- 支持所有常见格式（HEIC、RAW、PSD、SVG 会被自动解码）。
apps/docs/zh-CN/tools/image/gif-tools.md
+147
View File
@@ -0,0 +1,147 @@
---
description: "在单个工具中对动画 GIF 进行调整大小、优化、变速、反转、旋转和提取帧。"
i18n_source_hash: 5e525e80db92
i18n_provenance: human
i18n_output_hash: 79a1cadb7164
---
# GIF 工具 {#gif-tools}
对动画 GIF 进行调整大小、优化、变速、反转、提取帧和旋转。在单个工具中提供多种操作模式。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/gif-tools`
## 参数 {#parameters}
### 通用参数 {#common-parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| mode | string | 否 | `"resize"` | 操作模式：`resize`、`optimize`、`speed`、`reverse`、`extract`、`rotate` |
| loop | number | 否 | 0 | 输出 GIF 的循环次数（0 = 无限，1-100 = 有限次循环） |
### 调整大小模式参数 {#resize-mode-parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| width | integer | 否 | - | 目标宽度（像素，1 到 16384） |
| height | integer | 否 | - | 目标高度（像素，1 到 16384） |
| percentage | number | 否 | - | 按百分比缩放（1 到 500）。设置后会覆盖 width/height。 |
### 优化模式参数 {#optimize-mode-parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| colors | number | 否 | 256 | 调色板中的最大颜色数（2 到 256） |
| dither | number | 否 | 1.0 | 抖动强度（0 到 1，0 表示禁用抖动） |
| effort | number | 否 | 7 | 优化投入级别（1 到 10，越高越慢但文件越小） |
### 变速模式参数 {#speed-mode-parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| speedFactor | number | 否 | 1.0 | 速度倍数（0.1 到 10）。值 > 1 加速，< 1 减速。 |
### 提取模式参数 {#extract-mode-parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| extractMode | string | 否 | `"single"` | 提取模式：`single`、`range`、`all` |
| frameNumber | number | 否 | 0 | 在 `single` 模式下要提取的帧索引（从 0 开始） |
| frameStart | number | 否 | 0 | `range` 模式下的起始帧索引（从 0 开始） |
| frameEnd | number | 否 | - | `range` 模式下的结束帧索引（从 0 开始，含此帧） |
| extractFormat | string | 否 | `"png"` | 提取帧的格式：`png`、`webp` |
### 旋转模式参数 {#rotate-mode-parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| angle | number | 否 | - | 旋转角度：`90`、`180` 或 `270` 度 |
| flipH | boolean | 否 | `false` | 水平翻转 |
| flipV | boolean | 否 | `false` | 垂直翻转 |
## 请求示例 {#example-requests}
### 调整大小 {#resize}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/gif-tools \
-F "file=@animation.gif" \
-F 'settings={"mode":"resize","percentage":50}'
```
### 优化 {#optimize}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/gif-tools \
-F "file=@large.gif" \
-F 'settings={"mode":"optimize","colors":128,"effort":9}'
```
### 加速 {#speed-up}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/gif-tools \
-F "file=@animation.gif" \
-F 'settings={"mode":"speed","speedFactor":2.0}'
```
### 提取单帧 {#extract-single-frame}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/gif-tools \
-F "file=@animation.gif" \
-F 'settings={"mode":"extract","extractMode":"single","frameNumber":5,"extractFormat":"png"}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/animation.gif",
"originalSize": 2345678,
"processedSize": 1234567
}
```
## Info 子路由 {#info-sub-route}
`POST /api/v1/tools/image/gif-tools/info`
返回动画 GIF 的元数据而不对其进行处理。
### Info 请求 {#info-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/gif-tools/info \
-F "file=@animation.gif"
```
### Info 响应 {#info-response}
```json
{
"width": 480,
"height": 320,
"pages": 24,
"delay": [100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100],
"loop": 0,
"fileSize": 2345678,
"duration": 2400
}
```
## 说明 {#notes}
- 主处理端点使用标准的 `createToolRoute` 工厂。
- info 端点只需上传文件（无需设置）。
- 在 `resize` 模式下，如果提供了 `percentage`，它会优先于 `width`/`height`。调整大小使用 `fit: inside` 以保持宽高比。
- 在 `speed` 模式下，帧延迟会除以速度因子。每帧的最小延迟为 20ms（GIF 规范限制）。
- 在 `reverse` 模式下，还可使用 `speedFactor` 参数在反转的同时调整速度。
- 在 `extract` 模式且使用 `range` 或 `all` 时，输出是包含各个帧的 ZIP 文件。
- 在 `rotate` 模式下，会单独处理每一帧并重新组装成动画。
- `loop` 参数控制输出 GIF 的循环次数。使用 0 表示无限循环。
- info 响应中的 `duration` 字段是以毫秒为单位的动画总时长。
apps/docs/zh-CN/tools/image/gif-webp.md
+51
View File
@@ -0,0 +1,51 @@
---
description: "在动画 GIF 与 WebP 之间互相转换，保留所有帧。"
i18n_source_hash: 20946e5001cb
i18n_provenance: human
i18n_output_hash: 7c7af582111a
---
# GIF/WebP 转换器 {#gif-webp-converter}
在动画 GIF 文件与 WebP 之间互相转换，保留所有帧和动画时序。WebP 动画通常比等效的 GIF 小 25-35%。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/gif-webp`
接受包含一个 GIF 或 WebP 文件的 multipart 表单数据，以及一个 JSON `settings` 字段。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| quality | integer | 否 | `80` | WebP 编码的输出质量（1-100） |
| lossless | boolean | 否 | `false` | 使用无损 WebP 压缩 |
| resizePercent | integer | 否 | `100` | 按百分比缩放输出（10-100） |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/gif-webp \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@animation.gif" \
-F 'settings={"quality": 85, "resizePercent": 50}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/animation.webp",
"originalSize": 3500000,
"processedSize": 2200000
}
```
## 说明 {#notes}
- 仅接受 `.gif` 和 `.webp` 文件。此工具不支持其他图像格式。
- 转换方向是自动的：GIF 输入生成 WebP 输出，WebP 输入生成 GIF 输出。
- `quality` 和 `lossless` 选项仅在编码为 WebP 时适用。转换为 GIF 时，输出使用标准 GIF 调色板。
- 使用 `resizePercent` 来缩小大型动画的尺寸（以及文件大小）。
apps/docs/zh-CN/tools/image/histogram.md
+65
View File
@@ -0,0 +1,65 @@
---
description: "从图像生成带有各通道统计信息的 RGB 直方图图表。"
i18n_source_hash: 57aa610206a5
i18n_provenance: human
i18n_output_hash: 58229d59986f
---
# 直方图 {#histogram}
从图像生成 RGB 直方图图表。返回一张 PNG 直方图图像，并在响应 JSON 中附带各通道统计信息和原始的 256 桶直方图数据。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/histogram`
接受包含一个图像文件的 multipart 表单数据，以及一个 JSON `settings` 字段。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| scale | string | 否 | `"linear"` | Y 轴刻度：`linear` 或 `log` |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/histogram \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"scale": "linear"}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/histogram.png",
"originalSize": 2450000,
"processedSize": 12000,
"bins": {
"r": [0, 12, 45, "... (256 values)"],
"g": [0, 8, 38, "... (256 values)"],
"b": [2, 15, 52, "... (256 values)"],
"lum": [0, 10, 40, "... (256 values)"]
},
"stats": {
"r": { "mean": 128, "median": 132, "stdev": 48.5 },
"g": { "mean": 119, "median": 121, "stdev": 44.2 },
"b": { "mean": 105, "median": 108, "stdev": 51.3 },
"lum": { "mean": 118, "median": 120, "stdev": 45.1 }
},
"mean": { "r": 128, "g": 119, "b": 105 },
"max": { "r": 4200, "g": 3800, "b": 4100 }
}
```
## 说明 {#notes}
- `downloadUrl` 指向渲染后的 PNG 直方图图表，展示 R、G、B 和亮度分布。
- `bins` 包含每个通道（红、绿、蓝、亮度）的原始 256 值数组，适用于渲染自定义可视化。
- `stats` 提供每个通道的平均值、中位数和标准差。
- `mean` 和 `max` 是向后兼容的简写字段。
- 当直方图由少数几个峰值主导，而你想看清较低桶中的细节时，使用 `log` 刻度。
- HEIC、RAW、PSD 和 SVG 输入会在分析前被自动解码。
apps/docs/zh-CN/tools/image/html-to-image.md
+81
View File
@@ -0,0 +1,81 @@
---
description: "通过设备模拟将网页或 HTML 片段捕获为高质量图像。"
i18n_source_hash: 1e49d070ea2e
i18n_provenance: human
i18n_output_hash: 895080b5e602
---
# HTML 转图像 {#html-to-image}
将网页 URL 或原始 HTML 内容捕获为截图图像。支持设备模拟（桌面、平板、手机）、整页捕获以及多种输出格式。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/html-to-image`
接受 **JSON 请求体**（非 multipart）。无需上传文件。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| url | string | 有条件 | - | 要捕获的 URL（必须是有效的 URL） |
| html | string | 有条件 | - | 要渲染的原始 HTML 内容（1 到 5,000,000 个字符） |
| format | string | 否 | `"png"` | 输出格式：`jpg`、`png`、`webp` |
| quality | number | 否 | `90` | 有损格式的输出质量（1 到 100） |
| fullPage | boolean | 否 | `false` | 捕获整个可滚动页面，而不仅仅是视口 |
| devicePreset | string | 否 | `"desktop"` | 设备模拟：`desktop`、`tablet`、`mobile`、`custom` |
| viewportWidth | number | 否 | `1280` | 自定义视口宽度（像素，320 到 3840，当 devicePreset 为 `custom` 时使用） |
| viewportHeight | number | 否 | `720` | 自定义视口高度（像素，320 到 2160，当 devicePreset 为 `custom` 时使用） |
必须提供 `url` 或 `html` 之一，但不能同时提供两者。
### 设备预设 {#device-presets}
| 预设 | 宽度 | 高度 | 移动 UA |
|--------|-------|--------|-----------|
| `desktop` | 1280 | 720 | 否 |
| `tablet` | 768 | 1024 | 否 |
| `mobile` | 375 | 812 | 是 |
| `custom` | （用户指定） | （用户指定） | 否 |
## 请求示例 {#example-request}
捕获网页：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
-H "Authorization: Bearer si_your-api-key" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com", "format": "png", "fullPage": true, "devicePreset": "desktop"}'
```
渲染 HTML 内容：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
-H "Authorization: Bearer si_your-api-key" \
-H "Content-Type: application/json" \
-d '{"html": "<div style=\"padding: 20px; background: #f0f0f0;\"><h1>Hello</h1></div>", "format": "png"}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/screenshot.png",
"originalSize": 0,
"processedSize": 145000
}
```
## 说明 {#notes}
- 需要在服务器上安装 Chromium。如果浏览器服务不可用，则返回 HTTP 503。
- URL 会针对 SSRF 攻击进行验证（私有/内部网络地址会被阻止）。
- 此端点的速率限制为每小时 120 个请求。
- `originalSize` 始终为 0，因为此工具从 URL/HTML 生成图像。
- 输出文件名为 `screenshot.<format>`。
- 如果页面加载耗时过长，请求会返回 HTTP 504（网关超时）。
- 如果浏览器服务反复崩溃，它会被临时禁用，并返回带有代码 `BROWSER_CRASHED` 的 HTTP 503。
apps/docs/zh-CN/tools/image/image-enhancement.md
+99
View File
@@ -0,0 +1,99 @@
---
description: "一键自动增强，分析图像并校正曝光、对比度、白平衡、饱和度和锐度。"
i18n_source_hash: 42b6ab956f91
i18n_provenance: human
i18n_output_hash: 4011ac2b629b
---
# 图像增强 {#image-enhancement}
通过智能分析实现一键自动改善。分析图像并应用曝光、对比度、白平衡、饱和度、锐度和降噪校正。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/image-enhancement`
**处理方式：** 同步（使用 `createToolRoute` 工厂，直接返回结果）
**模型包：** 基础增强无需模型包。仅当启用 `deepEnhance` 时才使用 `upscale-enhance` 包（5-6 GB）（用于通过 SCUNet 进行 AI 降噪）。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 图像文件（multipart） |
| mode | string | 否 | `"auto"` | 增强模式：`auto`、`portrait`、`landscape`、`low-light`、`food`、`document` |
| intensity | number | 否 | `50` | 整体增强强度（0-100） |
| corrections | object | 否 | 全部 `true` | 要应用的可选校正项（见下文） |
| deepEnhance | boolean | 否 | `false` | 启用 AI 驱动的降噪（需要安装 `noise-removal` 工具） |
### Corrections 对象 {#corrections-object}
| 字段 | 类型 | 默认值 | 说明 |
|-------|------|---------|-------------|
| exposure | boolean | `true` | 自动校正曝光 |
| contrast | boolean | `true` | 自动校正对比度 |
| whiteBalance | boolean | `true` | 自动校正白平衡 |
| saturation | boolean | `true` | 自动校正饱和度 |
| sharpness | boolean | `true` | 自动锐化 |
| denoise | boolean | `true` | 轻度降噪 |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/image-enhancement \
-F "file=@photo.jpg" \
-F 'settings={"mode":"portrait","intensity":70,"corrections":{"exposure":true,"contrast":true,"sharpness":false}}'
```
## 响应（200 OK） {#response-200-ok}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/photo.jpg",
"originalSize": 300000,
"processedSize": 310000
}
```
## Analyze 端点 {#analyze-endpoint}
`POST /api/v1/tools/image/image-enhancement/analyze`
分析图像并返回校正建议，但不实际应用。
### 参数 {#parameters-1}
| 参数 | 类型 | 是否必填 | 说明 |
|-----------|------|----------|-------------|
| file | file | 是 | 图像文件（multipart） |
### 请求示例 {#example-request-1}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/image-enhancement/analyze \
-F "file=@photo.jpg"
```
### 响应（200 OK） {#response-200-ok-1}
```json
{
"corrections": {
"exposure": { "value": 0.3, "direction": "brighten" },
"contrast": { "value": 0.2, "direction": "increase" },
"whiteBalance": { "value": 200, "direction": "warmer" },
"saturation": { "value": 0.1, "direction": "increase" },
"sharpness": { "value": 0.4, "direction": "sharpen" }
}
}
```
## 说明 {#notes}
- 此工具使用同步的 `createToolRoute` 工厂，因此返回标准响应（而非 202 异步）。
- `mode` 参数会调整各项校正的权重（例如，人像模式对肤色更温和，风景模式会提升饱和度）。
- 当启用 `deepEnhance` 且已安装 `noise-removal` 工具（SCUNet）时，会在标准校正之后额外应用一次 AI 降噪处理。
- analyze 端点在正式应用前，可用于预览将会应用哪些校正。
- 通过自动解码支持 HEIC/HEIF、RAW、TGA、PSD、EXR 和 HDR 输入格式。
apps/docs/zh-CN/tools/image/image-pad.md
+54
View File
@@ -0,0 +1,54 @@
---
description: "使用纯色、透明或模糊背景将图像填充到目标宽高比。"
i18n_source_hash: 796122da3dae
i18n_provenance: human
i18n_output_hash: 63814b238de5
---
# 图像填充 {#image-pad}
通过在图像周围添加纯色、透明或模糊背景，将其填充到目标宽高比。适用于在不裁剪的情况下，将图像适配到社交媒体或印刷所需的固定宽高比。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/image-pad`
接受包含一个图像文件的 multipart 表单数据，以及一个 JSON `settings` 字段。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| target | string | 否 | `"1:1"` | 目标宽高比：`16:9`、`9:16`、`1:1`、`4:3`、`3:4` 或 `custom` |
| ratioW | integer | 否 | `1` | 自定义比例宽度（1-100，当 target 为 `custom` 时使用） |
| ratioH | integer | 否 | `1` | 自定义比例高度（1-100，当 target 为 `custom` 时使用） |
| background | string | 否 | `"color"` | 背景模式：`color`、`transparent` 或 `blur` |
| color | string | 否 | `"#ffffff"` | 背景十六进制颜色（当 background 为 `color` 时） |
| padding | integer | 否 | `0` | 额外内边距，占画布的百分比（0-50） |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/image-pad \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"target": "16:9", "background": "blur", "padding": 5}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
"originalSize": 2450000,
"processedSize": 3100000
}
```
## 说明 {#notes}
- `blur` 背景模式会创建原始图像的模糊副本作为填充，产生视觉上协调的效果。
- 使用 `transparent` 背景时，输出会转换为 PNG 以保留 alpha 通道。
- 除非涉及透明度，输出格式与输入格式一致。HEIC、RAW、PSD 和 SVG 输入会在处理前被自动解码。
- 将 `target` 设为 `custom` 并提供 `ratioW` 和 `ratioH` 即可使用任意宽高比（例如 `ratioW: 3, ratioH: 2` 对应 3:2）。
apps/docs/zh-CN/tools/image/image-to-base64.md
+96
View File
@@ -0,0 +1,96 @@
---
description: "将图像转换为 base64 data URI，以便嵌入 HTML、CSS 等。"
i18n_source_hash: ba4b8f3b4ece
i18n_provenance: human
i18n_output_hash: 0af37698b3a1
---
# 图像转 Base64 {#image-to-base64}
将一个或多个图像转换为 base64 编码的字符串和 data URI。支持可选的格式转换、质量控制和调整大小。适用于将图像直接嵌入 HTML、CSS、JSON 或电子邮件模板。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/image-to-base64`
接受包含一个或多个图像文件的 multipart 表单数据，以及一个可选的 JSON `settings` 字段。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| outputFormat | string | 否 | `"original"` | 编码前转换：`original`、`jpeg`、`png`、`webp`、`avif`、`jxl` |
| quality | number | 否 | `80` | 有损格式的输出质量（1 到 100） |
| maxWidth | number | 否 | `0` | 最大宽度（像素，0 = 不调整大小，不会放大） |
| maxHeight | number | 否 | `0` | 最大高度（像素，0 = 不调整大小，不会放大） |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/image-to-base64 \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@icon.png" \
-F 'settings={"outputFormat": "webp", "quality": 80, "maxWidth": 200}'
```
多个文件：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/image-to-base64 \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@icon1.png" \
-F "file=@icon2.png" \
-F "file=@icon3.png" \
-F 'settings={"outputFormat": "original"}'
```
## 响应示例 {#example-response}
```json
{
"results": [
{
"filename": "icon.png",
"mimeType": "image/webp",
"width": 200,
"height": 200,
"originalSize": 45000,
"encodedSize": 28800,
"overheadPercent": -36.0,
"base64": "UklGRlYAAABXRUJQ...",
"dataUri": "data:image/webp;base64,UklGRlYAAABXRUJQ..."
}
],
"errors": []
}
```
## 响应字段 {#response-fields}
| 字段 | 类型 | 说明 |
|-------|------|-------------|
| results | array | 成功转换的图像 |
| errors | array | 处理失败的图像（含文件名和错误信息） |
### Result 对象 {#result-object}
| 字段 | 类型 | 说明 |
|-------|------|-------------|
| filename | string | 原始文件名 |
| mimeType | string | 编码输出的 MIME 类型 |
| width | number | 最终宽度（像素，调整大小后） |
| height | number | 最终高度（像素，调整大小后） |
| originalSize | number | 原始文件大小（字节） |
| encodedSize | number | base64 字符串大小（字节） |
| overheadPercent | number | 相对原始文件的大小差异百分比（正数 = 更大，负数 = 更小） |
| base64 | string | 原始 base64 编码的图像数据 |
| dataUri | string | 可直接用于 `src` 属性的完整 data URI |
## 说明 {#notes}
- 与二进制文件相比，Base64 编码通常会使大小增加约 33%。`overheadPercent` 字段显示了实际差异。
- 当 `outputFormat` 为 `"original"` 时，HEIC/HEIF 文件会被转换为 JPEG（因为浏览器无法在 data URI 中显示 HEIC）。
- `maxWidth` 和 `maxHeight` 选项使用 `fit: inside` 配合 `withoutEnlargement` 进行调整大小，因此小于指定尺寸的图像不会被放大。
- 单个请求中可处理多个文件。每个文件独立处理，失败不会影响其他文件成功。
- SVG 文件会作为 `image/svg+xml` 直接传递而不重新编码（除非请求了格式转换）。
- 这是一个只读端点。它不会生成可下载文件或 `jobId`。base64 数据会直接在响应体中返回。
apps/docs/zh-CN/tools/image/image-to-pdf.md
+119
View File
@@ -0,0 +1,119 @@
---
description: "将一个或多个图像合并为 PDF 文档，可选择页面大小、方向和目标文件大小。"
i18n_source_hash: f659c7e7f56b
i18n_provenance: human
i18n_output_hash: 6cfa1b2ea8b1
---
# 图像转 PDF {#image-to-pdf}
将一个或多个图像合并为 PDF 文档。支持多种页面大小、方向、边距，并可通过质量调整选择性地约束文件大小。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/image-to-pdf`
接受包含一个或多个图像文件的 multipart 表单数据，以及一个 JSON `settings` 字段。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| pageSize | string | 否 | `"A4"` | 页面大小：`A4`、`Letter`、`A3`、`A5` |
| orientation | string | 否 | `"portrait"` | 页面方向：`portrait` 或 `landscape` |
| margin | number | 否 | `20` | 页面边距（磅，0-500） |
| targetSize | object | 否 | - | 目标文件大小约束（见下文） |
| collate | boolean | 否 | `true` | 将所有图像合并到一个 PDF。若为 `false`，则每张图像生成一个 PDF。 |
### Target Size 对象 {#target-size-object}
| 字段 | 类型 | 是否必填 | 说明 |
|-------|------|----------|-------------|
| value | number | 是 | 目标大小值 |
| unit | string | 是 | 单位：`KB` 或 `MB` |
最小目标大小为 50 KB。
## 请求示例 {#example-request}
基础的多图像 PDF：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/image-to-pdf \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@page1.jpg" \
-F "file=@page2.jpg" \
-F "file=@page3.jpg" \
-F 'settings={"pageSize": "A4", "orientation": "portrait", "margin": 20}'
```
带文件大小目标：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/image-to-pdf \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@scan1.jpg" \
-F "file=@scan2.jpg" \
-F 'settings={"pageSize": "Letter", "targetSize": {"value": 2, "unit": "MB"}}'
```
每张图像生成一个 PDF：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/image-to-pdf \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo1.jpg" \
-F "file=@photo2.jpg" \
-F 'settings={"collate": false}'
```
## 响应示例（合并） {#example-response-collated}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/images.pdf",
"originalSize": 5000000,
"processedSize": 1200000,
"pages": 3
}
```
## 响应示例（非合并） {#example-response-non-collated}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/images.zip",
"originalSize": 5000000,
"processedSize": 2400000,
"pages": 2,
"collated": false
}
```
## 响应示例（带目标大小） {#example-response-with-target-size}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/images.pdf",
"originalSize": 10000000,
"processedSize": 2000000,
"pages": 5,
"compression": {
"targetRequested": 2097152,
"targetMet": true,
"jpegQuality": 72
}
}
```
## 说明 {#notes}
- 图像在页面上居中，并在保持宽高比的前提下缩放以适应边距。图像永远不会被放大。
- 当 `collate` 为 `false` 时，每张图像会成为单独的 PDF 文件，下载内容是包含所有 PDF 的 ZIP 归档。
- 目标大小功能通过对 JPEG 质量级别（10-95）进行迭代二分搜索，找出在预算内的最佳质量。
- 透明图像在嵌入 PDF 前会被平整为白色。
- 支持的输入格式：JPEG、PNG、WebP、AVIF、TIFF、GIF、HEIC、RAW、PSD、SVG 等。
- 在嵌入前会自动应用 EXIF 方向信息。
apps/docs/zh-CN/tools/image/info.md
+92
View File
@@ -0,0 +1,92 @@
---
description: "查看详细的图像元数据、属性和各通道直方图统计信息。"
i18n_source_hash: 8a0f7a0b0153
i18n_provenance: human
i18n_output_hash: 7948831b5f0b
---
# 图像信息 {#image-info}
只读分析工具，返回全面的图像元数据，包括尺寸、格式、色彩空间、EXIF/ICC/XMP 是否存在，以及各通道直方图统计信息。不会生成处理后的输出文件。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/info`
接受包含一个图像文件的 multipart 表单数据。无需 settings 字段。
## 参数 {#parameters}
此工具没有可配置参数。只需上传图像文件即可。
| 字段 | 类型 | 是否必填 | 说明 |
|-------|------|----------|-------------|
| file | file | 是 | 要分析的图像 |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/info \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg"
```
## 响应示例 {#example-response}
```json
{
"filename": "photo.jpg",
"fileSize": 2450000,
"width": 4032,
"height": 3024,
"format": "jpeg",
"channels": 3,
"hasAlpha": false,
"colorSpace": "srgb",
"density": 72,
"isProgressive": false,
"orientation": 1,
"hasProfile": true,
"hasExif": true,
"hasIcc": true,
"hasXmp": false,
"bitDepth": "8",
"pages": 1,
"histogram": [
{ "channel": "red", "min": 0, "max": 255, "mean": 128.45, "stdev": 52.31 },
{ "channel": "green", "min": 2, "max": 253, "mean": 115.22, "stdev": 48.76 },
{ "channel": "blue", "min": 0, "max": 250, "mean": 102.89, "stdev": 55.14 }
]
}
```
## 响应字段 {#response-fields}
| 字段 | 类型 | 说明 |
|-------|------|-------------|
| filename | string | 经过清理的文件名 |
| fileSize | number | 文件大小（字节） |
| width | number | 图像宽度（像素） |
| height | number | 图像高度（像素） |
| format | string | 检测到的格式（jpeg、png、webp 等） |
| channels | number | 色彩通道数 |
| hasAlpha | boolean | 图像是否有 alpha 通道 |
| colorSpace | string | 色彩空间（srgb、cmyk 等） |
| density | number 或 null | DPI/PPI 分辨率 |
| isProgressive | boolean | JPEG 是否使用渐进式编码 |
| orientation | number 或 null | EXIF 方向值（1-8） |
| hasProfile | boolean | 是否嵌入了 ICC 配置文件 |
| hasExif | boolean | 是否存在 EXIF 元数据 |
| hasIcc | boolean | 是否存在 ICC 色彩配置文件 |
| hasXmp | boolean | 是否存在 XMP 元数据 |
| bitDepth | string 或 null | 每样本位数 |
| pages | number | 页数（用于 TIFF、GIF 等多页格式） |
| histogram | array | 各通道统计信息（最小值、最大值、平均值、标准差） |
## 说明 {#notes}
- 这是一个只读端点。它不会生成可下载的输出文件或 `jobId`。
- 对于 RAW 格式图像（DNG、CR2、NEF、ARW 等），会使用 ExifTool 提取 Sharp 无法直接读取的真实传感器尺寸和元数据标志。
- HEIC/HEIF 文件会在内部解码为 PNG 以提取像素统计信息，因为 Sharp 无法解码 HEVC 像素。
- 直方图提供每个通道的最小值/最大值/平均值/标准差，而非完整的 256 桶分布。
- `density` 字段反映嵌入的 DPI 元数据（如果存在）。
apps/docs/zh-CN/tools/image/lqip-placeholder.md
+62
View File
@@ -0,0 +1,62 @@
---
description: "生成带 base64 data URI 的微型低质量图像占位符。"
i18n_source_hash: f8a27c8021f5
i18n_provenance: human
i18n_output_hash: 5f5934959b5e
---
# LQIP 占位符 {#lqip-placeholder}
从源图像生成微型低质量图像占位符（LQIP）。返回一个小的占位符文件，并附带 base64 data URI、即用型 HTML `<img>` 标签和 CSS `background-image` 代码片段，可立即嵌入使用。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/lqip-placeholder`
接受包含一个图像文件的 multipart 表单数据，以及一个 JSON `settings` 字段。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| width | integer | 否 | `16` | 目标宽度（像素，4-64） |
| blur | number | 否 | `2` | 模糊策略的模糊半径（0-20） |
| strategy | string | 否 | `"blur"` | 占位符策略：`blur`、`pixelate` 或 `solid` |
| format | string | 否 | `"webp"` | 输出格式：`webp`、`png` 或 `jpeg` |
| quality | integer | 否 | `50` | 输出质量（1-100） |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/lqip-placeholder \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"width": 20, "strategy": "blur", "format": "webp"}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.webp",
"originalSize": 2450000,
"processedSize": 280,
"dataUri": "data:image/webp;base64,UklGR...",
"width": 20,
"height": 13,
"bytes": 280,
"strategy": "blur",
"html": "<img src=\"data:image/webp;base64,UklGR...\" />",
"css": "background-image:url('data:image/webp;base64,UklGR...');background-size:cover;background-position:center;"
}
```
## 说明 {#notes}
- `dataUri` 字段包含完整的 data URI，可直接用于 `src` 属性或 CSS，无需任何额外请求。
- `html` 和 `css` 字段提供适用于常见场景的可复制粘贴代码片段。
- `blur` 策略生成柔和的模糊缩略图。`pixelate` 策略生成块状马赛克。`solid` 策略返回单一的平均色。
- 典型的占位符大小为 200-500 字节，适合直接内联到 HTML 中。
- 高度会自动计算，以保持源图像的宽高比。
- HEIC、RAW、PSD 和 SVG 输入会在处理前被自动解码。
apps/docs/zh-CN/tools/image/meme-generator.md
+92
View File
@@ -0,0 +1,92 @@
---
description: "使用模板或自定义图片、带样式的文本框以及字体选项创建表情包。"
i18n_source_hash: 0a4970112ca6
i18n_provenance: human
i18n_output_hash: 8f47b4401894
---
# 表情包生成器 {#meme-generator}
使用内置模板或自定义图片创建表情包。添加带有经典表情包样式（粗体、描边文字）的文本、多种布局预设以及字体选择。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/meme-generator`
接受以下任一形式：
- **Multipart 表单数据**，包含一个图片文件和一个 JSON `settings` 字段（自定义图片模式）
- **JSON 请求体**，包含一个 `templateId`（模板模式，无需上传文件）
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| templateId | string | 否 | - | 内置表情包模板 ID。若提供此项，则无需上传图片 |
| textLayout | string | 否 | `"top-bottom"` | 文本框布局：`top-bottom`、`top-only`、`bottom-only`、`center`、`side-by-side` |
| textBoxes | array | 否 | `[]` | 文本框对象数组，包含 `id` 和 `text` 字段 |
| fontFamily | string | 否 | `"anton"` | 字体：`anton`、`arial-black`、`comic-sans`、`montserrat`、`bebas-neue`、`permanent-marker`、`roboto` |
| fontSize | number | 否 | auto | 字号（像素，8 到 200）。若省略则自动计算 |
| textColor | string | 否 | `"#ffffff"` | 文字填充颜色 |
| strokeColor | string | 否 | `"#000000"` | 文字描边/轮廓颜色 |
| textAlign | string | 否 | `"center"` | 文字对齐方式：`left`、`center`、`right` |
| allCaps | boolean | 否 | `true` | 将文字转换为大写 |
### 文本框 {#text-boxes}
`textBoxes` 数组中的每个条目应包含：
| 字段 | 类型 | 说明 |
|-------|------|-------------|
| id | string | 与布局匹配的文本框标识符（例如 `"top"`、`"bottom"`、`"left"`、`"right"`、`"center"`） |
| text | string | 要显示的表情包文字 |
### 文本布局的文本框 ID {#text-layout-box-ids}
| 布局 | 可用的文本框 ID |
|--------|-------------------|
| `top-bottom` | `top`、`bottom` |
| `top-only` | `top` |
| `bottom-only` | `bottom` |
| `center` | `center` |
| `side-by-side` | `left`、`right` |
## 请求示例 {#example-request}
带有顶部和底部文字的自定义图片：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/meme-generator \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"textLayout": "top-bottom", "textBoxes": [{"id": "top", "text": "When the code works"}, {"id": "bottom", "text": "On the first try"}], "fontFamily": "anton", "allCaps": true}'
```
使用内置模板（JSON 请求体，无需上传文件）：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/meme-generator \
-H "Authorization: Bearer si_your-api-key" \
-H "Content-Type: application/json" \
-d '{"templateId": "drake", "textBoxes": [{"id": "top", "text": "Manual testing"}, {"id": "bottom", "text": "Automated tests"}]}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/meme-drake.png",
"originalSize": 450000,
"processedSize": 520000
}
```
## 说明 {#notes}
- 必须提供 `templateId` 或上传一个图片文件。若两者都提供，则使用模板。
- 模板会定义自己的文本框位置；使用模板时会忽略 `textLayout` 参数。
- 文字以带描边轮廓的 SVG 形式渲染，以实现经典的表情包外观。
- 若未显式设置字号，则会自动计算以适应文本框。
- 空文本框会被跳过（如果所有文本框都为空，则不进行任何渲染）。
- 使用模板时，输出文件名会包含模板 ID（例如 `meme-drake.png`）。
- HEIC、RAW、PSD 和 SVG 输入会在处理前自动解码。
apps/docs/zh-CN/tools/image/noise-removal.md
+79
View File
@@ -0,0 +1,79 @@
---
description: "基于 AI 的降噪和去颗粒处理，提供多档质量选项。"
i18n_source_hash: f0dfc876e0e0
i18n_provenance: human
i18n_output_hash: 43d042c4f560
---
# 降噪 {#noise-removal}
基于 AI 的降噪和去颗粒处理，提供多档质量选项，使用 Python 边车（SCUNet 模型）。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/noise-removal`
**处理方式：** 异步（返回 202，通过 SSE 轮询 `/api/v1/jobs/{jobId}/progress` 获取状态）
**模型包：** `upscale-enhance`（5-6 GB）
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 图片文件（multipart） |
| tier | string | 否 | `"balanced"` | 质量档位：`quick`、`balanced`、`quality`、`maximum` |
| strength | number | 否 | `50` | 降噪强度（0-100） |
| detailPreservation | number | 否 | `50` | 保留细节的程度（0-100）。值越高保留的纹理越多 |
| colorNoise | number | 否 | `30` | 彩色噪点抑制强度（0-100） |
| format | string | 否 | `"original"` | 输出格式：`original`、`png`、`jpeg`、`webp`、`avif`、`jxl` |
| quality | number | 否 | `90` | 输出编码质量（1-100） |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/noise-removal \
-F "file=@noisy-photo.jpg" \
-F 'settings={"tier":"quality","strength":60,"detailPreservation":70,"colorNoise":40}'
```
## 响应 {#response}
### 初始响应（202 Accepted） {#initial-response-202-accepted}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"async": true
}
```
### 进度（位于 `/api/v1/jobs/{jobId}/progress` 的 SSE） {#progress-sse-at-api-v1-jobs-jobid-progress}
```
event: progress
data: {"phase":"processing","stage":"Denoising...","percent":65}
```
### 最终结果（通过 SSE） {#final-result-via-sse}
```json
{
"phase": "complete",
"percent": 100,
"result": {
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/noisy-photo_denoised.jpg",
"originalSize": 500000,
"processedSize": 380000
}
}
```
## 说明 {#notes}
- 需要安装 `upscale-enhance` 模型包（5-6 GB）。
- 质量档位在速度和质量之间权衡：`quick` 最快，仅做基础降噪；`maximum` 采用最彻底的多轮处理方式。
- 对于有纹理的主体（布料、头发、树叶），`detailPreservation` 参数至关重要。较高的值可防止降噪器抹平细微的细节。
- 当 `format` 设为 `"original"` 时，输出格式与输入文件格式一致。
- 通过自动解码支持 HEIC/HEIF、RAW、TGA、PSD、EXR 和 HDR 输入格式。
apps/docs/zh-CN/tools/image/ocr.md
+65
View File
@@ -0,0 +1,65 @@
---
description: "使用基于 AI 的光学字符识别从图片中提取文本。"
i18n_source_hash: 3d85d423b82c
i18n_provenance: human
i18n_output_hash: ae14f7fe10d3
---
# OCR / 文本提取 {#ocr-text-extraction}
使用基于 AI 的光学字符识别从图片中提取文本。支持多种语言和质量档位。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/ocr`
**处理方式：** 同步 JSON 响应。若提供了 `clientJobId`，则进度也会通过 SSE 上报。
**模型包：** `ocr`（5-6 GB）
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 图片文件（multipart） |
| quality | string | 否 | `"balanced"` | 质量档位：`fast`（Tesseract）、`balanced`（PaddleOCR v5）、`best`（PaddleOCR VL） |
| language | string | 否 | `"auto"` | 语言提示：`auto`、`en`、`de`、`fr`、`es`、`zh`、`ja`、`ko` |
| enhance | boolean | 否 | `true` | 对图片进行预处理以提高 OCR 准确度 |
| engine | string | 否 | - | 已弃用。请改用 `quality`。将 `tesseract` 映射为 `fast`，将 `paddleocr` 映射为 `balanced` |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/ocr \
-F "file=@document.png" \
-F 'settings={"quality":"best","language":"en","enhance":true}'
```
## 响应（200 OK） {#response-200-ok}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"filename": "document.png",
"text": "Extracted text content from the image...",
"engine": "paddleocr-vl"
}
```
### 进度（SSE，可选） {#progress-sse-optional}
若提供了 `clientJobId` 表单字段，则会流式传输进度事件：
```
event: progress
data: {"phase":"processing","stage":"Recognizing text...","percent":50}
```
## 说明 {#notes}
- 需要安装 `ocr` 模型包（5-6 GB）。
- OCR 直接返回提取的文本，而不是图片下载 URL。
- 采用回退链：若某个较高质量的档位崩溃（例如 PaddleOCR 段错误），会自动使用下一个较低档位重试。
- 若某个档位未崩溃但返回了空文本，也会回退到下一个档位。
- 质量档位对应引擎：`fast` = Tesseract，`balanced` = PaddleOCR v5，`best` = PaddleOCR VL。
- 通过自动解码支持 HEIC/HEIF、RAW、TGA、PSD、EXR 和 HDR 输入格式。
apps/docs/zh-CN/tools/image/optimize-for-web.md
+74
View File
@@ -0,0 +1,74 @@
---
description: "通过格式转换、质量控制、调整尺寸和剥离元数据来为网页交付优化图片。"
i18n_source_hash: c327bbbce768
i18n_provenance: human
i18n_output_hash: ae856b5bebbe
---
# 网页优化 {#optimize-for-web}
一步到位地为网页交付优化图片。整合了格式转换、质量调整、可选的尺寸调整、渐进式编码以及元数据剥离。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/optimize-for-web`
接受包含一个图片文件和一个 JSON `settings` 字段的 multipart 表单数据。
另外还提供实时预览端点 `POST /api/v1/tools/image/optimize-for-web/preview`，它直接以二进制形式返回处理后的图片（不创建工作区），用于实时调整参数。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| format | string | 否 | `"webp"` | 输出格式：`webp`、`jpeg`、`avif`、`png`、`jxl` |
| quality | number | 否 | `80` | 输出质量（1-100） |
| maxWidth | number | 否 | - | 最大宽度（像素）。图片若更宽则会被缩小。 |
| maxHeight | number | 否 | - | 最大高度（像素）。图片若更高则会被缩小。 |
| progressive | boolean | 否 | `true` | 启用渐进式/隔行扫描编码 |
| stripMetadata | boolean | 否 | `true` | 移除 EXIF、GPS、ICC 和 XMP 元数据 |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/optimize-for-web \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"format": "webp", "quality": 75, "maxWidth": 1920}'
```
以激进压缩优化为 AVIF：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/optimize-for-web \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"format": "avif", "quality": 50, "maxWidth": 1200, "maxHeight": 800}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.webp",
"originalSize": 4500000,
"processedSize": 320000
}
```
### 预览端点响应 {#preview-endpoint-response}
预览端点（`/api/v1/tools/image/optimize-for-web/preview`）直接返回二进制图片，并附带信息性响应头：
- `X-Original-Size` - 原始文件大小（字节）
- `X-Processed-Size` - 处理后文件大小（字节）
- `X-Output-Filename` - 经过 URL 编码的输出文件名
## 说明 {#notes}
- 该工具被设计为面向网页资源的一站式优化流水线。它在一次处理中完成格式转换、质量调整、最大尺寸限制和元数据移除。
- 输出文件名的扩展名会更新以匹配所选格式。
- JXL（JPEG XL）编码使用专用的 CLI 编码器。图片会先处理为 PNG，再编码为 JXL。
- 渐进式编码通过让浏览器在完整图片加载之前先渲染低质量预览，改善 JPEG 和 PNG 的感知加载时间。
- 预览端点更为轻量（不创建工作区/任务），旨在供前端的实时参数调整界面使用。
apps/docs/zh-CN/tools/image/passport-photo.md
+173
View File
@@ -0,0 +1,173 @@
---
description: "基于 AI 的护照和证件照生成器，具备人脸检测、背景去除和打印排版拼贴功能。"
i18n_source_hash: d4b4f4ced988
i18n_provenance: human
i18n_output_hash: 8f1a76094628
---
# 护照照片 {#passport-photo}
基于 AI 的护照和证件照生成器。采用两阶段工作流：先分析（人脸检测 + 背景去除），再生成（裁剪、调整尺寸并拼贴以供打印）。
## API 端点 {#api-endpoints}
该工具采用两阶段流程，分析和生成使用各自独立的端点。
**模型包：** `background-removal` 和 `face-detection`
---
### 阶段 1：分析 {#phase-1-analyze}
`POST /api/v1/tools/image/passport-photo/analyze`
检测人脸特征点并去除背景。返回特征点数据和一张预览图，供前端显示裁剪预览。
#### 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 图片文件（multipart） |
| clientJobId | string | 否 | - | 可选的任务 ID，用于通过 SSE 跟踪进度 |
#### 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/passport-photo/analyze \
-F "file=@headshot.jpg"
```
#### 响应（200 OK） {#response-200-ok}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"filename": "headshot.jpg",
"preview": "<base64-encoded PNG>",
"previewWidth": 800,
"previewHeight": 1067,
"landmarks": {
"leftEye": { "x": 0.42, "y": 0.35 },
"rightEye": { "x": 0.58, "y": 0.35 },
"eyeCenter": { "x": 0.50, "y": 0.35 },
"chin": { "x": 0.50, "y": 0.65 },
"forehead": { "x": 0.50, "y": 0.22 },
"crown": { "x": 0.50, "y": 0.18 },
"nose": { "x": 0.50, "y": 0.48 },
"faceCenterX": 0.50
},
"imageWidth": 2400,
"imageHeight": 3200
}
```
#### 进度（SSE，可选） {#progress-sse-optional}
若提供了 `clientJobId`，则会流式传输进度（人脸检测为 0-30%，背景去除为 30-95%）。
#### 错误：未检测到人脸（422） {#error-no-face-detected-422}
```json
{
"error": "No face detected",
"details": "Could not detect a face in the uploaded image. Please upload a clear, front-facing photo with good lighting."
}
```
---
### 阶段 2：生成 {#phase-2-generate}
`POST /api/v1/tools/image/passport-photo/generate`
裁剪、调整尺寸，并可选地将照片拼贴到打印排版上。使用阶段 1 的缓存图片（不重新运行 AI）。
#### 参数（JSON 请求体） {#parameters-json-body}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| jobId | string | 是 | - | 阶段 1 返回的任务 ID |
| filename | string | 是 | - | 阶段 1 的原始文件名 |
| countryCode | string | 是 | - | 护照规格的国家代码（例如 `US`、`GB`、`IN`） |
| documentType | string | 否 | `"passport"` | 证件类型（来自国家规格） |
| bgColor | string | 否 | `"#FFFFFF"` | 背景颜色十六进制值 |
| printLayout | string | 否 | `"none"` | 打印纸张排版：`none`、`4x6`、`a4` |
| maxFileSizeKb | number | 否 | `0` | 最大文件大小限制（KB，0 = 无限制） |
| dpi | number | 否 | `300` | 输出 DPI（72-1200） |
| customWidthMm | number | 否 | - | 自定义照片宽度（毫米，覆盖国家规格） |
| customHeightMm | number | 否 | - | 自定义照片高度（毫米，覆盖国家规格） |
| zoom | number | 否 | `1` | 缩放系数（0.5-3）。值 > 1 时裁剪得更紧 |
| adjustX | number | 否 | `0` | 水平位置调整 |
| adjustY | number | 否 | `0` | 垂直位置调整 |
| landmarks | object | 是 | - | 来自阶段 1 响应的特征点对象 |
| imageWidth | number | 是 | - | 来自阶段 1 响应的图片宽度 |
| imageHeight | number | 是 | - | 来自阶段 1 响应的图片高度 |
#### 请求示例 {#example-request-1}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/passport-photo/generate \
-H "Content-Type: application/json" \
-d '{
"jobId": "a1b2c3d4-...",
"filename": "headshot.jpg",
"countryCode": "US",
"documentType": "passport",
"bgColor": "#FFFFFF",
"printLayout": "4x6",
"dpi": 300,
"zoom": 1,
"adjustX": 0,
"adjustY": 0,
"landmarks": { "leftEye": {"x":0.42,"y":0.35}, "rightEye": {"x":0.58,"y":0.35}, "eyeCenter": {"x":0.50,"y":0.35}, "chin": {"x":0.50,"y":0.65}, "forehead": {"x":0.50,"y":0.22}, "crown": {"x":0.50,"y":0.18}, "nose": {"x":0.50,"y":0.48}, "faceCenterX": 0.50 },
"imageWidth": 2400,
"imageHeight": 3200
}'
```
#### 响应（200 OK） {#response-200-ok-1}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/headshot_passport.jpg",
"dimensions": {
"widthMm": 51,
"heightMm": 51,
"widthPx": 602,
"heightPx": 602,
"dpi": 300
},
"spec": {
"country": "United States",
"countryCode": "US",
"documentType": "passport",
"documentLabel": "Passport"
},
"printDownloadUrl": "/api/v1/download/{jobId}/headshot_passport_print_4x6.jpg"
}
```
---
### 基础路由 {#base-route}
`POST /api/v1/tools/image/passport-photo`
返回引导信息，提示使用正确的子端点。
```json
{
"error": "Use /api/v1/tools/image/passport-photo/analyze or /generate"
}
```
## 说明 {#notes}
- 需要安装 `background-removal` 和 `face-detection` 模型包。
- 阶段 1 运行 AI（人脸特征点 + 背景去除）并缓存结果。阶段 2 是纯 Sharp 图片处理（快速，无需 AI）。
- 特征点以归一化坐标形式返回（相对于图片尺寸的 0-1 范围）。
- 分析响应中的 `preview` 字段是一张 base64 编码的 PNG（最大宽度 800px），用于快速显示。
- 国家规格包含证件尺寸、头部高度比例以及基于官方护照照片要求的视线定位。
- `printLayout` 选项会在 4x6 英寸或 A4 纸上生成拼贴排版，照片之间留有 2mm 的间隙。
- 设置 `maxFileSizeKb` 时，输出会经过迭代压缩以符合大小限制。
apps/docs/zh-CN/tools/image/pixelate.md
+69
View File
@@ -0,0 +1,69 @@
---
description: "对整张图片或特定区域应用像素化效果。"
i18n_source_hash: a3ad29841f7b
i18n_provenance: human
i18n_output_hash: e7dd5030b7ec
---
# 像素化 {#pixelate}
对整张图片或特定矩形区域应用像素化效果。可用于遮挡敏感内容，例如人脸、车牌或个人信息。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/pixelate`
接受包含一个图片文件和一个 JSON `settings` 字段的 multipart 表单数据。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| blockSize | integer | 否 | `12` | 像素块大小（2-128）；值越大，像素化越粗糙 |
| region | object | 否 | - | 将像素化限制在一个矩形区域内（见下文） |
### 区域对象 {#region-object}
| 字段 | 类型 | 是否必填 | 说明 |
|-------|------|----------|-------------|
| left | integer | 是 | 左偏移量（像素，>= 0） |
| top | integer | 是 | 上偏移量（像素，>= 0） |
| width | integer | 是 | 区域宽度（像素，>= 1） |
| height | integer | 是 | 区域高度（像素，>= 1） |
## 请求示例 {#example-request}
像素化整张图片：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/pixelate \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"blockSize": 20}'
```
像素化特定区域：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/pixelate \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"blockSize": 16, "region": {"left": 100, "top": 50, "width": 200, "height": 150}}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
"originalSize": 2450000,
"processedSize": 2380000
}
```
## 说明 {#notes}
- 当省略 `region` 时，整张图片都会被像素化。
- 区域坐标以相对于图片左上角的像素为单位。区域必须落在图片边界之内。
- 输出格式与输入格式一致。HEIC、RAW、PSD 和 SVG 输入会在处理前自动解码。
apps/docs/zh-CN/tools/image/qr-generate.md
+76
View File
@@ -0,0 +1,76 @@
---
description: "生成带有自定义颜色和纠错级别的二维码。"
i18n_source_hash: 096ef4d90da5
i18n_provenance: human
i18n_output_hash: 84f7e9af1df8
---
# 二维码生成器 {#qr-code-generator}
从文本或 URL 生成二维码图片，可配置尺寸、纠错级别以及自定义的前景/背景颜色。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/qr-generate`
接受 **JSON 请求体**（而非 multipart）。无需上传文件。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| text | string | 是 | - | 要编码进二维码的内容（1 到 2000 个字符） |
| size | number | 否 | `400` | 输出图片的宽度/高度（像素，100 到 10000） |
| errorCorrection | string | 否 | `"M"` | 纠错级别：`L`（7%）、`M`（15%）、`Q`（25%）、`H`（30%） |
| foreground | string | 否 | `"#000000"` | 二维码前景/模块颜色的十六进制值（`#RRGGBB`） |
| background | string | 否 | `"#FFFFFF"` | 二维码背景颜色的十六进制值（`#RRGGBB`） |
| logoDataUri | string | 否 | - | 作为 data URI 的 logo 图片（`data:image/png;base64,...` 或 `data:image/jpeg;base64,...`，最大 700 KB）。以二维码尺寸的 22% 居中放置。会强制将纠错级别设为 `H` |
### 纠错级别 {#error-correction-levels}
| 级别 | 恢复能力 | 使用场景 |
|-------|----------|----------|
| `L` | ~7% | 最大数据密度 |
| `M` | ~15% | 均衡（默认） |
| `Q` | ~25% | 适合印刷的二维码 |
| `H` | ~30% | 最适合叠加 logo 的二维码 |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/qr-generate \
-H "Authorization: Bearer si_your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "https://snapotter.com", "size": 500, "errorCorrection": "H"}'
```
带自定义颜色的品牌二维码：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/qr-generate \
-H "Authorization: Bearer si_your-api-key" \
-H "Content-Type: application/json" \
-d '{"text": "Hello World", "size": 300, "foreground": "#1a365d", "background": "#f7fafc"}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/qrcode.png",
"originalSize": 0,
"processedSize": 4520
}
```
## 说明 {#notes}
- 由于无需上传图片，该端点接受 JSON，而非 multipart 表单数据。
- 输出始终为 PNG 图片。
- 输出文件名始终为 `qrcode.png`。
- `originalSize` 始终为 0，因为该工具从零开始生成图片。
- 二维码周围会包含一个 2 模块宽的静默区（边距）。
- 文本最大长度为 2000 个字符。实际容量取决于纠错级别和字符编码。
- 较高的纠错级别可让二维码即使部分被遮挡也能扫描，但会降低数据容量。
- 提供 `logoDataUri` 时，纠错级别会自动强制设为 `H`（30%），以便即使 logo 遮挡了中心区域，二维码仍可扫描。
apps/docs/zh-CN/tools/image/red-eye-removal.md
+79
View File
@@ -0,0 +1,79 @@
---
description: "基于 AI 检测并修正相机闪光灯造成的红眼。"
i18n_source_hash: 647c6ff1ef7c
i18n_provenance: human
i18n_output_hash: 4c47e6dbe7e2
---
# 红眼消除 {#red-eye-removal}
基于 AI 检测并修正相机闪光灯造成的红眼。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/red-eye-removal`
**处理方式：** 异步（返回 202，通过 SSE 轮询 `/api/v1/jobs/{jobId}/progress` 获取状态）
**模型包：** `face-detection`（200-300 MB）
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 图片文件（multipart） |
| sensitivity | number | 否 | `50` | 红眼检测灵敏度（0-100）。值越高，越能检测出更细微的红眼 |
| strength | number | 否 | `70` | 修正强度（0-100）。中和红色的力度 |
| format | string | 否 | - | 输出格式（可选覆盖） |
| quality | number | 否 | `90` | 输出质量（1-100） |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/red-eye-removal \
-F "file=@flash-photo.jpg" \
-F 'settings={"sensitivity":60,"strength":80}'
```
## 响应 {#response}
### 初始响应（202 Accepted） {#initial-response-202-accepted}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"async": true
}
```
### 进度（位于 `/api/v1/jobs/{jobId}/progress` 的 SSE） {#progress-sse-at-api-v1-jobs-jobid-progress}
```
event: progress
data: {"phase":"processing","stage":"Detecting red eyes...","percent":40}
```
### 最终结果（通过 SSE） {#final-result-via-sse}
```json
{
"phase": "complete",
"percent": 100,
"result": {
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/flash-photo_redeye_fixed.png",
"originalSize": 280000,
"processedSize": 290000,
"facesDetected": 2,
"eyesCorrected": 4
}
}
```
## 说明 {#notes}
- 需要安装 `face-detection` 模型包（200-300 MB）。
- 先检测人脸，再定位每张脸内的眼睛区域，最后识别并修正红眼像素。
- `facesDetected` 数量表示找到了多少张人脸；`eyesCorrected` 是被修正了红眼的单只眼睛的总数。
- 输出始终为 PNG，以最大程度地保留质量。
- 通过自动解码支持 HEIC/HEIF、RAW、TGA、PSD、EXR 和 HDR 输入格式。
apps/docs/zh-CN/tools/image/remove-background.md
+136
View File
@@ -0,0 +1,136 @@
---
description: "基于 AI 的背景去除，可选特效（模糊、阴影、渐变、自定义背景）。"
i18n_source_hash: 326a91284529
i18n_provenance: human
i18n_output_hash: fdb2d2307e44
---
# 背景去除 {#remove-background}
基于 AI 的背景去除，可选特效（模糊、阴影、渐变、自定义背景）。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/remove-background`
**处理方式：** 异步（返回 202，通过 SSE 轮询 `/api/v1/jobs/{jobId}/progress` 获取状态）
**模型包：** `background-removal`（4-5 GB）
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 图片文件（multipart） |
| model | string | 否 | - | 要使用的 AI 模型变体 |
| backgroundType | string | 否 | `"transparent"` | 以下之一：`transparent`、`color`、`gradient`、`blur`、`image` |
| backgroundColor | string | 否 | - | 纯色背景的十六进制颜色 |
| gradientColor1 | string | 否 | - | 第一个渐变颜色 |
| gradientColor2 | string | 否 | - | 第二个渐变颜色 |
| gradientAngle | number | 否 | - | 渐变角度（度） |
| blurEnabled | boolean | 否 | - | 启用背景模糊效果 |
| blurIntensity | number | 否 | - | 模糊强度（0-100） |
| shadowEnabled | boolean | 否 | - | 在主体上启用投影 |
| shadowOpacity | number | 否 | - | 阴影不透明度（0-100） |
| outputFormat | string | 否 | - | 输出格式：`png`、`webp` 或 `avif` |
| edgeRefine | integer | 否 | - | 边缘细化级别（0-3） |
| decontaminate | boolean | 否 | - | 移除边缘的颜色溢出 |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/remove-background \
-F "file=@photo.jpg" \
-F 'settings={"backgroundType":"transparent","edgeRefine":2,"outputFormat":"png"}'
```
## 响应 {#response}
### 初始响应（202 Accepted） {#initial-response-202-accepted}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"async": true
}
```
### 进度（位于 `/api/v1/jobs/{jobId}/progress` 的 SSE） {#progress-sse-at-api-v1-jobs-jobid-progress}
```
event: progress
data: {"phase":"processing","stage":"Removing background...","percent":50}
```
### 最终结果（通过 SSE） {#final-result-via-sse}
```json
{
"phase": "complete",
"percent": 100,
"result": {
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/photo_mask.png",
"maskUrl": "/api/v1/download/{jobId}/photo_mask.png",
"originalUrl": "/api/v1/download/{jobId}/photo_original.png",
"originalSize": 245000,
"processedSize": 180000,
"filename": "photo.jpg",
"model": "rembg"
}
}
```
## 特效端点（阶段 2） {#effects-endpoint-phase-2}
`POST /api/v1/tools/image/remove-background/effects`
在不重新运行 AI 模型的情况下重新应用背景特效。使用阶段 1 的缓存蒙版和原图。
### 参数 {#parameters-1}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| settings | JSON | 是 | - | 包含特效设置的 JSON（见下文） |
| backgroundImage | file | 否 | - | 自定义背景图片（当 backgroundType 为 `image` 时） |
#### 设置 JSON 字段 {#settings-json-fields}
| 字段 | 类型 | 是否必填 | 说明 |
|-------|------|----------|-------------|
| jobId | string | 是 | 阶段 1 返回的任务 ID |
| filename | string | 是 | 阶段 1 的原始文件名 |
| backgroundType | string | 否 | `transparent`、`color`、`gradient`、`blur`、`image` |
| backgroundColor | string | 否 | 纯色背景的十六进制颜色 |
| gradientColor1 | string | 否 | 第一个渐变颜色 |
| gradientColor2 | string | 否 | 第二个渐变颜色 |
| gradientAngle | number | 否 | 渐变角度（度） |
| blurEnabled | boolean | 否 | 启用背景模糊 |
| blurIntensity | number | 否 | 模糊强度（0-100） |
| shadowEnabled | boolean | 否 | 启用投影 |
| shadowOpacity | number | 否 | 阴影不透明度（0-100） |
| outputFormat | string | 否 | `png`、`webp` 或 `avif` |
### 请求示例 {#example-request-1}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/remove-background/effects \
-F 'settings={"jobId":"a1b2c3d4-...","filename":"photo.jpg","backgroundType":"color","backgroundColor":"#FF5500","outputFormat":"png"}'
```
### 响应（200 OK） {#response-200-ok}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/photo_nobg.png",
"processedSize": 195000
}
```
## 说明 {#notes}
- 需要安装 `background-removal` 模型包（4-5 GB）。
- 阶段 1 会缓存透明蒙版和原图，以便阶段 2（特效）能够即时重新应用不同的背景，无需重新运行 AI 模型。
- 通过自动解码支持 HEIC/HEIF、RAW、TGA、PSD、EXR 和 HDR 输入格式。
- 处理前会自动校正 EXIF 旋转。
apps/docs/zh-CN/tools/image/replace-color.md
+62
View File
@@ -0,0 +1,62 @@
---
description: "将图片中的某个特定颜色替换为另一种颜色，或将其变为透明。"
i18n_source_hash: df55ac451ecb
i18n_provenance: human
i18n_output_hash: e0faf0cb736f
---
# 替换与反转颜色 {#replace-invert-color}
将匹配某个源颜色的像素替换为目标颜色，或将其变为透明。使用 RGB 空间中的欧氏距离，并可配置容差，以在颜色边界处实现平滑过渡。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/replace-color`
接受包含一个图片文件和一个 JSON `settings` 字段的 multipart 表单数据。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| sourceColor | string | 否 | `"#FF0000"` | 要查找的十六进制颜色（格式：`#RRGGBB`） |
| targetColor | string | 否 | `"#00FF00"` | 要替换成的十六进制颜色（格式：`#RRGGBB`） |
| makeTransparent | boolean | 否 | `false` | 将匹配的像素变为透明，而不是替换为目标颜色 |
| tolerance | number | 否 | `30` | 颜色匹配容差（0 到 255）。值越高，匹配的相似颜色范围越广 |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/replace-color \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"sourceColor": "#FF0000", "targetColor": "#0000FF", "tolerance": 40}'
```
将绿色背景变为透明：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/replace-color \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@greenscreen.png" \
-F 'settings={"sourceColor": "#00FF00", "makeTransparent": true, "tolerance": 50}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.png",
"originalSize": 2450000,
"processedSize": 2100000
}
```
## 说明 {#notes}
- 颜色匹配使用 RGB 空间中的欧氏距离，并按 `tolerance * sqrt(3)` 缩放。
- 替换混合与颜色距离成正比：越接近源颜色的像素会获得越多的目标颜色，从而形成平滑过渡。
- 当 `makeTransparent` 为 `true` 时，如果输入格式不支持 alpha 通道（例如 JPEG），输出会被强制为 PNG（或 WebP/AVIF）。
- 容差为 0 时仅匹配完全一致的源颜色。较高的值（50 以上）会匹配更广范围的相似色调。
- 输出格式与输入格式一致，除非需要透明度而输入格式不支持 alpha。
apps/docs/zh-CN/tools/image/resize.md
+72
View File
@@ -0,0 +1,72 @@
---
description: "按像素、百分比或使用适配模式调整图片尺寸。"
i18n_source_hash: 00d1bffa4d38
i18n_provenance: human
i18n_output_hash: 0a8f45ef34da
---
# 调整尺寸 {#resize}
通过指定精确的像素尺寸、百分比缩放系数，或控制图片如何适配目标尺寸的适配模式来调整图片尺寸。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/resize`
接受包含一个图片文件和一个 JSON `settings` 字段的 multipart 表单数据。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| width | integer | 否 | - | 目标宽度（像素，最大 16383） |
| height | integer | 否 | - | 目标高度（像素，最大 16383） |
| fit | string | 否 | `"contain"` | 图片如何适配尺寸：`contain`、`cover`、`fill`、`inside`、`outside` |
| withoutEnlargement | boolean | 否 | `false` | 若图片小于目标尺寸则阻止放大 |
| percentage | number | 否 | - | 按百分比缩放（例如 50 表示缩至一半） |
必须至少提供 `width`、`height` 或 `percentage` 之一。
### 适配模式 {#fit-modes}
- **contain** - 调整尺寸以适配于给定尺寸之内，保持宽高比（可能留有空白）
- **cover** - 调整尺寸以覆盖给定尺寸，保持宽高比（可能裁剪）
- **fill** - 拉伸以精确匹配尺寸（忽略宽高比）
- **inside** - 类似 `contain`，但只缩小，绝不放大
- **outside** - 类似 `cover`，但只缩小，绝不放大
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/resize \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"width": 800, "height": 600, "fit": "contain"}'
```
按百分比调整尺寸：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/resize \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"percentage": 50}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
"originalSize": 2450000,
"processedSize": 980000
}
```
## 说明 {#notes}
- 任一轴向的最大尺寸为 16383 像素（Sharp/libvips 限制）。
- 输出格式与输入格式一致。HEIC、RAW、PSD 和 SVG 输入会在处理前自动解码。
- 调整尺寸前会自动应用 EXIF 方向。
- `withoutEnlargement` 标志对于批处理很有用，因为其中某些图片可能已经小于目标尺寸。
apps/docs/zh-CN/tools/image/restore-photo.md
+96
View File
@@ -0,0 +1,96 @@
---
description: "使用 AI 流水线修复旧照片上的划痕、破损和损伤，进行修复、人脸增强和上色。"
i18n_source_hash: 3de13284216c
i18n_provenance: human
i18n_output_hash: af039536e891
---
# 照片修复 {#photo-restoration}
使用多步骤 AI 流水线修复旧照片上的划痕、破损和损伤。整合了划痕修复、人脸增强、降噪以及可选的上色。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/restore-photo`
**处理方式：** 异步（返回 202，通过 SSE 轮询 `/api/v1/jobs/{jobId}/progress` 获取状态）
**模型包：** `photo-restoration`（4-5 GB）
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 图片文件（multipart） |
| scratchRemoval | boolean | 否 | `true` | 移除划痕和表面损伤 |
| faceEnhancement | boolean | 否 | `true` | 增强修复后照片中的人脸 |
| fidelity | number | 否 | `0.7` | 人脸增强保真度（0-1）。值越高越多地保留原始特征 |
| denoise | boolean | 否 | `true` | 对修复结果应用降噪 |
| denoiseStrength | number | 否 | `25` | 降噪强度（0-100） |
| colorize | boolean | 否 | `false` | 为修复后的照片上色（针对灰度图片） |
| colorizeStrength | number | 否 | `85` | 上色强度（0-100） |
## 请求示例 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/restore-photo \
-F "file=@damaged-old-photo.jpg" \
-F 'settings={"scratchRemoval":true,"faceEnhancement":true,"fidelity":0.6,"colorize":true}'
```
## 响应 {#response}
### 初始响应（202 Accepted） {#initial-response-202-accepted}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"async": true
}
```
### 进度（位于 `/api/v1/jobs/{jobId}/progress` 的 SSE） {#progress-sse-at-api-v1-jobs-jobid-progress}
```
event: progress
data: {"phase":"processing","stage":"Removing scratches...","percent":30}
```
```
event: progress
data: {"phase":"processing","stage":"Enhancing faces...","percent":60}
```
### 最终结果（通过 SSE） {#final-result-via-sse}
```json
{
"phase": "complete",
"percent": 100,
"result": {
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/damaged-old-photo_restored.jpg",
"previewUrl": "/api/v1/download/{jobId}/preview.webp",
"originalSize": 200000,
"processedSize": 350000,
"width": 1200,
"height": 900,
"steps": ["scratch_removal", "face_enhancement", "denoise", "colorize"],
"scratchCoverage": 12.5,
"facesEnhanced": 2,
"isGrayscale": true,
"colorized": true
}
}
```
## 说明 {#notes}
- 需要安装 `photo-restoration` 模型包（4-5 GB）。
- 该流水线依次运行多个 AI 步骤：划痕修复、人脸增强（GFPGAN）、降噪，以及可选的上色。
- 结果中的 `steps` 数组显示实际执行了哪些处理步骤。
- `scratchCoverage` 是有划痕损伤的图片面积的估算百分比。
- `fidelity` 控制人脸增强的强度与保留原始外观之间的权衡。较低的值产生更激进的增强；较高的值更为保守。
- `colorize` 选项会自动检测图片是否为灰度。结果中的 `isGrayscale` 标志确认此项检测。
- 输出格式会自动与输入格式一致。
- 通过自动解码支持 HEIC/HEIF、RAW、TGA、PSD、EXR、HDR 和 AVIF 输入格式。
apps/docs/zh-CN/tools/image/rotate.md
+71
View File
@@ -0,0 +1,71 @@
---
description: "按任意角度旋转图片，并进行水平或垂直翻转。"
i18n_source_hash: af2581d7cd8d
i18n_provenance: human
i18n_output_hash: dcbaa2a45cbf
---
# 旋转与翻转 {#rotate-flip}
按任意角度旋转图片，和/或对其进行水平或垂直翻转。旋转和翻转操作可以在单次请求中组合使用。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/rotate`
接受包含一个图片文件和一个 JSON `settings` 字段的 multipart 表单数据。
## 参数 {#parameters}
| 参数 | 类型 | 是否必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| angle | number | 否 | `0` | 旋转角度（度，顺时针）。接受任意数值。 |
| horizontal | boolean | 否 | `false` | 水平翻转图片（镜像） |
| vertical | boolean | 否 | `false` | 垂直翻转图片 |
## 请求示例 {#example-request}
顺时针旋转 90 度：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/rotate \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"angle": 90}'
```
水平翻转：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/rotate \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"horizontal": true}'
```
同时旋转和翻转：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/rotate \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"angle": 45, "vertical": true}'
```
## 响应示例 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
"originalSize": 2450000,
"processedSize": 2480000
}
```
## 说明 {#notes}
- 先应用旋转，再应用翻转操作。
- 非 90 度的旋转（例如 45 度）会扩大画布以容纳旋转后的图片，并根据输出格式使用透明或黑色填充。
- 常用值：90、180、270 用于四分之一圈旋转。
- 处理前会自动应用 EXIF 方向，因此旋转是相对于视觉方向的。
apps/docs/zh-CN/tools/image/sharpening.md
+71
View File
@@ -0,0 +1,71 @@
---
description: "使用自适应、USM 锐化或高通方法锐化图像，并可选降噪。"
i18n_source_hash: ccb60af9faae
i18n_provenance: human
i18n_output_hash: 8096d6bf1ecd
---
# 锐化 {#sharpening}
提供三种方法的高级锐化工具：自适应（智能边缘感知）、USM 锐化（经典的半径/强度）和高通（纹理强化）。内置降噪功能，可防止锐化产生伪影。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/sharpening`
接受包含图像文件和 JSON `settings` 字段的 multipart 表单数据。
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| method | string | 否 | `"adaptive"` | 锐化算法：`adaptive`、`unsharp-mask`、`high-pass` |
| sigma | number | 否 | `1.0` | 自适应：高斯 sigma（0.5 到 10） |
| m1 | number | 否 | `1.0` | 自适应：平坦区域锐化（0 到 10） |
| m2 | number | 否 | `3.0` | 自适应：锯齿区域锐化（0 到 20） |
| x1 | number | 否 | `2.0` | 自适应：平坦/锯齿阈值（0 到 10） |
| y2 | number | 否 | `12` | 自适应：最大平坦锐化（0 到 50） |
| y3 | number | 否 | `20` | 自适应：最大锯齿锐化（0 到 50） |
| amount | number | 否 | `100` | USM 锐化：锐化强度（0 到 1000） |
| radius | number | 否 | `1.0` | USM 锐化：模糊半径（像素，0.1 到 5） |
| threshold | number | 否 | `0` | USM 锐化：触发锐化的最小亮度差（0 到 255） |
| strength | number | 否 | `50` | 高通：滤波强度（0 到 100） |
| kernelSize | number | 否 | `3` | 高通：卷积核大小（3 或 5） |
| denoise | string | 否 | `"off"` | 锐化前降噪：`off`、`light`、`medium`、`strong` |
## 示例请求 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/sharpening \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"method": "adaptive", "sigma": 1.5}'
```
使用阈值保护平滑区域的 USM 锐化：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/sharpening \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"method": "unsharp-mask", "amount": 150, "radius": 1.5, "threshold": 10}'
```
## 示例响应 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
"originalSize": 2450000,
"processedSize": 2510000
}
```
## 说明 {#notes}
- 仅使用与所选方法相关的参数。例如，当 `method` 为 `adaptive` 时，`amount`、`radius` 和 `threshold` 会被忽略。
- 自适应方法使用 Sharp 内置的自适应锐化，可配置平坦/锯齿区域的行为。
- `denoise` 选项在锐化前应用降噪，以防止放大噪点/颗粒。
- 高通锐化通过从原图中减去模糊版本来提取细节，然后再混合回原图。
- 输出格式与输入格式一致。HEIC、RAW、PSD 和 SVG 输入在处理前会自动解码。
apps/docs/zh-CN/tools/image/smart-crop.md
+96
View File
@@ -0,0 +1,96 @@
---
description: "基于主体、人脸和熵的裁剪，使用 Sharp 和 AI 人脸检测智能地为图像取景。"
i18n_source_hash: acbe1439c6d8
i18n_provenance: human
i18n_output_hash: f0dcbc7bcece
---
# 智能裁剪 {#smart-crop}
智能的主体感知、人脸感知或基于修剪的裁剪。使用 Sharp 的注意力/熵策略和 AI 人脸检测实现智能取景。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/smart-crop`
**处理方式：** 异步（返回 202，通过 SSE 轮询 `/api/v1/jobs/{jobId}/progress` 获取状态）
**模型包：** `face-detection`（200-300 MB）- 仅 `face` 模式需要
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 图像文件（multipart） |
| mode | string | 否 | `"subject"` | 裁剪模式：`subject`、`face`、`trim`。（旧值 `attention` 和 `content` 分别映射到 `subject` 和 `trim`） |
| strategy | string | 否 | `"attention"` | 主体模式的策略：`attention` 或 `entropy` |
| width | integer | 否 | - | 目标宽度（像素） |
| height | integer | 否 | - | 目标高度（像素） |
| padding | integer | 否 | `0` | 主体周围的内边距百分比（0-50） |
| facePreset | string | 否 | `"head-shoulders"` | 人脸取景预设：`closeup`、`head-shoulders`、`upper-body`、`half-body` |
| sensitivity | number | 否 | `0.5` | 人脸检测灵敏度（0-1） |
| threshold | integer | 否 | `30` | 修剪模式下的背景检测阈值（0-255） |
| padToSquare | boolean | 否 | `false` | 将修剪后的结果填充为正方形 |
| padColor | string | 否 | `"#ffffff"` | 填充用的背景颜色 |
| targetSize | integer | 否 | - | 填充输出的目标尺寸（像素） |
| quality | integer | 否 | - | 输出质量（1-100） |
## 示例请求 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/smart-crop \
-F "file=@portrait.jpg" \
-F 'settings={"mode":"face","width":1080,"height":1080,"facePreset":"head-shoulders"}'
```
## 响应 {#response}
### 初始响应（202 Accepted） {#initial-response-202-accepted}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"async": true
}
```
### 进度（SSE，位于 `/api/v1/jobs/{jobId}/progress`） {#progress-sse-at-api-v1-jobs-jobid-progress}
```
event: progress
data: {"phase":"processing","percent":50}
```
### 最终结果（通过 SSE） {#final-result-via-sse}
```json
{
"phase": "complete",
"percent": 100,
"result": {
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/portrait_smartcrop.jpg",
"originalSize": 500000,
"processedSize": 320000
}
}
```
## 模式 {#modes}
### 主体模式 {#subject-mode}
使用 Sharp 的注意力或熵策略找到视觉上最有趣的区域，并围绕它进行裁剪。
### 人脸模式 {#face-mode}
使用 AI 检测人脸，然后根据指定的 `facePreset` 围绕检测到的人脸取景裁剪。如果未检测到人脸，则回退到主体模式（注意力策略）。
### 修剪模式 {#trim-mode}
移除图像中均匀的边框/背景。可选地使用指定的背景颜色和目标尺寸将结果填充为正方形。
## 说明 {#notes}
- 该工具使用带 `executionHint: "long"` 的 `createToolRoute` 工厂，因此返回 202 并附带 SSE 进度。
- 人脸模式需要 `face-detection` 模型包（200-300 MB）。
- 主体模式和修剪模式无需任何 AI 模型包即可工作。
- `facePreset` 决定裁剪对检测到的人脸取景的紧密程度：`closeup` 最紧凑，`half-body` 最宽松。
- 如果未指定宽度/高度，则默认为 1080x1080。
apps/docs/zh-CN/tools/image/split.md
+49
View File
@@ -0,0 +1,49 @@
---
description: "按行列数或像素尺寸将一张图像分割为网格图块，以 ZIP 压缩包形式返回。"
i18n_source_hash: 57a2e11e7cce
i18n_provenance: human
i18n_output_hash: 49ea1a52dd18
---
# 图像分割 {#image-splitting}
按列/行数或指定的像素尺寸将单张图像分割为网格图块。返回包含所有图块的 ZIP 压缩包。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/split`
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| columns | integer | 否 | 3 | 分割的列数（1 到 100） |
| rows | integer | 否 | 3 | 分割的行数（1 到 100） |
| tileWidth | integer | 否 | - | 图块宽度（像素，最小 10）。当同时设置 `tileWidth` 和 `tileHeight` 时，覆盖 `columns`。 |
| tileHeight | integer | 否 | - | 图块高度（像素，最小 10）。当同时设置 `tileWidth` 和 `tileHeight` 时，覆盖 `rows`。 |
| outputFormat | string | 否 | `"original"` | 图块的输出格式：`original`、`png`、`jpg`、`webp`、`avif`、`jxl` |
| quality | number | 否 | 90 | 有损格式的输出质量（1 到 100） |
## 示例请求 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/split \
-F "file=@large-image.png" \
-F 'settings={"columns":3,"rows":3,"outputFormat":"png"}' \
--output split-tiles.zip
```
## 示例响应 {#example-response}
响应以 ZIP 文件形式直接流式返回，附带 `Content-Type: application/zip`。文件名遵循 `split-<jobId>.zip` 的模式。
ZIP 内的每个图块命名为 `<originalBaseName>_r<row>_c<col>.<ext>`（例如 `photo_r1_c1.png`、`photo_r2_c3.webp`）。
## 说明 {#notes}
- 接受单个图像文件。
- 支持 HEIC、RAW、PSD 和 SVG 输入格式（自动解码）。
- 当同时提供 `tileWidth` 和 `tileHeight` 时，它们优先于 `columns`/`rows`。网格尺寸按 `ceil(imageWidth / tileWidth)` 和 `ceil(imageHeight / tileHeight)` 计算。
- 如果图像尺寸无法被整除，边缘图块（最右列、最底行）可能小于指定的图块尺寸。
- 网格尺寸最大限制为 100x100（10,000 个图块）。
- 响应直接流式返回 ZIP，因此没有 JSON 响应体。搭配 curl 使用 `--output` 来保存文件。
apps/docs/zh-CN/tools/image/sprite-sheet.md
+69
View File
@@ -0,0 +1,69 @@
---
description: "将多张图像合并为单个精灵表网格，并附带帧元数据。"
i18n_source_hash: 1938d7fb100d
i18n_provenance: human
i18n_output_hash: d9d3dc08d26a
---
# 精灵表 {#sprite-sheet}
将多张图像合并为单个精灵表网格。每张图像会被调整为与第一张图像相同的尺寸并放入网格中。返回精灵表图像以及每帧的坐标元数据。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/sprite-sheet`
接受包含两张或更多图像文件以及 JSON `settings` 字段的 multipart 表单数据。
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| columns | integer | 否 | `4` | 网格中的列数（1-16） |
| padding | integer | 否 | `0` | 单元格之间的间距（像素，0-64） |
| background | string | 否 | `"#ffffff"` | 背景十六进制颜色 |
| format | string | 否 | `"png"` | 输出格式：`png`、`webp` 或 `jpeg` |
| quality | integer | 否 | `90` | 输出质量（1-100） |
## 示例请求 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/sprite-sheet \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@frame1.png" \
-F "file=@frame2.png" \
-F "file=@frame3.png" \
-F "file=@frame4.png" \
-F 'settings={"columns": 2, "padding": 4, "format": "png"}'
```
## 示例响应 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/sprite-sheet.png",
"originalSize": 120000,
"processedSize": 95000,
"frames": [
{ "index": 0, "left": 0, "top": 0, "width": 128, "height": 128 },
{ "index": 1, "left": 132, "top": 0, "width": 128, "height": 128 },
{ "index": 2, "left": 0, "top": 132, "width": 128, "height": 128 },
{ "index": 3, "left": 132, "top": 132, "width": 128, "height": 128 }
],
"cols": 2,
"rows": 2,
"cellWidth": 128,
"cellHeight": 128,
"canvasWidth": 260,
"canvasHeight": 260
}
```
## 说明 {#notes}
- 接受 2 到 64 张图像。所有图像都会被调整为与第一张上传图像相同的尺寸。
- `frames` 数组提供输出中每一帧的精确像素坐标，适用于 CSS 精灵定义或游戏引擎帧图。
- 行数根据图像数量和 `columns` 值自动计算。
- 使用 `padding` 参数在单元格之间添加间距。`background` 颜色会显示在内边距区域以及任何末尾的空单元格中。
- HEIC、RAW、PSD 和 SVG 输入在处理前会自动解码。
apps/docs/zh-CN/tools/image/stitch.md
+63
View File
@@ -0,0 +1,63 @@
---
description: "将图像并排、堆叠或以网格方式拼接，可控制对齐、间距、边框和调整模式。"
i18n_source_hash: 39333210505a
i18n_provenance: human
i18n_output_hash: 87525c98302e
---
# 拼接/合并 {#stitch-combine}
将多张图像并排、垂直堆叠或以网格排列的方式拼接。支持对齐、间距、边框、圆角和多种调整模式。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/stitch`
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| direction | string | 否 | `"horizontal"` | 布局方向：`horizontal`、`vertical`、`grid` |
| gridColumns | integer | 否 | 2 | 当方向为 `grid` 时的列数（2 到 100） |
| resizeMode | string | 否 | `"fit"` | 图像调整方式：`fit`、`original`、`stretch`、`crop` |
| alignment | string | 否 | `"center"` | 交叉轴对齐：`start`、`center`、`end` |
| gap | number | 否 | 0 | 图像之间的间距（像素，0 到 1000） |
| border | number | 否 | 0 | 外边框宽度（像素，0 到 500） |
| cornerRadius | number | 否 | 0 | 应用于最终输出的圆角（0 到 500） |
| backgroundColor | string | 否 | `"#FFFFFF"` | 背景/边框颜色，十六进制（例如 `#FF0000`） |
| format | string | 否 | `"png"` | 输出格式：`png`、`jpeg`、`webp`、`avif`、`jxl` |
| quality | number | 否 | 90 | 输出质量（1 到 100） |
## 示例请求 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/stitch \
-F "file=@image1.png" \
-F "file=@image2.png" \
-F "file=@image3.png" \
-F 'settings={"direction":"horizontal","resizeMode":"fit","gap":10,"backgroundColor":"#FFFFFF","format":"png"}'
```
## 示例响应 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/stitch.png",
"originalSize": 1234567,
"processedSize": 987654
}
```
## 说明 {#notes}
- 至少需要 2 张图像。在 multipart 请求中上传多个图像文件。
- 支持 HEIC、RAW、PSD 和 SVG 输入格式（自动解码）。
- 调整模式：
- `fit` - 沿拼接轴将图像缩放至匹配最小尺寸。
- `original` - 保持原始尺寸（可能产生不齐的边缘）。
- `stretch` - 强制图像匹配最小尺寸，不保持宽高比。
- `crop` - 覆盖裁剪图像以匹配最小尺寸。
- 在 `grid` 模式下，单元格大小设为所有图像尺寸的中位数。
- `cornerRadius` 应用于整个最终输出，而非单张图像。
- 画布大小受 `MAX_CANVAS_PIXELS` 服务器配置限制，以防止内存耗尽。
apps/docs/zh-CN/tools/image/strip-metadata.md
+113
View File
@@ -0,0 +1,113 @@
---
description: "从图像中移除 EXIF、GPS、ICC 和 XMP 元数据，以保护隐私并减小文件大小。"
i18n_source_hash: e89147734fd0
i18n_provenance: human
i18n_output_hash: 0beed818cd0e
---
# 移除元数据 {#remove-metadata}
从图像中移除 EXIF、GPS、ICC 色彩配置文件和 XMP 元数据。适用于保护隐私（移除 GPS 坐标、相机信息）以及减小文件大小。
## API 端点 {#api-endpoints}
### 移除元数据 {#strip-metadata}
`POST /api/v1/tools/image/strip-metadata`
处理图像并返回移除了所选元数据的清理版本。
### 检查元数据 {#inspect-metadata}
`POST /api/v1/tools/image/strip-metadata/inspect`
以 JSON 形式返回解析后的元数据，不修改图像。适用于在移除前预览存在哪些元数据。
## 参数（移除） {#parameters-strip}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| stripExif | boolean | 否 | `false` | 移除 EXIF 数据（相机设置、日期等） |
| stripGps | boolean | 否 | `false` | 仅移除 GPS/位置数据 |
| stripIcc | boolean | 否 | `false` | 移除 ICC 色彩配置文件 |
| stripXmp | boolean | 否 | `false` | 移除 XMP 元数据（Adobe、IPTC） |
| stripAll | boolean | 否 | `true` | 一次性移除所有元数据 |
当 `stripAll` 为 `true` 时，它会覆盖各个单独的标志并移除所有内容。
## 示例请求 {#example-request}
移除所有元数据：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/strip-metadata \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"stripAll": true}'
```
仅移除 GPS 数据（保留相机信息和色彩配置文件）：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/strip-metadata \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"stripAll": false, "stripGps": true}'
```
检查元数据而不修改：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/strip-metadata/inspect \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg"
```
## 示例响应（移除） {#example-response-strip}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
"originalSize": 2450000,
"processedSize": 2380000
}
```
## 示例响应（检查） {#example-response-inspect}
```json
{
"filename": "photo.jpg",
"fileSize": 2450000,
"exif": {
"Make": "Canon",
"Model": "EOS R5",
"DateTimeOriginal": "2024:03:15 14:30:00",
"ExposureTime": "1/250",
"FNumber": 2.8,
"ISO": 400
},
"gps": {
"GPSLatitudeRef": "N",
"GPSLatitude": [37, 46, 30],
"_latitude": 37.775,
"_longitude": -122.4183
},
"icc": {
"Profile Size": "3144 bytes",
"Color Space": "RGB",
"Description": "sRGB IEC61966-2.1"
},
"xmp": {
"CreatorTool": "Adobe Photoshop 25.0"
}
}
```
## 说明 {#notes}
- 移除后，图像会以其原始格式重新编码。JPEG 使用 mozjpeg 以质量 90 编码，PNG 使用压缩级别 9，WebP 使用质量 85。
- 如果图像标记了非 sRGB 配置文件，移除 ICC 配置文件可能导致细微的色彩偏移。如果色彩准确性很重要，请使用 `stripIcc: false`。
- 检查端点会将 GPS 坐标解析为十进制的纬度/经度值（以下划线为前缀）以便使用。
- 支持的输入格式：JPEG、PNG、WebP、AVIF、TIFF、GIF。
apps/docs/zh-CN/tools/image/svg-to-raster.md
+85
View File
@@ -0,0 +1,85 @@
---
description: "以自定义分辨率和 DPI 将 SVG 文件转换为 PNG、JPEG、WebP、AVIF、TIFF、GIF、HEIF 或 JXL，并支持批量处理。"
i18n_source_hash: cf36830f8797
i18n_provenance: human
i18n_output_hash: c79bbc83c528
---
# SVG 转位图 {#svg-to-raster}
以自定义分辨率和 DPI 将 SVG 文件转换为位图图像格式（PNG、JPEG、WebP、AVIF、TIFF、GIF、HEIF 或 JXL）。同时支持多个 SVG 的批量转换。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/svg-to-raster`
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| width | integer | 否 | - | 目标宽度（像素，1 到 65536）。若仅设置一个维度则保持宽高比。 |
| height | integer | 否 | - | 目标高度（像素，1 到 65536）。若仅设置一个维度则保持宽高比。 |
| dpi | integer | 否 | 300 | 渲染 DPI，控制基础栅格化密度（36 到 2400） |
| quality | number | 否 | 90 | 有损格式的输出质量（1 到 100） |
| backgroundColor | string | 否 | `"#00000000"` | 背景颜色，十六进制（6 或 8 个字符，8 字符含 alpha） |
| outputFormat | string | 否 | `"png"` | 输出格式：`png`、`jpg`、`webp`、`avif`、`tiff`、`gif`、`heif`、`jxl` |
## 示例请求 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/svg-to-raster \
-F "file=@logo.svg" \
-F 'settings={"width":1024,"dpi":300,"outputFormat":"png","backgroundColor":"#FFFFFF"}'
```
## 示例响应 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/logo.png",
"previewUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/preview.webp",
"originalSize": 12345,
"processedSize": 67890
}
```
## 批量端点 {#batch-endpoint}
`POST /api/v1/tools/image/svg-to-raster/batch`
在一次请求中转换多个 SVG 文件。返回 ZIP 压缩包。
### 额外的批量参数 {#additional-batch-parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| clientJobId | string | 否 | - | 可选的客户端提供的作业 ID，用于进度跟踪（最多 128 个字符） |
### 批量示例请求 {#batch-example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/svg-to-raster/batch \
-F "file=@icon1.svg" \
-F "file=@icon2.svg" \
-F "file=@icon3.svg" \
-F 'settings={"width":512,"outputFormat":"png","dpi":150}'
```
### 批量响应 {#batch-response}
批量端点直接流式返回 ZIP 文件，附带以下标头：
- `Content-Type: application/zip`
- `X-Job-Id: <jobId>`
- `X-File-Results: <url-encoded JSON mapping of index to filename>`
## 说明 {#notes}
- 仅接受 SVG 和 SVGZ 文件（验证内容，而不仅是扩展名）。SVGZ 会被自动解压。
- SVG 内容在渲染前会被净化，以防止 XSS 和外部资源加载。
- `dpi` 设置控制 SVG 栅格化的密度。更高的 DPI 会从相同的 SVG 视口产生更大的像素尺寸。
- 当同时提供 `width` 和 `height` 时，图像会使用 `fit: inside` 进行调整（在边界内保持宽高比）。
- 对于浏览器无法原生显示的格式（TIFF、HEIF），响应中会包含 `previewUrl`。预览是 1200px 的 WebP 缩略图。
- 默认背景 `#00000000` 为完全透明。设为 `#FFFFFF` 可获得白色背景（对不支持透明度的 JPEG 输出很有用）。
- 批量处理遵循 `MAX_BATCH_SIZE` 服务器配置，并使用并发工作进程以提升性能。
- 批量操作的进度可通过 `/api/v1/jobs/:jobId/progress` 处的 SSE 跟踪。
apps/docs/zh-CN/tools/image/text-overlay.md
+66
View File
@@ -0,0 +1,66 @@
---
description: "添加带投影和背景框的样式化文字叠加。"
i18n_source_hash: 9f8e697188fc
i18n_provenance: human
i18n_output_hash: d0640359fbc4
---
# 文字叠加 {#text-overlay}
为图像添加带可选投影和半透明背景框的样式化文字。适用于照片上的标题、说明文字或注释。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/text-overlay`
接受包含图像文件和 JSON `settings` 字段的 multipart 表单数据。
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| text | string | 是 | - | 要叠加的文字（1 到 500 个字符） |
| fontSize | number | 否 | `48` | 字体大小（像素，8 到 200） |
| color | string | 否 | `"#FFFFFF"` | 文字颜色，十六进制格式（`#RRGGBB`） |
| position | string | 否 | `"bottom"` | 垂直位置：`top`、`center`、`bottom` |
| backgroundBox | boolean | 否 | `false` | 在文字后显示半透明背景矩形 |
| backgroundColor | string | 否 | `"#000000"` | 背景框颜色，十六进制格式（`#RRGGBB`） |
| shadow | boolean | 否 | `true` | 在文字后应用投影 |
## 示例请求 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/text-overlay \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"text": "Hello World", "fontSize": 64, "color": "#FFFFFF", "position": "bottom", "shadow": true}'
```
带背景框：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/text-overlay \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"text": "Caption", "fontSize": 36, "position": "bottom", "backgroundBox": true, "backgroundColor": "#000000"}'
```
## 示例响应 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
"originalSize": 2450000,
"processedSize": 2470000
}
```
## 说明 {#notes}
- 文字在图像中始终水平居中。
- 投影使用 2px 偏移、3px 模糊，黑色不透明度为 70%。
- 背景框跨越整个图像宽度，不透明度为 70%，高度与字体大小成比例（1.8 倍）。
- 文字通过 SVG 合成渲染，因此使用系统默认的无衬线字体。
- 文字中的 XML 特殊字符会被安全转义。
- 输出格式与输入格式一致。HEIC、RAW、PSD 和 SVG 输入在处理前会自动解码。
apps/docs/zh-CN/tools/image/transparency-fixer.md
+78
View File
@@ -0,0 +1,78 @@
---
description: "使用 AI 抠图（BiRefNet）修复伪透明 PNG，生成真正的 alpha 通道，并进行去边缘杂色清理。"
i18n_source_hash: 7eb748b80f93
i18n_provenance: human
i18n_output_hash: bf179732f8ea
---
# PNG 透明度修复器 {#png-transparency-fixer}
一键修复伪透明 PNG。使用 AI 抠图（BiRefNet HR Matting 模型）生成真正的 alpha 透明度，并通过去边缘后处理清理边缘。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/transparency-fixer`
**处理方式：** 异步（返回 202，通过 SSE 轮询 `/api/v1/jobs/{jobId}/progress` 获取状态）
**模型包：** `background-removal`（4-5 GB）
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 图像文件（multipart） |
| defringe | number | 否 | `30` | 去边缘强度（0-100）。移除边缘周围的半透明杂色像素 |
| outputFormat | string | 否 | `"png"` | 输出格式：`png` 或 `webp` |
| removeWatermark | boolean | 否 | `false` | 应用水印移除预处理（中值滤波） |
## 示例请求 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \
-F "file=@fake-transparent.png" \
-F 'settings={"defringe":40,"outputFormat":"png"}'
```
## 响应 {#response}
### 初始响应（202 Accepted） {#initial-response-202-accepted}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"async": true
}
```
### 进度（SSE，位于 `/api/v1/jobs/{jobId}/progress`） {#progress-sse-at-api-v1-jobs-jobid-progress}
```
event: progress
data: {"phase":"processing","stage":"Processing transparency...","percent":50}
```
### 最终结果（通过 SSE） {#final-result-via-sse}
```json
{
"phase": "complete",
"percent": 100,
"result": {
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/fake-transparent_fixed.png",
"originalSize": 180000,
"processedSize": 150000,
"filename": "fake-transparent.png"
}
}
```
## 说明 {#notes}
- 需要安装 `background-removal` 模型包（4-5 GB）。
- 使用 `birefnet-hr-matting` 作为高质量 alpha 抠图的主模型。如果 HR 模型内存不足，则回退到 `birefnet-general`。
- `defringe` 选项移除 AI 抠图有时在头发、毛发和细边缘周围留下的半透明杂色像素。其原理是模糊 alpha 通道并将低置信度像素置零。
- `removeWatermark` 选项应用中值滤波预处理步骤。这是一种基础的水印削弱，而非专用的水印移除工具。
- 仅输出 PNG 或无损 WebP（两者都支持 alpha 透明度）。
- 通过自动解码支持 HEIC/HEIF、RAW、TGA、PSD、EXR 和 HDR 输入格式。
apps/docs/zh-CN/tools/image/upscale.md
+83
View File
@@ -0,0 +1,83 @@
---
description: "使用 Real-ESRGAN AI 超分辨率将图像放大 2 到 4 倍，同时保留细节。"
i18n_source_hash: 150032e99476
i18n_provenance: human
i18n_output_hash: 464013380e6f
---
# 图像放大 {#image-upscaling}
使用 Real-ESRGAN 进行 AI 超分辨率增强。将图像放大 2 到 4 倍，同时保留细节。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/upscale`
**处理方式：** 异步（返回 202，通过 SSE 轮询 `/api/v1/jobs/{jobId}/progress` 获取状态）
**模型包：** `upscale-enhance`（5-6 GB）
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| file | file | 是 | - | 图像文件（multipart） |
| scale | number | 否 | `2` | 放大倍数（例如 2、3、4） |
| model | string | 否 | `"auto"` | 使用的模型（例如 `auto`、具体模型名称） |
| faceEnhance | boolean | 否 | `false` | 在放大过程中应用人脸增强 |
| denoise | number | 否 | `0` | 降噪强度（0 = 关闭） |
| format | string | 否 | `"auto"` | 输出格式：`auto`、`png`、`jpg`、`webp`、`tiff`、`gif`、`avif`、`heic`、`heif`、`jxl` |
| quality | number | 否 | `95` | 输出质量（1-100） |
## 示例请求 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/upscale \
-F "file=@photo.jpg" \
-F 'settings={"scale":4,"model":"auto","faceEnhance":true,"format":"png"}'
```
## 响应 {#response}
### 初始响应（202 Accepted） {#initial-response-202-accepted}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"async": true
}
```
### 进度（SSE，位于 `/api/v1/jobs/{jobId}/progress`） {#progress-sse-at-api-v1-jobs-jobid-progress}
```
event: progress
data: {"phase":"processing","stage":"Upscaling...","percent":60}
```
### 最终结果（通过 SSE） {#final-result-via-sse}
```json
{
"phase": "complete",
"percent": 100,
"result": {
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/{jobId}/photo_4x.png",
"previewUrl": "/api/v1/download/{jobId}/preview.webp",
"originalSize": 120000,
"processedSize": 2400000,
"width": 4096,
"height": 4096,
"method": "realesrgan-x4plus"
}
}
```
## 说明 {#notes}
- 需要安装 `upscale-enhance` 模型包（5-6 GB）。
- 可用时使用 Real-ESRGAN；如果 AI 模型不可用，则回退到 Lanczos 插值。
- `faceEnhance` 选项在放大过程中应用 GFPGAN 人脸修复，以获得更好的人脸质量。
- 对于非浏览器可预览的输出格式（HEIC、JXL、TIFF），会在主输出之外生成 WebP 预览。
- 通过自动解码支持 HEIC/HEIF、RAW、TGA、PSD、EXR 和 HDR 输入格式。
apps/docs/zh-CN/tools/image/vectorize.md
+64
View File
@@ -0,0 +1,64 @@
---
description: "将位图图像转换为 SVG，支持黑白（potrace）和全彩多层矢量化。"
i18n_source_hash: f3e4777188ad
i18n_provenance: human
i18n_output_hash: 9bd31316b327
---
# 图像转 SVG {#image-to-svg}
使用追踪算法将位图图像矢量化为 SVG。支持黑白追踪（potrace）和全彩多层矢量化。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/vectorize`
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| colorMode | string | 否 | `"bw"` | 追踪模式：`bw`（黑白）或 `color`（多色图层） |
| threshold | number | 否 | 128 | 黑白模式的亮度阈值（0 到 255）。低于此值的像素变为黑色。 |
| colorPrecision | number | 否 | 6 | 彩色模式的颜色量化精度（1 到 16）。值越高产生的独立色层越多。 |
| layerDifference | number | 否 | 6 | 彩色模式下图层之间的最小颜色差异（1 到 128） |
| filterSpeckle | number | 否 | 4 | 追踪形状的最小面积（像素，1 到 256）。移除噪点/斑点。 |
| pathMode | string | 否 | `"spline"` | 路径平滑：`none`（锯齿）、`polygon`（直线段）、`spline`（平滑曲线） |
| cornerThreshold | number | 否 | 60 | 彩色模式下角点检测的角度阈值（0 到 180 度） |
| invert | boolean | 否 | `false` | 追踪前反转图像（交换黑白） |
## 示例请求 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/vectorize \
-F "file=@logo.png" \
-F 'settings={"colorMode":"bw","threshold":128,"filterSpeckle":4,"pathMode":"spline"}'
```
### 彩色矢量化 {#color-vectorization}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/vectorize \
-F "file=@illustration.png" \
-F 'settings={"colorMode":"color","colorPrecision":8,"layerDifference":6,"filterSpeckle":4}'
```
## 示例响应 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/logo.svg",
"originalSize": 45678,
"processedSize": 12345
}
```
## 说明 {#notes}
- 无论输入格式如何，输出始终为 SVG 文件。
- 支持 HEIC、RAW、PSD 和 SVG 输入格式（在追踪前自动解码为位图）。
- 黑白模式使用 potrace 算法。图像先转换为灰度，然后在追踪前进行阈值化处理为纯黑白。
- 彩色模式采用多层方法：图像被量化为多个色层，每层单独追踪并在 SVG 输出中堆叠。
- 较低的 `filterSpeckle` 值保留更多细节，但会产生路径更多、体积更大的 SVG 文件。
- `pathMode` 设置对文件大小影响显著：`none` 产生最多的路径，`spline` 产生最平滑（通常也是最小）的输出。
- 对于徽标和图标，使用黑白模式配合干净的高对比度输入可获得最佳效果。对于照片或插图，使用彩色模式并配合较高的 `colorPrecision`。
apps/docs/zh-CN/tools/image/vignette.md
+55
View File
@@ -0,0 +1,55 @@
---
description: "添加暗角效果，可调整强度、颜色和位置。"
i18n_source_hash: 0b9795fea2eb
i18n_provenance: human
i18n_output_hash: 3006e6b25805
---
# 暗角 {#vignette}
添加使图像边缘变暗或着色的暗角效果。支持可调整的强度、颜色、半径、柔和度、圆度和中心位置。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/vignette`
接受包含图像文件和 JSON `settings` 字段的 multipart 表单数据。
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| strength | number | 否 | `0.5` | 暗角不透明度（0.1-1） |
| color | string | 否 | `"#000000"` | 暗角十六进制颜色 |
| radius | integer | 否 | `70` | 外半径，占半对角线的百分比（0-100） |
| softness | integer | 否 | `50` | 羽化柔和度（0-100）；值越高过渡越平缓 |
| roundness | integer | 否 | `100` | 形状：100 = 圆形，0 = 匹配图像宽高比的椭圆 |
| centerX | integer | 否 | `50` | 水平中心位置，百分比（0-100） |
| centerY | integer | 否 | `50` | 垂直中心位置，百分比（0-100） |
## 示例请求 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/vignette \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"strength": 0.7, "radius": 60, "softness": 70}'
```
## 示例响应 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
"originalSize": 2450000,
"processedSize": 2410000
}
```
## 说明 {#notes}
- 较小的 `radius` 会使图像更多区域变暗；较大的半径会将暗角限制在最边缘处。
- 使用非黑色的 `color`（例如白色或棕褐色调）可实现有创意的暗角效果。
- 调整 `centerX` 和 `centerY` 可让清晰区域偏离中心，适用于将焦点引向不在画面中央的主体。
- 输出格式与输入格式一致。HEIC、RAW、PSD 和 SVG 输入在处理前会自动解码。
apps/docs/zh-CN/tools/image/watermark-image.md
+61
View File
@@ -0,0 +1,61 @@
---
description: "将徽标或图像作为水印叠加，可配置位置、不透明度和缩放。"
i18n_source_hash: c73ab0ef8ab9
i18n_provenance: human
i18n_output_hash: fcce0a92b138
---
# 图像水印 {#image-watermark}
将徽标或副图像作为水印叠加到基础图像上。水印相对于基础图像宽度进行缩放，并放置在角落或中心。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/watermark-image`
接受包含**两个**图像文件和 JSON `settings` 字段的 multipart 表单数据。
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| position | string | 否 | `"bottom-right"` | 水印位置：`center`、`top-left`、`top-right`、`bottom-left`、`bottom-right` |
| opacity | number | 否 | `50` | 水印不透明度百分比（0 到 100） |
| scale | number | 否 | `25` | 水印宽度占主图像宽度的百分比（1 到 100） |
### 文件字段 {#file-fields}
| 字段名 | 必填 | 说明 |
|------------|----------|-------------|
| file | 是 | 主图像/基础图像 |
| watermark | 是 | 水印/徽标图像 |
## 示例请求 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/watermark-image \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F "watermark=@logo.png" \
-F 'settings={"position": "bottom-right", "opacity": 60, "scale": 20}'
```
## 示例响应 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
"originalSize": 2450000,
"processedSize": 2520000
}
```
## 说明 {#notes}
- 两张图像都会被验证和解码（支持 HEIC、RAW、PSD、SVG）。
- 水印会按比例调整大小，使其宽度等于主图像宽度的 `scale`%。
- 不透明度通过与 `dest-in` 混合合成的 alpha 蒙版应用。
- 角落位置距图像边缘使用 20px 的内边距。
- 如果水印图像带有透明度（例如 PNG 徽标），合成期间会保留透明度。
- 处理前会在两张图像上自动应用 EXIF 方向。
apps/docs/zh-CN/tools/image/watermark-text.md
+65
View File
@@ -0,0 +1,65 @@
---
description: "添加文字水印，可配置位置、不透明度、旋转和平铺。"
i18n_source_hash: b80f12f410e4
i18n_provenance: human
i18n_output_hash: 471457a79ffa
---
# 文字水印 {#text-watermark}
为图像添加文字水印叠加。支持在角落/中心的单个位置放置，或在整幅图像上平铺重复，可配置字体大小、颜色、不透明度和旋转。
## API 端点 {#api-endpoint}
`POST /api/v1/tools/image/watermark-text`
接受包含图像文件和 JSON `settings` 字段的 multipart 表单数据。
## 参数 {#parameters}
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|-----------|------|----------|---------|-------------|
| text | string | 是 | - | 水印文字（1 到 500 个字符） |
| fontSize | number | 否 | `48` | 字体大小（像素，8 到 1000） |
| color | string | 否 | `"#000000"` | 文字颜色，十六进制格式（`#RRGGBB`） |
| opacity | number | 否 | `50` | 文字不透明度百分比（0 到 100） |
| position | string | 否 | `"center"` | 位置：`center`、`top-left`、`top-right`、`bottom-left`、`bottom-right`、`tiled` |
| rotation | number | 否 | `0` | 文字旋转角度（度，-360 到 360） |
## 示例请求 {#example-request}
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/watermark-text \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"text": "SAMPLE", "fontSize": 64, "opacity": 30, "position": "center", "rotation": -30}'
```
在整幅图像上平铺的水印：
```bash
curl -X POST http://localhost:1349/api/v1/tools/image/watermark-text \
-H "Authorization: Bearer si_your-api-key" \
-F "file=@photo.jpg" \
-F 'settings={"text": "DRAFT", "fontSize": 36, "opacity": 20, "position": "tiled", "rotation": -45}'
```
## 示例响应 {#example-response}
```json
{
"jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/photo.jpg",
"originalSize": 2450000,
"processedSize": 2480000
}
```
## 说明 {#notes}
- 水印以 SVG 文字形式渲染并合成到图像上，保持输出质量。
- 平铺模式根据字体大小设置文字元素的间距（水平 6 倍、垂直 4 倍间距），最多 500 个元素。
- 对于角落位置，距边缘的内边距等于字体大小。
- 使用的字体是系统默认的无衬线字体。
- 文字中的 XML 特殊字符（`&`、`<`、`>`、`"`、`'`）会被安全转义。
- 输出格式与输入格式一致。HEIC、RAW、PSD 和 SVG 输入在处理前会自动解码。