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

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.
2026-08-03 07:46:42 +02:00 · 2026-07-11 13:52:47 +08:00
parent 00b651c9f8
commit 4963ab3bbd
3620 changed files with 306134 additions and 0 deletions
@@ -0,0 +1,438 @@
+---
+description: "AI 引擎参考，涵盖所有本地 ML 工具。抠图、放大、OCR、人脸检测、照片修复等。"
+i18n_source_hash: 14728c1dcd05
+i18n_provenance: machine
+i18n_output_hash: 4f22ccca588a
+---
+
+# AI 引擎参考 {#ai-engine-reference}
+
+`@snapotter/ai` 包将 Node.js 与一个**常驻的 Python 边车进程**桥接，用于所有 ML 操作。调度器进程在请求之间保持存活，以获得快速的热启动性能。启动时会自动检测 NVIDIA CUDA，并在可用时使用；否则 AI 工具在 CPU 上运行。
+
+目前不支持通过 VA-API、Quick Sync 或 OpenCL 使用 Intel/AMD 集成显卡加速 AI 推理。将 `/dev/dri` 映射到容器中并不会加速这些 Python 边车工具，除非有支持 CUDA 的 NVIDIA GPU 可用。
+
+19 个 Python 边车 AI 工具，覆盖四种模态（图像、音频、视频、文档），另有 2 个具备可选 AI 能力的工具。所有模型均在本地运行，首次下载模型后无需联网。
+
+## 架构 {#architecture}
+
+```
+Node.js Tool Route
+      |
+      v
+ @snapotter/ai bridge.ts
+      | (stdin/stdout JSON + stderr progress events)
+      v
+ Python dispatcher (persistent process, "ai" profile)
+      |
+      |-- remove_bg.py        (rembg / BiRefNet)
+      |-- upscale.py          (RealESRGAN)
+      |-- inpaint.py          (LaMa ONNX)
+      |-- outpaint.py         (LaMa canvas expansion)
+      |-- ocr.py              (PaddleOCR / Tesseract)
+      |-- ocr_pdf.py          (page-by-page document OCR)
+      |-- ocr_preprocess.py   (image enhancement for OCR)
+      |-- detect_faces.py     (MediaPipe)
+      |-- face_landmarks.py   (MediaPipe landmarks)
+      |-- enhance_faces.py    (GFPGAN / CodeFormer)
+      |-- colorize.py         (DDColor)
+      |-- noise_removal.py    (SCUNet / tiered denoising)
+      |-- red_eye_removal.py  (landmark + color analysis)
+      |-- restore.py          (scratch repair + enhancement + denoising)
+      |-- transcribe.py       (faster-whisper speech-to-text)
+      +-- install_feature.py  (on-demand bundle installer)
+```
+
+一个独立的 "docs" 调度器配置用文档处理脚本（`doc_pagecount`、`doc_health`、`doc_flatten`、`doc_redact`、`doc_text`、`doc_to_word`、`doc_metadata`、`doc_html_pdf`）替换了 AI 白名单，并跳过繁重的 ML 导入。
+
+**超时：** 默认 300 秒；OCR 和 BiRefNet 抠图为 600 秒。
+
+## 功能包 {#feature-bundles}
+
+AI 模型按共享依赖栈打包，而不是每个工具一个归档。当多个工具使用同一模型系列、Python wheel 或原生库时，一个功能包可以启用多个工具。这样可以让发布用的 Docker 镜像更小，并避免重复存储相同的抠图、人脸检测、OCR、修复和语音模型副本。
+
+Docker 镜像随附应用程序以及通用运行时。大型模型归档会按需下载到常驻的 `/data/ai` 卷中，然后供每个需要它的工具复用。如果某个包因为另一个工具需要而已经安装，那么启用一个新的依赖工具时不会再次下载该包。
+
+每个 AI 工具在运行前都需要一个或多个功能包。管理后台 UI 通过 `POST /api/v1/admin/tools/:toolId/features/install` 按工具进行安装，它会解析完整的包列表，跳过已安装的包，仅将缺失的下载排入队列。例如，在全新实例上启用护照照片会将 `background-removal` 和 `face-detection` 排入队列；在已安装抠图之后再启用它，则只会将 `face-detection` 排入队列。
+
+| 功能包 | 大小 | 共享依赖组 | 使用它的工具 |
+|--------|------|-------------------------|-------------------|
+| `background-removal` | 4-5 GB | rembg / BiRefNet 抠图 | remove-background、passport-photo、transparency-fixer、background-replace、blur-background |
+| `face-detection` | 200-300 MB | MediaPipe 人脸检测与关键点 | blur-faces、red-eye-removal、smart-crop |
+| `object-eraser-colorize` | 1-2 GB | LaMa 图像修复/外扩与 DDColor | erase-object、colorize、ai-canvas-expand |
+| `upscale-enhance` | 5-6 GB | RealESRGAN、GFPGAN / CodeFormer、降噪 | upscale、enhance-faces、noise-removal |
+| `photo-restoration` | 4-5 GB | 划痕修复与修复流水线 | restore-photo |
+| `ocr` | 5-6 GB | PaddleOCR / Tesseract OCR 栈 | ocr、ocr-pdf |
+| `transcription` | ~600 MB | faster-whisper 语音转文本模型 | transcribe-audio、auto-subtitles |
+
+具有跨包依赖的工具：
+
+| 工具 | 所需功能包 | 原因 |
+|------|------------------|-----|
+| `passport-photo` | `background-removal`、`face-detection` | 先移除背景，然后使用人脸关键点将裁剪对齐到护照和证件照规则。 |
+| `enhance-faces` | `upscale-enhance`、`face-detection` | 在对选定的人脸区域运行 GFPGAN 或 CodeFormer 增强之前先检测人脸。 |
+
+只有当某个工具的全部所需功能包都已安装时，该工具才可用。部分安装是有效的，并会以增量方式处理：已安装的包会被复用，缺失的包显示为待下载项，排队的安装逐个执行，从而避免并发修改共享的 Python 环境。
+
+---
+
+## 抠图 {#background-removal}
+
+**工具路由：** `remove-background`  
+**模型：** 采用 BiRefNet（默认）或 U2-Net 变体的 rembg
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `model` | string | - | 模型变体（可选覆盖） |
+| `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 | - | 移除边缘的颜色溢出 |
+
+## 背景替换 {#background-replace}
+
+**工具路由：** `background-replace`  
+**模型：** rembg / BiRefNet（与 remove-background 共享）
+
+移除背景并将其替换为纯色或渐变。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `backgroundType` | `"color"` \| `"gradient"` | `"color"` | 背景模式 |
+| `color` | string | `"#ffffff"` | 背景十六进制颜色（当 `backgroundType` 为 `color` 时） |
+| `gradientColor1` | string | - | 第一个渐变十六进制颜色 |
+| `gradientColor2` | string | - | 第二个渐变十六进制颜色 |
+| `gradientAngle` | integer (0-360) | `180` | 渐变角度（度） |
+| `feather` | integer (0-20) | `0` | 边缘羽化半径 |
+| `format` | `"png"` \| `"webp"` | `"png"` | 输出格式 |
+
+## 背景模糊 {#blur-background}
+
+**工具路由：** `blur-background`  
+**模型：** rembg / BiRefNet（与 remove-background 共享）
+
+在保持主体清晰的同时模糊背景。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `intensity` | integer (1-100) | `50` | 模糊强度 |
+| `feather` | integer (0-20) | `0` | 边缘羽化半径 |
+| `format` | `"png"` \| `"webp"` | `"png"` | 输出格式 |
+
+## 图像放大 {#image-upscaling}
+
+**工具路由：** `upscale`  
+**模型：** RealESRGAN（不可用时回退到 Lanczos）
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `scale` | number | `2` | 放大倍数 |
+| `model` | string | `"auto"` | 模型变体 |
+| `faceEnhance` | boolean | `false` | 应用 GFPGAN 人脸增强处理 |
+| `denoise` | number | `0` | 降噪强度 |
+| `format` | string | `"auto"` | 输出格式覆盖 |
+| `quality` | number | `95` | 输出质量（1-100） |
+
+## OCR / 文本提取 {#ocr-text-extraction}
+
+**工具路由：** `ocr`  
+**模型：** Tesseract（快速）、PaddleOCR PP-OCRv5（均衡）、PaddleOCR-VL 1.5（最佳）
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | 处理档次 |
+| `language` | string | `"auto"` | 语言：`auto`、`en`、`de`、`fr`、`es`、`zh`、`ja`、`ko` |
+| `enhance` | boolean | `true` | 预处理图像以提升 OCR 准确率 |
+| `engine` | string | - | 已弃用。将 `tesseract` 映射到 `fast`，将 `paddleocr` 映射到 `balanced` |
+
+返回带有边界框、置信度分数和提取文本块的结构化结果。
+
+## PDF OCR {#pdf-ocr}
+
+**工具路由：** `ocr-pdf`  
+**模型：** 与图像 OCR 相同的档次体系
+
+使用 AI 驱动的 OCR 逐页从扫描的 PDF 文档中提取文本。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | 处理档次 |
+| `language` | string | `"auto"` | 语言：`auto`、`en`、`de`、`fr`、`es`、`zh`、`ja`、`ko` |
+| `pages` | string | `"all"` | 页面选择：`"all"`、`"1-3"`、`"1,3,5"` |
+
+## 人脸 / PII 模糊 {#face-pii-blur}
+
+**工具路由：** `blur-faces`  
+**模型：** MediaPipe 人脸检测
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `blurRadius` | number (1-100) | `30` | 高斯模糊半径 |
+| `sensitivity` | number (0-1) | `0.5` | 检测置信度阈值 |
+
+## 人脸增强 {#face-enhancement}
+
+**工具路由：** `enhance-faces`  
+**模型：** GFPGAN、CodeFormer
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `model` | `"auto"` \| `"gfpgan"` \| `"codeformer"` | `"auto"` | 增强模型 |
+| `strength` | number (0-1) | `0.8` | 增强强度 |
+| `sensitivity` | number (0-1) | `0.5` | 人脸检测阈值 |
+| `onlyCenterFace` | boolean | `false` | 仅增强最居中的人脸 |
+
+## AI 上色 {#ai-colorization}
+
+**工具路由：** `colorize`  
+**模型：** DDColor（回退到 OpenCV DNN）
+
+将黑白或灰度照片转换为全彩。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `intensity` | number (0-1) | `1.0` | 色彩饱和度强度 |
+| `model` | `"auto"` \| `"ddcolor"` \| `"opencv"` | `"auto"` | 模型变体 |
+
+## 噪点去除 {#noise-removal}
+
+**工具路由：** `noise-removal`  
+**模型：** SCUNet（分档降噪流水线）
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `tier` | `"quick"` \| `"balanced"` \| `"quality"` \| `"maximum"` | `"balanced"` | 处理档次 |
+| `strength` | number (0-100) | `50` | 降噪强度 |
+| `detailPreservation` | number (0-100) | `50` | 保留多少细节；数值越高保留的纹理越多 |
+| `colorNoise` | number (0-100) | `30` | 彩色噪点抑制强度 |
+| `format` | string | `"original"` | 输出格式：`original`、`png`、`jpeg`、`webp`、`avif`、`jxl` |
+| `quality` | number (1-100) | `90` | 输出编码质量 |
+
+## 红眼消除 {#red-eye-removal}
+
+**工具路由：** `red-eye-removal`
+
+检测人脸关键点，定位眼部区域，并校正红色通道过饱和。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `sensitivity` | number (0-100) | `50` | 红色像素检测阈值 |
+| `strength` | number (0-100) | `70` | 校正强度 |
+| `format` | string | - | 输出格式覆盖（可选） |
+| `quality` | number (1-100) | `90` | 输出质量 |
+
+## 照片修复 {#photo-restoration}
+
+**工具路由：** `restore-photo`
+
+针对老旧或受损照片的多步流水线：划痕/撕裂检测与修复、人脸增强、降噪，以及可选的上色。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `scratchRemoval` | boolean | `true` | 检测并修复划痕、撕裂 |
+| `faceEnhancement` | boolean | `true` | 应用人脸增强处理 |
+| `fidelity` | number (0-1) | `0.7` | 人脸增强强度（越高越保守） |
+| `denoise` | boolean | `true` | 应用降噪处理 |
+| `denoiseStrength` | number (0-100) | `25` | 降噪强度 |
+| `colorize` | boolean | `false` | 修复后进行上色 |
+| `colorizeStrength` | number (0-100) | `85` | 上色强度 |
+
+## 护照照片 {#passport-photo}
+
+**工具路由：** `passport-photo`  
+**模型：** MediaPipe 人脸关键点 + BiRefNet 抠图
+
+两阶段工作流：分析（检测人脸 + 移除背景），然后生成（裁剪、缩放、平铺）。支持横跨 6 个地区的 37+ 个国家/地区。
+
+### 阶段 1：分析 {#phase-1-analyze}
+
+`POST /api/v1/tools/image/passport-photo/analyze`
+
+接受一个图像文件（multipart）。返回人脸关键点数据、一张 base64 预览图，以及图像尺寸。
+
+### 阶段 2：生成 {#phase-2-generate}
+
+`POST /api/v1/tools/image/passport-photo/generate`
+
+接受一个 JSON 主体，其中包含阶段 1 的结果加上生成设置：
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `jobId` | string | （必填） | 来自阶段 1 的作业 ID |
+| `filename` | string | （必填） | 来自阶段 1 的原始文件名 |
+| `countryCode` | string | （必填） | ISO 国家/地区代码（例如 `US`、`GB`、`IN`） |
+| `documentType` | string | `"passport"` | 证件类型 |
+| `bgColor` | string | `"#FFFFFF"` | 背景颜色十六进制 |
+| `printLayout` | string | `"none"` | 打印排版：`none`、`4x6`、`a4`、`letter` |
+| `maxFileSizeKb` | number | `0` | 最大文件大小（KB）（0 = 无限制） |
+| `dpi` | number (72-1200) | `300` | 输出 DPI |
+| `customWidthMm` | number | - | 自定义宽度（毫米）（覆盖国家/地区规格） |
+| `customHeightMm` | number | - | 自定义高度（毫米）（覆盖国家/地区规格） |
+| `zoom` | number (0.5-3) | `1` | 缩放系数 |
+| `adjustX` | number | `0` | 水平位置调整 |
+| `adjustY` | number | `0` | 垂直位置调整 |
+| `landmarks` | object | （必填） | 来自阶段 1 的关键点 |
+| `imageWidth` | number | （必填） | 来自阶段 1 的图像宽度 |
+| `imageHeight` | number | （必填） | 来自阶段 1 的图像高度 |
+
+## 对象擦除（图像修复） {#object-erasing-inpainting}
+
+**工具路由：** `erase-object`  
+**模型：** 通过 ONNX Runtime 运行的 LaMa
+
+蒙版作为**第二个文件部分**发送（字段名 `mask`），而不是作为 base64。蒙版中的白色像素表示要擦除的区域。`format` 和 `quality` 设置作为顶层表单字段发送。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `file` | file | （必填） | 源图像（multipart） |
+| `mask` | file | （必填） | 蒙版图像（multipart，字段名 `mask`，白色 = 擦除） |
+| `format` | string | `"auto"` | 输出格式：`auto`、`png`、`jpg`、`jpeg`、`webp`、`tiff`、`gif`、`avif`、`heic`、`heif`、`jxl` |
+| `quality` | integer (1-100) | `95` | 输出质量 |
+
+当有 NVIDIA GPU 可用时启用 CUDA 加速。
+
+## AI 画布扩展 {#ai-canvas-expand}
+
+**工具路由：** `ai-canvas-expand`  
+**模型：** 基于 LaMa 的外扩
+
+向任意方向扩展图像画布，并用与现有图像相匹配的 AI 生成内容填充新增区域。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `extendTop` | integer | `0` | 顶部扩展的像素数 |
+| `extendRight` | integer | `0` | 右侧扩展的像素数 |
+| `extendBottom` | integer | `0` | 底部扩展的像素数 |
+| `extendLeft` | integer | `0` | 左侧扩展的像素数 |
+| `tier` | `"fast"` \| `"balanced"` \| `"high"` | `"balanced"` | 质量档次 |
+| `format` | string | `"auto"` | 输出格式：`auto`、`png`、`jpg`、`jpeg`、`webp`、`tiff`、`gif`、`avif`、`heic`、`heif`、`jxl` |
+| `quality` | integer (1-100) | `95` | 输出质量 |
+
+至少有一个扩展方向必须大于 0。
+
+## 智能裁剪 {#smart-crop}
+
+**工具路由：** `smart-crop`  
+**模型：** MediaPipe 人脸检测（仅人脸模式）
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `mode` | string | `"subject"` | 裁剪策略：`subject`、`face`、`trim` |
+| `strategy` | `"attention"` \| `"entropy"` | `"attention"` | 主体模式的策略 |
+| `width` | integer | - | 输出宽度 |
+| `height` | integer | - | 输出高度 |
+| `padding` | integer (0-50) | `0` | 主体周围的内边距百分比 |
+| `facePreset` | string | `"head-shoulders"` | 当 `mode=face` 时的预设取景 |
+| `sensitivity` | number (0-1) | `0.5` | 人脸检测阈值 |
+| `threshold` | integer (0-255) | `30` | 背景检测阈值（trim 模式） |
+| `padToSquare` | boolean | `false` | 将裁剪结果补齐为正方形 |
+| `padColor` | string | `"#ffffff"` | 正方形补齐的背景颜色 |
+| `targetSize` | integer | - | 补齐输出的目标尺寸（像素） |
+| `quality` | integer (1-100) | - | 输出质量 |
+
+旧版 `mode` 值 `attention` 和 `content` 仍被接受，并分别映射到 `subject` 和 `trim`。
+
+**人脸预设：**
+
+| 预设 | 最适合 |
+|--------|---------|
+| `closeup` | 头像特写 |
+| `head-shoulders` | 个人资料照片 |
+| `upper-body` | LinkedIn / 正式照 |
+| `half-body` | 完整上半身 |
+
+## 音频转写 {#transcribe-audio}
+
+**工具路由：** `transcribe-audio`  
+**模型：** faster-whisper
+
+将语音转换为文本。支持纯文本、SRT 和 VTT 输出格式。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `language` | string | `"auto"` | 语言：`auto`、`en`、`de`、`fr`、`es`、`zh`、`ja`、`ko`、`id`、`th`、`vi` |
+| `outputFormat` | `"txt"` \| `"srt"` \| `"vtt"` | `"txt"` | 输出格式 |
+
+## 自动字幕 {#auto-subtitles}
+
+**工具路由：** `auto-subtitles`  
+**模型：** faster-whisper（从视频中提取音频，然后转写）
+
+从视频的音轨生成字幕文件。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `language` | string | `"auto"` | 语言：`auto`、`en`、`de`、`fr`、`es`、`zh`、`ja`、`ko`、`id`、`th`、`vi` |
+| `format` | `"srt"` \| `"vtt"` | `"srt"` | 输出字幕格式 |
+
+## PNG 透明度修复 {#png-transparency-fixer}
+
+**工具路由：** `transparency-fixer`  
+**模型：** BiRefNet HR-matting（2048x2048 分辨率）
+
+修复"伪透明"PNG，即背景已被移除但残留了毛边、光晕或半透明杂影。使用 BiRefNet 的高分辨率抠图模型生成干净的 alpha 通道，然后应用可配置的去边处理以移除边缘的颜色污染。
+
+**OOM 回退链：** 如果 BiRefNet HR-matting 超出可用内存，工具会自动回退到 `birefnet-general`，然后回退到 `u2net`。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `defringe` | number (0-100) | `30` | 边缘去边强度，用于移除颜色污染 |
+| `outputFormat` | `"png"` \| `"webp"` | `"png"` | 输出图像格式 |
+| `removeWatermark` | boolean | `false` | 应用水印移除预处理（中值滤波） |
+
+```bash
+curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \
+  -H "Authorization: Bearer <token>" \
+  -F "file=@fake-transparent.png" \
+  -F 'settings={"defringe":30,"outputFormat":"png"}'
+```
+
+---
+
+## 具备可选 AI 能力的工具 {#tools-with-optional-ai-capabilities}
+
+以下工具并非 Python 边车工具，但在启用某些选项时会使用 AI 功能。
+
+### 图像增强 {#image-enhancement}
+
+**工具路由：** `image-enhancement`  
+**引擎：** 基于分析（Sharp 直方图与统计）
+
+分析图像并对曝光、对比度、白平衡、饱和度、锐度和噪点应用自动校正。支持特定场景模式。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `mode` | `"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"` | `"auto"` | 用于微调校正的场景模式 |
+| `intensity` | number (0-100) | `50` | 整体校正强度 |
+| `corrections.exposure` | boolean | `true` | 应用曝光校正 |
+| `corrections.contrast` | boolean | `true` | 应用对比度校正 |
+| `corrections.whiteBalance` | boolean | `true` | 应用白平衡校正 |
+| `corrections.saturation` | boolean | `true` | 应用饱和度校正 |
+| `corrections.sharpness` | boolean | `true` | 应用锐度校正 |
+| `corrections.denoise` | boolean | `true` | 应用降噪 |
+| `deepEnhance` | boolean | `false` | 通过 SCUNet 启用 AI 噪点去除（需要 `upscale-enhance` 功能包） |
+
+在 `POST /api/v1/tools/image/image-enhancement/analyze` 处还提供一个额外的分析端点，它返回检测到的校正而不实际应用它们。
+
+### 内容感知缩放（接缝裁剪） {#content-aware-resize-seam-carving}
+
+**工具路由：** `content-aware-resize`  
+**引擎：** Go `caire` 二进制文件（非 Python，无 GPU 收益）
+
+通过移除低能量接缝智能地缩放图像，保留重要内容。
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `width` | number | - | 目标宽度 |
+| `height` | number | - | 目标高度 |
+| `protectFaces` | boolean | `false` | 保护检测到的人脸区域（需要 `face-detection` 功能包） |
+| `blurRadius` | number (0-20) | `4` | 用于能量计算的预模糊 |
+| `sobelThreshold` | number (1-20) | `2` | 边缘敏感度阈值 |
+| `square` | boolean | `false` | 强制正方形输出 |
@@ -0,0 +1,211 @@
+---
+description: "图像引擎操作参考。所有基于 Sharp 的图像处理操作及其参数。"
+i18n_source_hash: 42febdf85fa8
+i18n_provenance: human
+i18n_output_hash: 76ddc27cca10
+---
+
+# 图像引擎 {#image-engine}
+
+`@snapotter/image-engine` 包处理所有非 AI 图像操作。它封装了 [Sharp](https://sharp.pixelplumbing.com/)，完全在进程内运行，没有外部依赖。
+
+## 操作 {#operations}
+
+### resize {#resize}
+
+将图像缩放到特定尺寸或按百分比缩放。
+
+| 参数 | 类型 | 描述 |
+|---|---|---|
+| `width` | number | 目标宽度（像素） |
+| `height` | number | 目标高度（像素） |
+| `fit` | string | `cover`、`contain`、`fill`、`inside` 或 `outside` |
+| `withoutEnlargement` | boolean | 若为 true，不会放大较小的图像 |
+| `percentage` | number | 按百分比缩放，而非绝对尺寸 |
+
+你可以设置 `width`、`height` 或两者。如果只设置其中一个，另一个会被计算以保持宽高比。
+
+### crop {#crop}
+
+从图像中裁出一个矩形区域。
+
+| 参数 | 类型 | 描述 |
+|---|---|---|
+| `left` | number | 距左边缘的 X 偏移 |
+| `top` | number | 距顶边缘的 Y 偏移 |
+| `width` | number | 裁剪区域宽度 |
+| `height` | number | 裁剪区域高度 |
+| `unit` | string | `px`（默认）或 `percent` |
+
+### rotate {#rotate}
+
+将图像旋转给定角度。
+
+| 参数 | 类型 | 描述 |
+|---|---|---|
+| `angle` | number | 旋转角度（度，0-360） |
+| `background` | string | 暴露区域的填充颜色（默认：`#000000`）。仅适用于非 90 度角。 |
+
+### flip {#flip}
+
+水平、垂直或双向镜像图像。至少一项必须为 true。
+
+| 参数 | 类型 | 描述 |
+|---|---|---|
+| `horizontal` | boolean | 左右镜像 |
+| `vertical` | boolean | 上下镜像 |
+
+### convert {#convert}
+
+更改图像格式。
+
+| 参数 | 类型 | 描述 |
+|---|---|---|
+| `format` | string | 目标格式：`jpg`、`png`、`webp`、`avif`、`tiff`、`gif`、`jxl`、`heic`、`heif`、`bmp`、`ico`、`jp2`、`qoi` |
+| `quality` | number | 压缩质量（1-100，适用于有损格式） |
+
+前七种格式（`jpg` 至 `jxl`）由 Sharp 在进程内编码。其余格式在 API 层使用外部编码器：`heic`/`heif` 通过 heif-enc，`bmp`/`ico` 通过 ImageMagick，`jp2` 通过 opj_compress，`qoi` 通过内联 TypeScript 编解码器。
+
+### compress {#compress}
+
+在保持相同格式的前提下减小文件大小。
+
+| 参数 | 类型 | 描述 |
+|---|---|---|
+| `quality` | number | 目标质量（1-100） |
+| `targetSizeBytes` | number | 可选的目标文件大小（字节） |
+| `format` | string | 可选的格式覆盖 |
+
+### strip-metadata {#strip-metadata}
+
+从图像中移除 EXIF、IPTC、XMP 和 ICC 元数据。不带参数（或 `stripAll: true`）时移除所有内容。传入单独的标志以进行选择性移除。
+
+| 参数 | 类型 | 描述 |
+|---|---|---|
+| `stripAll` | boolean | 移除所有元数据（未设置任何标志时的默认行为） |
+| `stripExif` | boolean | 移除 EXIF 数据（若未单独设置 `stripGps`，则包含 GPS） |
+| `stripGps` | boolean | 移除 GPS 位置数据 |
+| `stripIcc` | boolean | 移除 ICC 色彩配置文件 |
+| `stripXmp` | boolean | 移除 XMP 元数据 |
+
+### 色彩调整 {#color-adjustments}
+
+这些操作修改图像的色彩属性。每个操作接受一个数值。
+
+| 操作 | 参数 | 范围 | 描述 |
+|---|---|---|---|
+| `brightness` | `value` | -100 到 100 | 调整亮度 |
+| `contrast` | `value` | -100 到 100 | 调整对比度 |
+| `saturation` | `value` | -100 到 100 | 调整色彩饱和度 |
+
+### 色彩滤镜 {#color-filters}
+
+这些应用固定的色彩变换。它们不接受参数。
+
+| 操作 | 描述 |
+|---|---|
+| `grayscale` | 转换为灰度 |
+| `sepia` | 应用棕褐色调 |
+| `invert` | 反转所有颜色 |
+
+### 色彩通道 {#color-channels}
+
+调整单独的 RGB 色彩通道。数值为倍率，100 = 无变化。
+
+| 参数 | 类型 | 描述 |
+|---|---|---|
+| `red` | number | 红色通道倍率（0 到 200，100 = 不变） |
+| `green` | number | 绿色通道倍率（0 到 200，100 = 不变） |
+| `blue` | number | 蓝色通道倍率（0 到 200，100 = 不变） |
+
+### sharpen {#sharpen}
+
+由单个数值控制的简单锐化。
+
+| 参数 | 类型 | 描述 |
+|---|---|---|
+| `value` | number | 锐化强度（0 到 100）。映射到 0.5-10 的高斯 sigma。 |
+
+### sharpen-advanced {#sharpen-advanced}
+
+高级锐化，具有三种可选方法和一个可选的降噪预处理。
+
+| 参数 | 类型 | 描述 |
+|---|---|---|
+| `method` | string | `adaptive`、`unsharp-mask` 或 `high-pass` |
+| `sigma` | number | 高斯模糊半径，0.5-10（自适应） |
+| `m1` | number | 平坦区域锐化，0-10（自适应） |
+| `m2` | number | 纹理区域锐化，0-20（自适应） |
+| `x1` | number | 平坦/锯齿阈值，0-10（自适应） |
+| `y2` | number | 最大提亮（光晕钳制），0-50（自适应） |
+| `y3` | number | 最大压暗（光晕钳制），0-50（自适应） |
+| `amount` | number | 强度百分比，0-500（USM 锐化） |
+| `radius` | number | 模糊半径，0.1-5.0（USM 锐化） |
+| `threshold` | number | 最小边缘亮度，0-255（USM 锐化） |
+| `strength` | number | 混合强度，0-100（高通） |
+| `kernelSize` | number | `3` 或 `5`，对应 3x3 / 5x5 卷积核（高通） |
+| `denoise` | string | 降噪预处理：`off`、`light`、`medium` 或 `strong` |
+
+参数因方法而异。只提供与所选方法相关的参数。
+
+### color-blindness {#color-blindness}
+
+使用 3x3 色彩重组矩阵模拟色觉缺陷。
+
+| 参数 | 类型 | 描述 |
+|---|---|---|
+| `type` | string | 取值之一：`protanopia`、`deuteranopia`、`tritanopia`、`protanomaly`、`deuteranomaly`、`tritanomaly`、`achromatopsia`、`blueConeMonochromacy` |
+
+### edit-metadata {#edit-metadata}
+
+写入或移除单个 EXIF/IPTC 元数据字段，而无需移除整个数据块。
+
+| 参数 | 类型 | 描述 |
+|---|---|---|
+| `artist` | string | EXIF Artist 标签 |
+| `copyright` | string | EXIF Copyright 标签 |
+| `imageDescription` | string | EXIF ImageDescription 标签 |
+| `software` | string | EXIF Software 标签 |
+| `dateTime` | string | EXIF DateTime 标签 |
+| `dateTimeOriginal` | string | EXIF DateTimeOriginal 标签 |
+| `clearGps` | boolean | 移除所有 GPS 标签 |
+| `fieldsToRemove` | string[] | 要删除的 EXIF 字段名列表 |
+
+所有参数均为可选。`fieldsToRemove` 中列出的字段会从现有 EXIF 块中删除。通过命名参数设置的字段会被写入（或覆盖）。像 MakerNote 这类二进制/不安全的键会被静默忽略。
+
+## 格式检测 {#format-detection}
+
+引擎会根据文件头自动检测输入格式，而不仅仅依赖文件扩展名。这意味着一个实际上是 PNG 的 `.jpg` 文件也能被正确处理。检测采用多层方法：先看魔数字节，再以文件扩展名作为回退。
+
+SnapOtter 支持 **55+ 种输入格式**和 **13 种输出格式**，包括来自 20 多个品牌的 23 种相机 RAW 格式、专业格式（PSD、EPS、OpenEXR、HDR）、现代编解码格式（JPEG XL、AVIF、HEIC、QOI、JPEG 2000）以及科学/游戏格式（FITS、DDS）。解码在可能的情况下由 Sharp 原生处理，并自动回退到 ImageMagick、LibRaw 和专用 CLI 解码器。
+
+完整列表请参见[支持的格式](/zh-CN/guide/supported-formats)页面。
+
+## 元数据提取 {#metadata-extraction}
+
+`info` 工具返回图像元数据。完整字段参考请参见[图像信息](/zh-CN/tools/image/info)。
+
+```json
+{
+  "filename": "photo.jpg",
+  "fileSize": 2450000,
+  "width": 4032,
+  "height": 3024,
+  "format": "jpeg",
+  "channels": 3,
+  "hasAlpha": false,
+  "colorSpace": "srgb",
+  "density": 72,
+  "isProgressive": false,
+  "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 }
+  ]
+}
+```
@@ -0,0 +1,702 @@
+---
+description: "完整的 REST API 参考。工具端点、批处理、流水线、文件库、身份验证、团队以及管理操作。"
+i18n_source_hash: 8646977f7cc9
+i18n_provenance: machine
+i18n_output_hash: c43973438a42
+---
+
+# REST API 参考 {#rest-api-reference}
+
+带请求/响应示例的交互式 API 文档见 [http://localhost:1349/api/docs](http://localhost:1349/api/docs)。
+
+机器可读规范：
+- `/api/v1/openapi.yaml` - OpenAPI 3.1 规范
+- `/llms.txt` - 面向 LLM 的摘要
+- `/llms-full.txt` - 完整的面向 LLM 的文档
+
+## 身份验证 {#authentication}
+
+除非 `AUTH_ENABLED=false`，否则所有端点都需要身份验证。
+
+### 会话令牌 {#session-token}
+
+```bash
+# Login
+curl -X POST http://localhost:1349/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin"}'
+# Returns: {"token":"<session-token>"}
+
+# Use token
+curl http://localhost:1349/api/v1/tools/image/resize \
+  -H "Authorization: Bearer <session-token>"
+```
+
+会话在 7 天后过期（可通过 `SESSION_DURATION_HOURS` 配置）。
+
+### API 密钥 {#api-keys}
+
+```bash
+# Create a key (returns key once - store it)
+curl -X POST http://localhost:1349/api/v1/api-keys \
+  -H "Authorization: Bearer <session-token>" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"my-script"}'
+# Returns: {"key":"si_<96 hex chars>","id":"...","name":"my-script"}
+
+# Use the key
+curl http://localhost:1349/api/v1/tools/image/resize \
+  -H "Authorization: Bearer si_<your-key>"
+```
+
+密钥以 `si_` 为前缀，并以 scrypt 哈希形式存储，原始密钥只显示一次，之后再也无法取回。
+
+### 身份验证端点 {#auth-endpoints}
+
+| 方法 | 路径 | 访问权限 | 说明 |
+|--------|------|--------|-------------|
+| `POST` | `/api/auth/login` | 公开 | 登录，获取会话令牌 |
+| `POST` | `/api/auth/logout` | 需身份验证 | 销毁当前会话 |
+| `GET` | `/api/auth/session` | 需身份验证 | 校验当前会话 |
+| `POST` | `/api/auth/change-password` | 需身份验证 | 修改自己的密码（会使所有其他会话和 API 密钥失效） |
+| `GET` | `/api/auth/users` | 管理员 | 列出所有用户 |
+| `POST` | `/api/auth/register` | 管理员 | 创建新用户 |
+| `PUT` | `/api/auth/users/:id` | 管理员 | 更新用户角色或团队 |
+| `POST` | `/api/auth/users/:id/reset-password` | 管理员 | 重置用户密码 |
+| `DELETE` | `/api/auth/users/:id` | 管理员 | 删除用户 |
+| `GET` | `/api/v1/config/auth` | 公开 | 检查是否启用了身份验证（`{ authEnabled: bool }`） |
+| `POST` | `/api/auth/mfa/enroll` | 需身份验证 | 开始 TOTP MFA 注册。需要企业版 `mfa` 功能 |
+| `POST` | `/api/auth/mfa/verify` | 需身份验证 | 用 TOTP 验证码确认 MFA 注册 |
+| `POST` | `/api/auth/mfa/complete` | 公开 | 完成待处理的 MFA 登录挑战 |
+| `POST` | `/api/auth/mfa/disable` | 需身份验证 | 为当前用户禁用 MFA |
+| `POST` | `/api/auth/users/:id/mfa/reset` | 管理员（`users:manage`） | 为用户重置 MFA |
+| `GET` | `/api/auth/oidc/login` | 公开 | 启用 OIDC 时开始 OIDC 登录 |
+| `GET` | `/api/auth/oidc/callback` | 公开 | OIDC 授权回调 |
+| `GET` | `/api/auth/saml/metadata` | 公开 | 启用 SAML 时提供 SAML SP 元数据 XML |
+| `GET` | `/api/auth/saml/login` | 公开 | 开始 SAML 登录 |
+| `POST` | `/api/auth/saml/callback` | 公开 | SAML 断言消费者服务 |
+
+当用户启用了 MFA 时，`POST /api/auth/login` 会返回 `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` 而不是会话令牌。将该 `mfaToken` 连同 TOTP 或恢复码一起发送到 `/api/auth/mfa/complete`。
+
+### 权限 {#permissions}
+
+| 权限 | 管理员 | 用户 |
+|-----------|:-----:|:----:|
+| 使用工具 | ✓ | ✓ |
+| 自己的文件/流水线/API 密钥 | ✓ | ✓ |
+| 查看所有用户的文件/流水线/密钥 | ✓ | - |
+| 写入设置 | ✓ | - |
+| 管理用户与团队 | ✓ | - |
+| 管理品牌设置 | ✓ | - |
+
+## 健康检查 {#health-check}
+
+| 方法 | 路径 | 访问权限 | 说明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/health` | 公开 | 基础健康检查。数据库可用时返回 `{"status":"healthy","version":"..."}` 与 200，数据库不可达时返回 `{"status":"unhealthy"}` 与 503。 |
+| `GET` | `/api/v1/readyz` | 公开 | 就绪探针。检查 PostgreSQL、Redis、磁盘空间，以及在配置了 S3 时检查 S3。当实例不应接收流量时返回 503。 |
+| `GET` | `/api/v1/admin/health` | 管理员（`system:health`） | 详细诊断信息，包括运行时长、存储模式、数据库状态、队列状态以及 GPU 可用性。 |
+
+## 使用工具 {#using-tools}
+
+每个工具都遵循相同的模式：
+
+```bash
+# Single file
+curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId> \
+  -H "Authorization: Bearer <token>" \
+  -F "file=@input.jpg" \
+  -F 'settings={"width":800,"height":600}'
+
+# Batch (returns ZIP)
+curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId>/batch \
+  -H "Authorization: Bearer <token>" \
+  -F "files=@a.jpg" \
+  -F "files=@b.jpg" \
+  -F 'settings={...}'
+```
+
+`<section>` 是 `image`、`video`、`audio`、`pdf` 或 `files` 之一。
+
+- 上传为 `multipart/form-data`。
+- `settings` 是一个包含工具专属选项的 JSON 字符串。
+- `clientJobId` 是一个可选的表单字段，用于调用方提供的进度关联标识。
+- `fileId` 是一个可选的表单字段，引用现有文件库项目。存在时，处理输出会保存为一个新版本，且响应中会包含 `savedFileId`。
+- **快速工具** 通常返回 200 JSON：`{"jobId":"...","downloadUrl":"/api/v1/download/<jobId>/<filename>","originalSize":1234,"processedSize":567}`。从 `downloadUrl` 获取处理后的文件。
+- **任何排队工具** 若为长时间运行或超过同步等待窗口，都可能返回 202 JSON：`{"jobId":"...","async":true}`。连接 SSE 获取进度，完成后再下载（参见 [进度跟踪](#progress-tracking)）。
+- **批处理** 路由会直接以流式返回一个 ZIP 归档（带 `X-Job-Id` 头），适用于在通用批处理注册表中注册的工具。
+
+## 工具参考 {#tools-reference}
+
+### 转换预设 {#conversion-presets}
+
+共享目录包含 83 个专用的转换预设端点，例如 `jpg-to-png`、`mov-to-mp4`、`m4a-to-mp3`、`pdf-to-jpg` 和 `excel-to-csv`。预设是一等的工具路由：
+
+`POST /api/v1/tools/<section>/<presetId>`
+
+每个预设锁定输出格式，并委托给某个基础工具，例如 `convert`、`convert-video`、`extract-audio`、`convert-audio`、`image-to-pdf`、`pdf-to-image`、`svg-to-raster` 或 `convert-spreadsheet`。完整的路由表和可选设置见 [转换预设](/zh-CN/tools/conversion-presets)。
+
+### 基础工具 {#essentials}
+
+| 工具 ID | 名称 | 主要设置 |
+|---------|------|-------------|
+| `resize` | 调整尺寸 | `width`、`height`、`fit`（cover/contain/fill/inside/outside）、`percentage`、`withoutEnlargement`，另加 23 个社交媒体预设 |
+| `crop` | 裁剪 | `left`、`top`、`width`、`height`、`unit`（px/percent） |
+| `rotate` | 旋转与翻转 | `angle`、`horizontal`（bool）、`vertical`（bool） |
+| `convert` | 转换 | `format`（jpg/png/webp/avif/tiff/gif/heic/heif）、`quality` |
+| `compress` | 压缩 | `mode`（quality/targetSize）、`quality`（1–100）、`targetSizeKb` |
+
+### 优化 {#optimization}
+
+| 工具 ID | 名称 | 主要设置 |
+|---------|------|-------------|
+| `optimize-for-web` | 网页优化 | `format`（webp/jpeg/avif/png）、`quality`、`maxWidth`、`maxHeight`、`progressive`、`stripMetadata` |
+| `strip-metadata` | 去除元数据 | - |
+| `edit-metadata` | 编辑元数据 | `title`、`description`、`author`、`copyright`、`keywords`、`gps`（lat/lon）、`dateTime` |
+| `bulk-rename` | 批量重命名 | `pattern`（支持 `{n}`、`{date}`、`{original}`）、`startIndex`、`padding` |
+| `image-to-pdf` | 图片转 PDF | `pageSize`（A4/Letter/...）、`orientation`、`margin`、`targetSize`（{value, unit}） |
+| `favicon` | 网站图标生成器 | `padding`、`backgroundColor`、`borderRadius` - 生成所有标准尺寸 |
+
+### 调整 {#adjustments}
+
+| 工具 ID | 名称 | 主要设置 |
+|---------|------|-------------|
+| `adjust-colors` | 调整颜色 | `brightness`、`contrast`、`exposure`、`saturation`、`temperature`、`tint`、`hue`、`sharpness`、`red`、`green`、`blue`、`effect`（none/grayscale/sepia/invert） |
+| `sharpening` | 锐化 | `method`（adaptive/unsharp-mask/high-pass）、`sigma`、`m1`、`m2`、`x1`、`y2`、`y3`、`amount`、`radius`、`threshold`、`strength`、`kernelSize`（3/5）、`denoise`（off/light/medium/strong） |
+| `replace-color` | 替换颜色 | `sourceColor`、`targetColor`（替换色）、`makeTransparent`、`tolerance` |
+| `color-blindness` | 色盲模拟 | `simulationType`（protanopia/deuteranopia/tritanopia/protanomaly/deuteranomaly/tritanomaly/achromatopsia/blueConeMonochromacy，默认 "deuteranomaly"） |
+| `duotone` | 双色调 | `shadow`（hex）、`highlight`（hex）、`intensity`（0-100） |
+| `pixelate` | 像素化 | `blockSize`（2-128）、`region`（{left, top, width, height}，用于局部像素化） |
+| `vignette` | 暗角 | `strength`（0.1-1）、`color`（hex）、`radius`、`softness`、`roundness`、`centerX`、`centerY` |
+
+### AI 工具 {#ai-tools}
+
+所有 AI 工具都在你自己的硬件上运行：默认使用 CPU，或在有受支持的 NVIDIA GPU 时使用 NVIDIA CUDA。目前不支持通过 VA-API、Quick Sync 或 OpenCL 使用 Intel/AMD 核显进行 AI 推理加速。无需联网。
+
+| 工具 ID | 名称 | AI 模型 | 主要设置 |
+|---------|------|---------|-------------|
+| `remove-background` | 移除背景 | rembg (BiRefNet / U2-Net) | `model`、`backgroundType`（transparent/color/gradient/blur/image）、`backgroundColor`、`gradientColor1`、`gradientColor2`、`gradientAngle`、`blurEnabled`、`blurIntensity`、`shadowEnabled`、`shadowOpacity` |
+| `upscale` | 图片放大 | RealESRGAN | `scale`（2/4）、`model`、`faceEnhance`、`denoise`、`format`、`quality` |
+| `erase-object` | 对象擦除 | LaMa (ONNX) | 蒙版作为第二个文件部分发送（字段名 `mask`）、`format`、`quality` |
+| `ocr` | OCR / 文本提取 | PaddleOCR / Tesseract | `quality`（fast/balanced/best）、`language`、`enhance` |
+| `blur-faces` | 人脸 / PII 模糊 | MediaPipe | `blurRadius`、`sensitivity` |
+| `smart-crop` | 智能裁剪 | MediaPipe + Sharp | `mode`（subject/face/trim）、`strategy`（attention/entropy）、`width`、`height`、`padding`、`facePreset`（closeup/head-shoulders/upper-body/half-body）、`sensitivity`、`threshold`、`padToSquare`、`padColor`、`targetSize`、`quality` |
+| `image-enhancement` | 图片增强 | 基于分析 | `mode`（auto/exposure/contrast/color/sharpness）、`strength` |
+| `enhance-faces` | 人脸增强 | GFPGAN / CodeFormer | `model`（gfpgan/codeformer）、`strength`、`sensitivity`、`centerFace` |
+| `colorize` | AI 上色 | DDColor | `intensity`、`model` |
+| `noise-removal` | 降噪 | 分级降噪 | `tier`（quick/balanced/quality/maximum）、`strength`、`detailPreservation`、`colorNoise`、`format`、`quality` |
+| `red-eye-removal` | 去红眼 | 人脸关键点 + 颜色分析 | `sensitivity`、`strength` |
+| `restore-photo` | 照片修复 | 多步流水线 | `mode`（auto/light/heavy）、`scratchRemoval`、`faceEnhancement`、`fidelity`、`denoise`、`denoiseStrength`、`colorize` |
+| `passport-photo` | 证件照 | MediaPipe 关键点 | 两阶段流程。分析使用 multipart `file`；生成使用带 `countryCode`、`bgColor`、`printLayout`（none/4x6/a4）、关键点、图片尺寸的 JSON |
+| `content-aware-resize` | 内容感知调整尺寸 | 接缝裁剪 (caire) | `width`、`height`、`protectFaces`、`blurRadius`、`sobelThreshold`、`square` |
+| `transparency-fixer` | PNG 透明度修复 | BiRefNet HR-matting | `defringe`（0-100）、`outputFormat`（png/webp） |
+| `background-replace` | 背景替换 | rembg (BiRefNet) | `backgroundType`（color/gradient）、`color`（hex）、`gradientColor1`、`gradientColor2`、`gradientAngle`、`feather`（0-20）、`format`（png/webp） |
+| `blur-background` | 背景模糊 | rembg (BiRefNet) | `intensity`（1-100）、`feather`（0-20）、`format`（png/webp） |
+| `ai-canvas-expand` | AI 画布扩展 | LaMa (outpainting) | `extendTop`、`extendRight`、`extendBottom`、`extendLeft`（px）、`tier`（fast/balanced/high）、`format`、`quality` |
+
+### 水印与叠加 {#watermark-overlay}
+
+| 工具 ID | 名称 | 主要设置 |
+|---------|------|-------------|
+| `watermark-text` | 文字水印 | `text`、`font`、`fontSize`、`color`、`opacity`、`position`、`rotation`、`tile` |
+| `watermark-image` | 图片水印 | `opacity`、`position`、`scale` - 第二个文件是水印 |
+| `text-overlay` | 文字叠加 | `text`、`font`、`fontSize`、`color`、`x`、`y`、`background`、`padding`、`borderRadius` |
+| `compose` | 图片合成 | `x`、`y`、`opacity`、`blend` - 第二个文件叠在上层 |
+| `meme-generator` | 表情包生成器 | `templateId`、`textLayout`（top-bottom/top-only/bottom-only/center/side-by-side）、`textBoxes`（[{id, text}]）、`fontFamily`（anton/arial-black/comic-sans/montserrat/bebas-neue/permanent-marker/roboto）、`fontSize`、`textColor`、`strokeColor`、`textAlign`、`allCaps`。支持模板模式（带 `templateId` 的 JSON 请求体）或自定义图片模式（带文件的 multipart）。 |
+
+### 实用工具 {#utilities}
+
+| 工具 ID | 名称 | 主要设置 |
+|---------|------|-------------|
+| `info` | 图片信息 | -（返回宽度、高度、格式、大小、通道数、hasAlpha、DPI、EXIF） |
+| `compare` | 图片对比 | `mode`（side-by-side/overlay/diff）、`diffThreshold` - 第二个文件是对比目标 |
+| `find-duplicates` | 查找重复 | `threshold`（感知哈希距离，默认 8）- 多文件 |
+| `color-palette` | 调色板 | `count`（主色数量）、`format`（hex/rgb） |
+| `qr-generate` | 二维码生成器 | `data`、`size`、`margin`、`colorDark`、`colorLight`、`errorCorrectionLevel`、`dotStyle`、`cornerStyle`、`logo`（可选文件） |
+| `barcode-read` | 条形码识别 | -（自动识别 QR、EAN、Code128、DataMatrix 等） |
+| `image-to-base64` | 图片转 Base64 | `format`（data-uri/plain）、`mimeType` |
+| `html-to-image` | HTML 转图片 | `url`、`format`（png/jpg/webp）、`quality`、`fullPage`、`devicePreset`（desktop/tablet/mobile/custom）、`viewportWidth`、`viewportHeight` |
+| `histogram` | 直方图 | `scale`（linear/log）- 返回 RGB 直方图图表 + 各通道统计 |
+| `lqip-placeholder` | LQIP 占位图 | `width`（4-64）、`blur`、`strategy`（blur/pixelate/solid）、`format`（webp/png/jpeg）、`quality` |
+| `barcode-generate` | 条形码生成器 | `text`、`type`（code128/ean13/upca/code39/itf14/datamatrix）、`scale`（1-8）、`includeText`（bool）。JSON 请求体，无需上传文件。 |
+
+### 布局与合成 {#layout-composition}
+
+| 工具 ID | 名称 | 主要设置 |
+|---------|------|-------------|
+| `collage` | 拼贴 / 网格 | `template`（25+ 种布局）、`gap`、`backgroundColor`、`borderRadius` - 多文件 |
+| `stitch` | 拼接 / 合并 | `direction`（horizontal/vertical/grid）、`gap`、`backgroundColor`、`alignment` - 多文件 |
+| `split` | 图片分割 | `mode`（grid/rows/cols）、`rows`、`cols`、`tileWidth`、`tileHeight` |
+| `border` | 边框与相框 | `width`、`color`、`style`（solid/gradient/pattern）、`borderRadius`、`padding`、`shadow` |
+| `beautify` | 美化截图 | `backgroundType`（solid/linear-gradient/radial-gradient/image/transparent）、`gradientStops`、`padding`、`borderRadius`、`shadowPreset`、`frame`（none/macos-light/macos-dark/windows-light/windows-dark/browser-light/browser-dark/iphone/macbook/ipad/...）、`socialPreset`（none/twitter/linkedin/instagram-square/instagram-story/facebook/producthunt）、`watermarkText`、`outputFormat` |
+| `circle-crop` | 圆形裁剪 | `zoom`（1-5）、`offsetX`、`offsetY`、`borderWidth`、`borderColor`、`background`（transparent/hex）、`outputSize` |
+| `image-pad` | 图片留白 | `target`（16:9/9:16/1:1/4:3/3:4/custom）、`ratioW`、`ratioH`、`background`（color/transparent/blur）、`color`（hex）、`padding`（0-50%） |
+| `sprite-sheet` | 精灵图 | `columns`（1-16）、`padding`、`background`（hex）、`format`（png/webp/jpeg）、`quality` - 多文件（2-64 张图片） |
+
+### 格式与转换 {#format-conversion}
+
+| 工具 ID | 名称 | 主要设置 |
+|---------|------|-------------|
+| `svg-to-raster` | SVG 转位图 | `format`（png/jpeg/webp/avif/tiff/gif/heif）、`width`、`height`、`scale`、`dpi`、`background` |
+| `vectorize` | 图片转 SVG | `colorMode`（bw/color）、`threshold`、`colorPrecision`、`filterSpeckle`、`pathMode`（none/polygon/spline） |
+| `gif-tools` | GIF 工具 | `action`（resize/optimize/reverse/speed/extract-frames/rotate/add-text）、动作专属参数 |
+| `gif-webp` | GIF/WebP 转换器 | `quality`（1-100）、`lossless`（bool）、`resizePercent`（10-100） |
+
+### 视频工具 {#video-tools}
+
+| 工具 ID | 名称 | 主要设置 |
+|---------|------|-------------|
+| `convert-video` | 转换视频 | `format`（mp4/mov/webm/avi/mkv）、`quality`（high/balanced/small） |
+| `compress-video` | 压缩视频 | `quality`（light/balanced/strong）、`resolution`（original/1080p/720p/480p） |
+| `trim-video` | 裁剪视频（时长） | `startS`、`endS`、`precise`（bool，逐帧精确剪切） |
+| `mute-video` | 视频静音 | - |
+| `video-to-gif` | 视频转 GIF | `fps`（1-30）、`width`、`startS`、`durationS`（最长 60 秒） |
+| `resize-video` | 调整视频尺寸 | `width`、`height`、`preset`（custom/2160p/1440p/1080p/720p/480p/360p） |
+| `crop-video` | 裁剪视频（画面） | `width`、`height`、`x`、`y` |
+| `rotate-video` | 旋转视频 | `transform`（cw90/ccw90/180/hflip/vflip） |
+| `change-fps` | 更改帧率 | `fps`（1-120） |
+| `video-color` | 视频调色 | `brightness`、`contrast`、`saturation`、`gamma` |
+| `video-speed` | 视频速度 | `factor`（0.25-4）、`keepPitch`（bool） |
+| `reverse-video` | 倒放视频 | -（最长 5 分钟） |
+| `video-loudnorm` | 音频归一化 | -（EBU R128） |
+| `aspect-pad` | 比例留白 | `target`（16:9/9:16/1:1/4:3/3:4）、`color`（hex） |
+| `blur-pad` | 模糊留白 | `target`（16:9/9:16/1:1/4:3/3:4）、`blur`（2-50） |
+| `watermark-video` | 视频加水印 | `text`、`position`、`fontSize`、`opacity`、`color` |
+| `stabilize-video` | 视频防抖 | `smoothing`（5-60，以帧计） |
+| `gif-to-video` | GIF 转视频 | `format`（mp4/webm/mov） |
+| `video-to-webp` | 视频转 WebP | `fps`、`width`、`quality`、`loop`（bool） |
+| `video-to-frames` | 视频转帧 | `mode`（all/nth/timestamps）、`n`、`timestamps`、`format`（png/jpg） |
+| `merge-videos` | 合并视频 | -（多文件，归一化到第一个视频的分辨率） |
+| `replace-audio` | 替换音频 | -（视频 + 音频文件，两个文件） |
+| `burn-subtitles` | 烧录字幕 | `fontSize`（8-72）- 视频 + 字幕文件 |
+| `embed-subtitles` | 嵌入字幕 | `language`（ISO 639-2/B 代码）- 视频 + 字幕文件 |
+| `extract-subtitles` | 提取字幕 | -（输出 SRT） |
+| `images-to-video` | 图片转视频 | `secondsPerImage`（0.5-10）、`resolution`（1080p/720p/square）、`fps` - 多文件 |
+| `video-metadata` | 清理视频元数据 | - |
+| `auto-subtitles` | 自动字幕（AI） | `language`（auto/en/de/fr/es/zh/ja/ko/id/th/vi）、`format`（srt/vtt） |
+| `extract-audio` | 提取音频 | `format`（mp3/wav/m4a/ogg） |
+
+### 音频工具 {#audio-tools}
+
+| 工具 ID | 名称 | 主要设置 |
+|---------|------|-------------|
+| `convert-audio` | 转换音频 | `format`（mp3/wav/ogg/flac/m4a）、`bitrateKbps`（32-320） |
+| `trim-audio` | 裁剪音频 | `startS`、`endS` |
+| `volume-adjust` | 调整音量 | `gainDb`（-30 至 30） |
+| `normalize-audio` | 音频归一化 | -（EBU R128，-16 LUFS） |
+| `fade-audio` | 音频淡入淡出 | `fadeInS`（0-30）、`fadeOutS`（0-30） |
+| `reverse-audio` | 倒放音频 | - |
+| `audio-speed` | 音频速度 | `factor`（0.25-4） |
+| `pitch-shift` | 音调变换 | `semitones`（-12 至 12） |
+| `audio-channels` | 音频声道 | `mode`（stereo-to-mono/mono-to-stereo/swap） |
+| `silence-removal` | 去除静音 | `thresholdDb`（-80 至 -20）、`minSilenceS`（0.1-5） |
+| `noise-reduction` | 降噪 | `strength`（light/medium/strong） |
+| `merge-audio` | 合并音频 | `format`（mp3/wav/flac/m4a）- 多文件 |
+| `split-audio` | 分割音频 | `mode`（time/parts/silence）、`segmentS`、`parts`、`thresholdDb`、`minSilenceS` |
+| `ringtone-maker` | 铃声制作 | `startS`、`durationS`（1-30） |
+| `waveform-image` | 波形图 | `width`、`height`、`color`（hex） |
+| `audio-metadata` | 音频元数据 | `strip`（bool）、`title`、`artist`、`album` |
+| `transcribe-audio` | 音频转写（AI） | `language`（auto/en/de/fr/es/zh/ja/ko/id/th/vi）、`outputFormat`（txt/srt/vtt） |
+
+### 文档工具 {#document-tools}
+
+| 工具 ID | 名称 | 主要设置 |
+|---------|------|-------------|
+| `merge-pdf` | 合并 PDF | -（多文件，最多 20 个 PDF） |
+| `split-pdf` | 拆分 PDF | `mode`（range/every）、`range`、`everyN`（1-500） |
+| `compress-pdf` | 压缩 PDF | `mode`（quality/targetSize）、`quality`（1-100）、`targetSizeKb` |
+| `rotate-pdf` | 旋转 PDF | `angle`（90/180/270）、`range`（页面范围） |
+| `extract-pages` | 提取页面 | `range`（qpdf 语法，例如 "1-5,8,10-z"） |
+| `remove-pages` | 删除页面 | `pages`（要删除的 qpdf 范围） |
+| `organize-pdf` | 整理 PDF | `order`（qpdf 页面顺序，例如 "3,1,2,5-z"） |
+| `protect-pdf` | 保护 PDF | `userPassword`、`ownerPassword`（AES-256） |
+| `unlock-pdf` | 解锁 PDF | `password` |
+| `repair-pdf` | 修复 PDF | - |
+| `linearize-pdf` | 网页优化 PDF | -（线性化以便快速网页查看） |
+| `grayscale-pdf` | PDF 灰度化 | - |
+| `pdfa-convert` | PDF/A 转换 | -（归档级 PDF/A-2） |
+| `crop-pdf` | 裁剪 PDF | `margin`（0-2000 点） |
+| `nup-pdf` | N-up PDF | `perSheet`（2/3/4/8/9/12/16） |
+| `booklet-pdf` | 小册子 PDF | `perSheet`（2/4/6/8） |
+| `watermark-pdf` | PDF 加水印 | `text`、`position`、`fontSize`、`opacity`、`rotation` |
+| `pdf-page-numbers` | PDF 页码 | `position`（bl/bc/br/tl/tc/tr）、`fontSize` |
+| `flatten-pdf` | 展平 PDF | -（将表单和批注固化） |
+| `redact-pdf` | PDF 涂黑 | `terms`（string[]）、`caseSensitive`（bool） |
+| `sign-pdf` | PDF 签名 | 自定义 multipart 路由，带 PDF `file`、签名文件 `sig0`、`sig1` 和 `placements` JSON 数组 |
+| `pdf-to-text` | PDF 转文本 | - |
+| `pdf-to-word` | PDF 转 Word | - |
+| `pdf-metadata` | PDF 元数据 | `title`、`author`、`subject`、`keywords` |
+| `convert-document` | 转换文档 | `format`（docx/odt/rtf/txt） |
+| `convert-presentation` | 转换演示文稿 | `format`（pptx/odp） |
+| `convert-spreadsheet` | 转换电子表格 | `format`（xlsx/ods/csv） |
+| `excel-to-pdf` | Excel 转 PDF | - |
+| `word-to-pdf` | Word 转 PDF | - |
+| `powerpoint-to-pdf` | PowerPoint 转 PDF | - |
+| `html-to-pdf` | HTML 转 PDF | -（已禁用远程资源） |
+| `markdown-to-docx` | Markdown 转 Word | - |
+| `markdown-to-html` | Markdown 转 HTML | - |
+| `markdown-to-pdf` | Markdown 转 PDF | -（已禁用远程资源） |
+| `epub-convert` | 转换 EPUB | `format`（pdf/docx/html/md） |
+| `to-epub` | 转换为 EPUB | -（接受 .docx、.md、.html、.txt） |
+| `ocr-pdf` | PDF OCR（AI） | `quality`（fast/balanced/best）、`language`（auto/en/de/fr/es/zh/ja/ko）、`pages` |
+| `pdf-to-image` | PDF 转图片 | `pages`（all/range）、`format`、`dpi`、`quality` |
+| `pdf-to-jpg` | PDF 转 JPG | `pages`、`dpi`、`quality`、`colorMode` |
+| `pdf-to-png` | PDF 转 PNG | `pages`、`dpi`、`quality`、`colorMode` |
+| `pdf-to-tiff` | PDF 转 TIFF | `pages`、`dpi`、`quality`、`colorMode` |
+
+### 文件工具 {#file-tools}
+
+| 工具 ID | 名称 | 主要设置 |
+|---------|------|-------------|
+| `chart-maker` | 图表制作 | `kind`（bar/line/pie）、`title`、`width`、`height` |
+| `csv-excel` | CSV 转 Excel | `sheet`（XLSX 输入的工作表编号）- 双向 |
+| `csv-json` | CSV 转 JSON | `pretty`（bool）- 双向 |
+| `json-xml` | JSON 转 XML | `pretty`（bool）- 双向 |
+| `split-csv` | 拆分 CSV | `rowsPerFile`（1-1000000）、`keepHeader`（bool） |
+| `merge-csvs` | 合并 CSV | -（多文件，列匹配） |
+| `yaml-json` | YAML / JSON | -（双向） |
+| `xml-to-csv` | XML 转 CSV | -（自动查找重复元素） |
+| `excel-to-csv` | Excel 转 CSV | 由 `convert-spreadsheet` 支撑的专用转换预设 |
+| `create-zip` | 创建 ZIP | -（多文件，2-50 个文件） |
+| `extract-zip` | 解压 ZIP | -（已做 ZIP 炸弹防护） |
+
+### HTML 转图片 {#html-to-image}
+
+将网页捕获为图片。与其他工具不同，该端点接受 `application/json` 而非 multipart 表单数据（无需上传文件）。
+
+**端点：** `POST /api/v1/tools/image/html-to-image`
+
+**Content-Type：** `application/json`
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `url` | string | （必填） | 要捕获的 URL（仅限 http/https） |
+| `format` | string | `"png"` | 输出格式：`jpg`、`png`、`webp` |
+| `quality` | number | `90` | 质量 1-100（仅 JPG/WebP） |
+| `fullPage` | boolean | `false` | 捕获整个可滚动页面 |
+| `devicePreset` | string | `"desktop"` | `desktop`、`tablet`、`mobile`、`custom` |
+| `viewportWidth` | number | `1280` | 自定义视口宽度 320-3840 |
+| `viewportHeight` | number | `720` | 自定义视口高度 320-2160 |
+
+**示例：**
+
+```bash
+curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://snapotter.com", "format": "png", "devicePreset": "desktop"}'
+```
+
+**响应：**
+
+```json
+{
+  "jobId": "uuid",
+  "downloadUrl": "/api/v1/download/{jobId}/screenshot.png",
+  "originalSize": 0,
+  "processedSize": 54321
+}
+```
+
+### 工具子路由 {#tool-sub-routes}
+
+某些工具在标准的 `POST /api/v1/tools/<section>/<toolId>` 之外还暴露了额外端点：
+
+| 方法 | 路径 | 说明 |
+|--------|------|-------------|
+| `GET` | `/api/v1/tools/popular` | 返回热门工具 ID，当使用数据稀少时回退到精选默认列表 |
+| `POST` | `/api/v1/tools/image/remove-background/effects` | 应用背景效果（color/gradient/blur/shadow）而无需重新运行 AI。使用初次移除时缓存的蒙版。 |
+| `POST` | `/api/v1/tools/image/edit-metadata/inspect` | 从图片读取现有的 EXIF/IPTC/XMP 元数据 |
+| `POST` | `/api/v1/tools/image/strip-metadata/inspect` | 在去除前检查元数据字段 |
+| `POST` | `/api/v1/tools/image/passport-photo/analyze` | 第 1 阶段：AI 人脸检测 + 背景移除。返回人脸关键点和缓存数据。 |
+| `POST` | `/api/v1/tools/image/passport-photo/generate` | 第 2 阶段：使用缓存分析进行裁剪、调整尺寸和平铺。无需重新运行 AI。 |
+| `POST` | `/api/v1/tools/image/gif-tools/info` | 获取 GIF 元数据（帧数、尺寸、时长） |
+| `POST` | `/api/v1/tools/pdf/pdf-to-image/info` | 获取 PDF 元数据（页数、尺寸） |
+| `POST` | `/api/v1/tools/pdf/pdf-to-image/preview` | 生成指定 PDF 页面的预览 |
+| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/info` | 获取专用 JPG 预设的 PDF 元数据 |
+| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/preview` | 生成 JPG 预设的 PDF 页面预览 |
+| `POST` | `/api/v1/tools/pdf/pdf-to-png/info` | 获取专用 PNG 预设的 PDF 元数据 |
+| `POST` | `/api/v1/tools/pdf/pdf-to-png/preview` | 生成 PNG 预设的 PDF 页面预览 |
+| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/info` | 获取专用 TIFF 预设的 PDF 元数据 |
+| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/preview` | 生成 TIFF 预设的 PDF 页面预览 |
+| `POST` | `/api/v1/tools/image/svg-to-raster/batch` | 将多个 SVG 批量转换为位图 |
+| `POST` | `/api/v1/tools/image/image-enhancement/analyze` | 分析图片质量并返回增强建议 |
+| `POST` | `/api/v1/tools/image/optimize-for-web/preview` | 用于实时参数调节的轻量预览。返回带尺寸头的优化图片。 |
+
+## 批处理 {#batch-processing}
+
+将某个支持批处理的通用工具一次性应用到多个文件。返回一个 ZIP 归档。自定义的多文件或多步路由（例如 PDF 签名、PDF OCR 以及 PDF 转图片预设路由）使用它们自己的端点约定，而非通用的 `/batch` 路由。
+
+```bash
+curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \
+  -H "Authorization: Bearer <token>" \
+  -F "files=@a.jpg" \
+  -F "files=@b.jpg" \
+  -F "files=@c.jpg" \
+  -F 'settings={"quality":80}'
+```
+
+并发由 `CONCURRENT_JOBS` 控制（默认：从 CPU 核心数自动检测）。`MAX_BATCH_SIZE` 限制每个批次的文件数量（默认：100；设为 0 表示无限制）。
+
+## 流水线 {#pipelines}
+
+### 执行流水线 {#execute-a-pipeline}
+
+```bash
+# Single file
+curl -X POST http://localhost:1349/api/v1/pipeline/execute \
+  -H "Authorization: Bearer <token>" \
+  -F "file=@input.jpg" \
+  -F 'pipeline={"steps":[
+    {"toolId":"resize","settings":{"width":1200}},
+    {"toolId":"compress","settings":{"quality":80}},
+    {"toolId":"watermark-text","settings":{"text":"© 2025"}}
+  ]}'
+
+# Batch (multiple files → ZIP)
+curl -X POST http://localhost:1349/api/v1/pipeline/batch \
+  -H "Authorization: Bearer <token>" \
+  -F "files=@a.jpg" \
+  -F "files=@b.jpg" \
+  -F 'pipeline={"steps":[{"toolId":"resize","settings":{"width":800}}]}'
+```
+
+每一步的输出是下一步的输入。流水线默认允许 20 步，可通过 `MAX_PIPELINE_STEPS` 配置。设置 `MAX_PIPELINE_STEPS=0` 可移除该限制。
+
+### 保存和管理流水线 {#save-and-manage-pipelines}
+
+| 方法 | 路径 | 说明 |
+|--------|------|-------------|
+| `POST` | `/api/v1/pipeline/save` | 保存一个命名流水线（`name`、`description`、`steps[]`） |
+| `GET` | `/api/v1/pipeline/list` | 列出已保存的流水线（管理员看到全部；用户看到自己的） |
+| `DELETE` | `/api/v1/pipeline/:id` | 删除（所有者或管理员） |
+| `GET` | `/api/v1/pipeline/tools` | 列出可用于流水线步骤的工具 ID |
+
+## 进度跟踪 {#progress-tracking}
+
+长时间运行的作业、排队工具、批处理作业和流水线会通过 Server-Sent Events 实时发出进度。进度流是公开的，以作业 ID 作为键，因此客户端无需发送 Authorization 头即可读取。
+
+```bash
+# Connect to the SSE stream (jobId is in the JSON response body from the tool endpoint)
+curl -N http://localhost:1349/api/v1/jobs/<jobId>/progress
+```
+
+事件格式：
+```
+data: {"jobId":"...","type":"single","phase":"processing","stage":"Upscaling","percent":42}
+data: {"jobId":"...","type":"single","phase":"complete","percent":100,"result":{"downloadUrl":"/api/v1/download/..."}}
+data: {"jobId":"...","type":"batch","status":"processing","completedFiles":2,"totalFiles":5,"failedFiles":0,"errors":[]}
+```
+
+你可以用 `POST /api/v1/jobs/:jobId/cancel` 请求取消一个已排队或正在运行的作业。响应为 `{"canceled":true|false}`。
+
+## 文件库 {#file-library}
+
+带版本历史的持久化文件存储。
+
+| 方法 | 路径 | 说明 |
+|--------|------|-------------|
+| `POST` | `/api/v1/upload` | 将文件上传到工作区（临时处理） |
+| `POST` | `/api/v1/files/upload` | 将文件上传到持久化文件库 |
+| `POST` | `/api/v1/files/save-result` | 将工具处理结果保存为一个新文件版本 |
+| `GET` | `/api/v1/files` | 列出已保存文件（分页，带搜索） |
+| `GET` | `/api/v1/files/:id` | 获取文件元数据 + 版本链 |
+| `GET` | `/api/v1/files/:id/download` | 下载文件 |
+| `GET` | `/api/v1/files/:id/thumbnail` | 获取 300px JPEG 缩略图 |
+| `DELETE` | `/api/v1/files` | 批量删除文件及其版本链（请求体：`{ ids: [...] }`） |
+| `POST` | `/api/v1/fetch-urls` | 将远程 URL 抓取到工作区，用于基于 URL 的导入 |
+| `POST` | `/api/v1/preview` | 生成浏览器兼容的 WebP 预览（适用于 HEIC/HEIF/RAW 格式） |
+| `GET` | `/api/v1/files/:id/preview` | 为已保存的 PDF、Office 文档、视频或音频文件流式传输已缓存或生成的浏览器兼容预览 |
+| `POST` | `/api/v1/preview/generate` | 为已上传的媒体文件按需生成 MP4 或 MP3 预览，无需先保存 |
+| `GET` | `/api/v1/download/:jobId/:filename` | 从工作区下载已处理的文件 |
+
+要将工具结果自动保存到文件库，请将 `fileId` 作为一个 multipart 表单字段包含进去，引用一个现有的库文件。处理结果将保存为一个新版本。
+
+## API 密钥管理 {#api-key-management}
+
+| 方法 | 路径 | 访问权限 | 说明 |
+|--------|------|--------|-------------|
+| `POST` | `/api/v1/api-keys` | 需身份验证 | 生成新密钥 - 只显示一次 |
+| `GET` | `/api/v1/api-keys` | 需身份验证 | 列出密钥（name、id、lastUsedAt - 不含原始密钥） |
+| `DELETE` | `/api/v1/api-keys/:id` | 需身份验证 | 删除密钥 |
+
+## 团队 {#teams}
+
+| 方法 | 路径 | 访问权限 | 说明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/teams` | 管理员（`teams:manage`） | 列出团队 |
+| `POST` | `/api/v1/teams` | 管理员（`teams:manage`） | 创建团队 |
+| `PUT` | `/api/v1/teams/:id` | 管理员（`teams:manage`） | 重命名团队 |
+| `DELETE` | `/api/v1/teams/:id` | 管理员（`teams:manage`） | 删除团队（无法删除默认团队或有成员的团队） |
+
+## 设置 {#settings}
+
+运行时键值配置（任何已验证用户可读，仅管理员可写）。
+
+| 方法 | 路径 | 说明 |
+|--------|------|-------------|
+| `GET` | `/api/v1/settings` | 获取所有设置 |
+| `PUT` | `/api/v1/settings` | 批量更新设置（带键值对的 JSON 请求体） |
+| `GET` | `/api/v1/settings/:key` | 按键获取指定设置 |
+
+已知键：`disabledTools`（工具 ID 的 JSON 数组）、`enableExperimentalTools`（bool 字符串）、`loginAttemptLimit`（数字）。
+
+## 偏好设置 {#preferences}
+
+每用户偏好设置与实例设置是分开的。任何已验证用户都可以读取和更新自己的偏好映射。
+
+| 方法 | 路径 | 说明 |
+|--------|------|-------------|
+| `GET` | `/api/v1/preferences` | 以 `{ "preferences": { ... } }` 获取当前用户的偏好设置 |
+| `PUT` | `/api/v1/preferences` | 为当前用户新增或更新一个或多个偏好键 |
+
+## 角色 {#roles}
+
+带细粒度权限的自定义角色管理。
+
+| 方法 | 路径 | 访问权限 | 说明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/roles` | 管理员（`audit:read`） | 列出所有角色及其用户数量 |
+| `POST` | `/api/v1/roles` | 管理员（`security:manage`） | 创建自定义角色（`name`、`description`、`permissions`） |
+| `PUT` | `/api/v1/roles/:id` | 管理员（`security:manage`） | 更新自定义角色（无法修改内置角色） |
+| `DELETE` | `/api/v1/roles/:id` | 管理员（`security:manage`） | 删除自定义角色（无法删除内置角色；受影响用户回退到 `user` 角色） |
+
+可用权限（17 个）：`tools:use`、`files:own`、`files:all`、`apikeys:own`、`apikeys:all`、`pipelines:own`、`pipelines:all`、`settings:read`、`settings:write`、`users:manage`、`teams:manage`、`features:manage`、`system:health`、`audit:read`、`compliance:manage`、`webhooks:manage`、`security:manage`。
+
+## 审计日志 {#audit-log}
+
+仅管理员的端点，用于审查与安全相关的操作。
+
+| 方法 | 路径 | 访问权限 | 说明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/audit-log` | 管理员（`audit:read`） | 带可选过滤器的分页审计日志 |
+
+查询参数：
+
+| 参数 | 说明 |
+|-----------|-------------|
+| `page` | 页码（默认：1） |
+| `limit` | 每页条目数（默认：50，最大：100） |
+| `action` | 按操作类型过滤（例如 `ROLE_CREATED`、`ROLE_DELETED`） |
+| `ip` | 按来源 IP 地址过滤 |
+| `from` | 过滤此 ISO 8601 日期之后的条目 |
+| `to` | 过滤此 ISO 8601 日期之前的条目 |
+
+## 分析 {#analytics}
+
+| 方法 | 路径 | 访问权限 | 说明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/config/analytics` | 公开 | 获取生效的分析配置（PostHog 密钥、Sentry DSN、采样率）。当分析关闭时（无论来自编译期烘焙还是实例 `analyticsEnabled` 设置），密钥、DSN 和实例 ID 均为空。 |
+| `POST` | `/api/v1/feedback` | 需身份验证 | 将显式的用户反馈以 `feedback_submitted` 提交到已配置的 PostHog 项目。该路由遵守分析开关，对提交进行限流，除非 `contactOk` 为 true 否则会剥离联系字段，并且从不接受文件内容、文件名、上传路径或原始私有错误文本。分析被禁用时，返回 `{ "ok": true, "accepted": false }`。 |
+| `PUT` | `/api/v1/settings` | 管理员（`settings:write`） | 设置实例范围的选择退出。发送 JSON 请求体 `{ "analyticsEnabled": "false" }` 为所有人关闭分析，或 `"true"` 重新开启。 |
+
+## 功能 / AI 捆绑包 {#features-ai-bundles}
+
+管理 AI 功能捆绑包（在 Docker 环境中安装/卸载 AI 模型包）。从自定义自动化启用某个工具时，优先使用工具级安装端点：某些 AI 工具需要多个共享捆绑包，而该端点会跳过已安装的捆绑包，仅将缺失的排队安装。
+
+| 方法 | 路径 | 访问权限 | 说明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/features` | 需身份验证 | 列出所有功能捆绑包及其安装状态 |
+| `POST` | `/api/v1/admin/features/:bundleId/install` | 管理员（`features:manage`） | 安装一个功能捆绑包（异步，返回 `jobId` 用于进度跟踪） |
+| `POST` | `/api/v1/admin/tools/:toolId/features/install` | 管理员（`features:manage`） | 安装某工具所需的每个捆绑包；返回每个捆绑包的已排队/已跳过状态 |
+| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | 管理员（`features:manage`） | 卸载一个功能捆绑包并清理模型文件 |
+| `GET` | `/api/v1/admin/features/disk-usage` | 管理员（`features:manage`） | 获取 AI 模型的总磁盘占用 |
+| `POST` | `/api/v1/admin/features/import` | 管理员（`features:manage`） | 导入一个离线 AI 捆绑包归档 |
+
+## 管理操作 {#admin-operations}
+
+用于可观测性、支持、用量报告和备份状态的运维端点。
+
+| 方法 | 路径 | 访问权限 | 说明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/admin/log-level` | 管理员（`settings:write`） | 读取当前运行时日志级别 |
+| `POST` | `/api/v1/admin/log-level` | 管理员（`settings:write`） | 更改运行时日志级别（`fatal`、`error`、`warn`、`info`、`debug`、`trace` 或 `silent`） |
+| `GET` | `/api/v1/metrics` | 管理员（`system:health`） | 文本格式的 Prometheus 指标 |
+| `GET` | `/api/v1/admin/support-bundle` | 管理员（`system:health`） | 下载一个已脱敏的诊断支持包 ZIP |
+| `GET` | `/api/v1/admin/usage` | 管理员（`audit:read`） | 用量仪表盘数据，带可选的 `days` 查询参数 |
+| `GET` | `/api/v1/admin/backup-status` | 管理员（`system:health`） | 读取上次备份元数据和新鲜度状态 |
+| `POST` | `/api/v1/admin/backup-status` | 管理员（`system:health`） | 记录一次已完成的备份（`type`，可选 `sizeBytes`，可选 `notes`） |
+
+## 企业版 API {#enterprise-apis}
+
+这些路由由其相关的企业版功能进行许可证限制。它们仍需要列出的 SnapOtter 权限。
+
+| 方法 | 路径 | 访问权限 | 说明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/enterprise/audit/export` | 管理员（`audit:read`） | 带过滤器将审计条目导出为 JSON 或 CSV |
+| `GET` | `/api/v1/enterprise/config/export` | 管理员（`system:health`） | 导出已脱敏的实例配置、自定义角色和团队 |
+| `POST` | `/api/v1/enterprise/config/import` | 管理员（`system:health`） | 导入配置，可选试运行 |
+| `GET` | `/api/v1/enterprise/ip-allowlist` | 管理员（`security:manage`） | 读取已配置的 CIDR 允许列表 |
+| `PUT` | `/api/v1/enterprise/ip-allowlist` | 管理员（`security:manage`） | 更新 CIDR 允许列表，并防止自我锁定 |
+| `GET` | `/api/v1/enterprise/legal-hold` | 管理员（`compliance:manage`） | 列出用户和团队的法律保留 |
+| `PUT` | `/api/v1/enterprise/legal-hold` | 管理员（`compliance:manage`） | 对用户或团队施加或解除法律保留 |
+| `POST` | `/api/v1/enterprise/scim/token` | 管理员（`users:manage`） | 生成一个 SCIM 承载令牌，仅返回一次 |
+| `DELETE` | `/api/v1/enterprise/scim/token` | 管理员（`users:manage`） | 吊销当前 SCIM 承载令牌 |
+| `GET` | `/api/v1/enterprise/siem/config` | 管理员（`webhooks:manage`） | 读取 SIEM 转发配置 |
+| `PUT` | `/api/v1/enterprise/siem/config` | 管理员（`webhooks:manage`） | 更新 SIEM 转发配置 |
+| `GET` | `/api/v1/enterprise/webhooks` | 管理员（`webhooks:manage`） | 列出 webhook 目标 |
+| `POST` | `/api/v1/enterprise/webhooks` | 管理员（`webhooks:manage`） | 创建一个 webhook 目标 |
+| `PUT` | `/api/v1/enterprise/webhooks/:index` | 管理员（`webhooks:manage`） | 更新一个 webhook 目标 |
+| `DELETE` | `/api/v1/enterprise/webhooks/:index` | 管理员（`webhooks:manage`） | 删除一个 webhook 目标 |
+| `POST` | `/api/v1/enterprise/webhooks/:index/test` | 管理员（`webhooks:manage`） | 发送一个测试 webhook 载荷 |
+| `POST` | `/api/v1/enterprise/users/:id/export` | 管理员（`compliance:manage`） | 启动一个 GDPR 用户导出作业 |
+| `GET` | `/api/v1/enterprise/users/:id/export/:jobId` | 管理员（`compliance:manage`） | 读取 GDPR 导出状态和下载 URL |
+| `DELETE` | `/api/v1/enterprise/users/:id/purge` | 管理员（`compliance:manage`） | 确认后永久清除用户数据 |
+| `DELETE` | `/api/v1/enterprise/teams/:id/purge` | 管理员（`compliance:manage`） | 确认后永久清除团队数据 |
+| `GET` | `/api/v1/admin/version` | 管理员（`system:health`） | 读取应用、构建、Node 和 schema 版本元数据 |
+| `GET` | `/api/v1/admin/migrations/pending` | 管理员（`system:health`） | 比较打包的迁移与已应用的迁移 |
+| `GET` | `/api/v1/admin/upgrade-check` | 管理员（`system:health`） | 运行升级就绪检查 |
+
+### SCIM 2.0 {#scim-2-0}
+
+SCIM 发现端点是公开的。用户和组端点需要上面生成的 SCIM 承载令牌。
+
+| 方法 | 路径 | 访问权限 | 说明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/scim/v2/ServiceProviderConfig` | 公开 | SCIM 服务器能力 |
+| `GET` | `/api/v1/scim/v2/Schemas` | 公开 | SCIM schema 发现 |
+| `GET` | `/api/v1/scim/v2/ResourceTypes` | 公开 | SCIM 资源类型发现 |
+| `GET` | `/api/v1/scim/v2/Users` | SCIM 令牌 | 列出用户，带可选的 SCIM 过滤器 |
+| `POST` | `/api/v1/scim/v2/Users` | SCIM 令牌 | 创建一个用户 |
+| `GET` | `/api/v1/scim/v2/Users/:id` | SCIM 令牌 | 获取一个用户 |
+| `PUT` | `/api/v1/scim/v2/Users/:id` | SCIM 令牌 | 替换一个用户 |
+| `DELETE` | `/api/v1/scim/v2/Users/:id` | SCIM 令牌 | 软停用一个用户 |
+| `GET` | `/api/v1/scim/v2/Groups` | SCIM 令牌 | 将团队列为 SCIM 组 |
+| `POST` | `/api/v1/scim/v2/Groups` | SCIM 令牌 | 创建一个团队 |
+| `GET` | `/api/v1/scim/v2/Groups/:id` | SCIM 令牌 | 获取一个团队 |
+| `PUT` | `/api/v1/scim/v2/Groups/:id` | SCIM 令牌 | 替换一个团队及组成员关系 |
+| `DELETE` | `/api/v1/scim/v2/Groups/:id` | SCIM 令牌 | 删除一个团队 |
+
+## 表情包模板 {#meme-templates}
+
+为表情包生成器工具提供支持的 API。
+
+| 方法 | 路径 | 访问权限 | 说明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/meme-templates` | 需身份验证 | 列出所有可用的表情包模板及文本框位置 |
+| `GET` | `/api/v1/meme-templates/full/:filename` | 需身份验证 | 提供完整尺寸的模板图片 |
+| `GET` | `/api/v1/meme-templates/thumbs/:filename` | 需身份验证 | 提供模板缩略图 |
+| `GET` | `/api/v1/meme-templates/fonts/:filename` | 需身份验证 | 提供用于表情包文本渲染的字体文件 |
+
+## 错误响应 {#error-responses}
+
+所有错误都返回 JSON：
+
+```json
+{
+  "error": "Human-readable message",
+  "code": "MACHINE_READABLE_CODE"
+}
+```
+
+| 状态码 | 含义 |
+|--------|---------|
+| 400 | 请求无效 / 校验失败 |
+| 401 | 未通过身份验证 |
+| 403 | 权限不足 |
+| 404 | 资源未找到 |
+| 413 | 文件过大（见 `MAX_UPLOAD_SIZE_MB`） |
+| 422 | 校验通过后处理失败 |
+| 429 | 已被限流（见 `RATE_LIMIT_PER_MIN`） |
+| 501 | 所需的 AI 功能捆绑包未安装（`FEATURE_NOT_INSTALLED`） |
+| 500 | 服务器内部错误 |