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: 36207813ccb8
+---
+
+# AI 引擎參考 {#ai-engine-reference}
+
+`@snapotter/ai` 套件將 Node.js 橋接到一個**常駐的 Python sidecar**，用於所有 ML 操作。dispatcher 程序在兩次請求之間保持存活，以獲得快速的暖啟動效能。啟動時會自動偵測 NVIDIA CUDA，可用時即加以使用；否則 AI 工具會在 CPU 上執行。
+
+目前不支援透過 VA-API、Quick Sync 或 OpenCL 進行 Intel/AMD iGPU 的 AI 推論加速。除非有支援 CUDA 的 NVIDIA GPU 可用，否則將 `/dev/dri` 對映進容器並不會加速這些 Python sidecar 工具。
+
+19 個 Python sidecar AI 工具，橫跨四種模態（image、audio、video、document），另有 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」dispatcher 設定檔，以文件處理指令碼（`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` 進行安裝，它會解析完整的套件包清單、略過已安裝的套件包，並只將缺少的下載排入佇列。舉例來說，在全新的執行個體上啟用 Passport Photo 會將 `background-removal` 與 `face-detection` 排入佇列；若在 Background Removal 已安裝後才啟用它，則只會將 `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`  
+**模型：** rembg 搭配 BiRefNet（預設）或 U2-Net 變體
+
+| 參數 | 型別 | 預設值 | 說明 |
+|-----------|------|---------|-------------|
+| `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 的 Job 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 | - | 自訂寬度（mm）（覆寫國家規格） |
+| `customHeightMm` | number | - | 自訂高度（mm）（覆寫國家規格） |
+| `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 人臉偵測（僅 face 模式）
+
+| 參數 | 型別 | 預設值 | 說明 |
+|-----------|------|---------|-------------|
+| `mode` | string | `"subject"` | 裁切策略：`subject`、`face`、`trim` |
+| `strategy` | `"attention"` \| `"entropy"` | `"attention"` | subject 模式的策略 |
+| `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 sidecar 工具，但在啟用特定選項時會使用 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: b8db3db71a01
+---
+
+# 影像引擎 {#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（反遮罩銳利化） |
+| `radius` | number | 模糊半徑，0.1-5.0（反遮罩銳利化） |
+| `threshold` | number | 最小邊緣亮度，0-255（反遮罩銳利化） |
+| `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-TW/guide/supported-formats) 頁面。
+
+## 中繼資料擷取 {#metadata-extraction}
+
+`info` 工具會回傳影像中繼資料。完整欄位參考請見 [影像資訊](/zh-TW/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: 9fa4a9a91996
+---
+
+# REST API 參考 {#rest-api-reference}
+
+可在 [http://localhost:1349/api/docs](http://localhost:1349/api/docs) 取得含請求／回應範例的互動式 API 文件。
+
+機器可讀規格：
+- `/api/v1/openapi.yaml` - OpenAPI 3.1 規格
+- `/llms.txt` - 便於 LLM 使用的摘要
+- `/llms-full.txt` - 完整的 LLM 友善文件
+
+## 驗證 {#authentication}
+
+除非 `AUTH_ENABLED=false`，所有端點都需要驗證。
+
+### Session Token {#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>"
+```
+
+Session 會在 7 天後過期（可透過 `SESSION_DURATION_HOURS` 設定）。
+
+### API Keys {#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>"
+```
+
+Key 以 `si_` 為前綴並以 scrypt 雜湊儲存，原始 key 只會顯示一次，之後無法再取回。
+
+### 驗證端點 {#auth-endpoints}
+
+| Method | Path | 存取權限 | 說明 |
+|--------|------|--------|-------------|
+| `POST` | `/api/auth/login` | Public | 登入，取得 session token |
+| `POST` | `/api/auth/logout` | Auth | 銷毀目前的 session |
+| `GET` | `/api/auth/session` | Auth | 驗證目前的 session |
+| `POST` | `/api/auth/change-password` | Auth | 變更自己的密碼（會使所有其他 session 與 API key 失效） |
+| `GET` | `/api/auth/users` | Admin | 列出所有使用者 |
+| `POST` | `/api/auth/register` | Admin | 建立新使用者 |
+| `PUT` | `/api/auth/users/:id` | Admin | 更新使用者角色或團隊 |
+| `POST` | `/api/auth/users/:id/reset-password` | Admin | 重設使用者密碼 |
+| `DELETE` | `/api/auth/users/:id` | Admin | 刪除使用者 |
+| `GET` | `/api/v1/config/auth` | Public | 檢查是否已啟用驗證（`{ authEnabled: bool }`） |
+| `POST` | `/api/auth/mfa/enroll` | Auth | 啟動 TOTP MFA 註冊。需要企業版 `mfa` 功能 |
+| `POST` | `/api/auth/mfa/verify` | Auth | 以 TOTP 代碼確認 MFA 註冊 |
+| `POST` | `/api/auth/mfa/complete` | Public | 完成待處理的 MFA 登入挑戰 |
+| `POST` | `/api/auth/mfa/disable` | Auth | 為目前使用者停用 MFA |
+| `POST` | `/api/auth/users/:id/mfa/reset` | Admin（`users:manage`） | 重設某使用者的 MFA |
+| `GET` | `/api/auth/oidc/login` | Public | 啟用 OIDC 時啟動 OIDC 登入 |
+| `GET` | `/api/auth/oidc/callback` | Public | OIDC 授權回呼 |
+| `GET` | `/api/auth/saml/metadata` | Public | 啟用 SAML 時的 SAML SP metadata XML |
+| `GET` | `/api/auth/saml/login` | Public | 啟動 SAML 登入 |
+| `POST` | `/api/auth/saml/callback` | Public | SAML assertion consumer service |
+
+當使用者啟用 MFA 時，`POST /api/auth/login` 會回傳 `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` 而非 session token。將該 `mfaToken` 加上 TOTP 或復原代碼送至 `/api/auth/mfa/complete`。
+
+### 權限 {#permissions}
+
+| 權限 | Admin | User |
+|-----------|:-----:|:----:|
+| 使用工具 | ✓ | ✓ |
+| 擁有檔案／管線／API key | ✓ | ✓ |
+| 查看所有使用者的檔案／管線／key | ✓ | - |
+| 寫入設定 | ✓ | - |
+| 管理使用者與團隊 | ✓ | - |
+| 管理品牌 | ✓ | - |
+
+## 健康檢查 {#health-check}
+
+| Method | Path | 存取權限 | 說明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/health` | Public | 基本健康檢查。健康時回傳 `{"status":"healthy","version":"..."}` 與 200；若資料庫無法連線則回傳 `{"status":"unhealthy"}` 與 503。 |
+| `GET` | `/api/v1/readyz` | Public | 就緒探測。檢查 PostgreSQL、Redis、磁碟空間，以及設定後的 S3。當該執行個體不應接收流量時回傳 503。 |
+| `GET` | `/api/v1/admin/health` | Admin（`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-TW/tools/conversion-presets)。
+
+### 基本功能 {#essentials}
+
+| Tool 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}
+
+| Tool ID | 名稱 | 主要設定 |
+|---------|------|-------------|
+| `optimize-for-web` | 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` | Favicon 產生器 | `padding`、`backgroundColor`、`borderRadius` - 產生所有標準尺寸 |
+
+### 調整 {#adjustments}
+
+| Tool 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 iGPU 加速做 AI 推論。無需連網。
+
+| Tool 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`；產生使用 JSON，含 `countryCode`、`bgColor`、`printLayout`（none/4x6/a4）、特徵點、影像尺寸 |
+| `content-aware-resize` | 內容感知調整大小 | Seam carving（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}
+
+| Tool 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}
+
+| Tool 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` | QR Code 產生器 | `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}
+
+| Tool 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}
+
+| Tool 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}
+
+| Tool 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 | `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}
+
+| Tool 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}
+
+| Tool 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` | Web 最佳化 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}
+
+| Tool 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 | - （防炸彈保護） |
+
+### 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>` 之外還提供額外端點：
+
+| Method | Path | 說明 |
+|--------|------|-------------|
+| `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}
+
+| Method | Path | 說明 |
+|--------|------|-------------|
+| `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}
+
+具版本歷史的持久性檔案儲存。
+
+| Method | Path | 說明 |
+|--------|------|-------------|
+| `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 Key 管理 {#api-key-management}
+
+| Method | Path | 存取權限 | 說明 |
+|--------|------|--------|-------------|
+| `POST` | `/api/v1/api-keys` | Auth | 產生新 key，僅顯示一次 |
+| `GET` | `/api/v1/api-keys` | Auth | 列出 key（name、id、lastUsedAt，非原始 key） |
+| `DELETE` | `/api/v1/api-keys/:id` | Auth | 刪除 key |
+
+## 團隊 {#teams}
+
+| Method | Path | 存取權限 | 說明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/teams` | Admin（`teams:manage`） | 列出團隊 |
+| `POST` | `/api/v1/teams` | Admin（`teams:manage`） | 建立團隊 |
+| `PUT` | `/api/v1/teams/:id` | Admin（`teams:manage`） | 重新命名團隊 |
+| `DELETE` | `/api/v1/teams/:id` | Admin（`teams:manage`） | 刪除團隊（無法刪除預設團隊或含成員的團隊） |
+
+## 設定 {#settings}
+
+執行時的鍵值設定（任何已驗證使用者可讀取，僅管理員可寫入）。
+
+| Method | Path | 說明 |
+|--------|------|-------------|
+| `GET` | `/api/v1/settings` | 取得所有設定 |
+| `PUT` | `/api/v1/settings` | 批次更新設定（帶有鍵值對的 JSON 主體） |
+| `GET` | `/api/v1/settings/:key` | 依 key 取得特定設定 |
+
+已知的 key：`disabledTools`（工具 ID 的 JSON 陣列）、`enableExperimentalTools`（bool 字串）、`loginAttemptLimit`（number）。
+
+## 偏好設定 {#preferences}
+
+各使用者的偏好設定與執行個體設定分開。任何已驗證使用者都可讀取並更新自己的偏好設定對應表。
+
+| Method | Path | 說明 |
+|--------|------|-------------|
+| `GET` | `/api/v1/preferences` | 以 `{ "preferences": { ... } }` 取得目前使用者的偏好設定 |
+| `PUT` | `/api/v1/preferences` | 為目前使用者新增或更新一個以上的偏好設定 key |
+
+## 角色 {#roles}
+
+具細緻權限的自訂角色管理。
+
+| Method | Path | 存取權限 | 說明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/roles` | Admin（`audit:read`） | 列出所有角色及其使用者數 |
+| `POST` | `/api/v1/roles` | Admin（`security:manage`） | 建立自訂角色（`name`、`description`、`permissions`） |
+| `PUT` | `/api/v1/roles/:id` | Admin（`security:manage`） | 更新自訂角色（無法修改內建角色） |
+| `DELETE` | `/api/v1/roles/:id` | Admin（`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}
+
+僅限管理員的端點，用於檢視與安全相關的動作。
+
+| Method | Path | 存取權限 | 說明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/audit-log` | Admin（`audit:read`） | 分頁的稽核日誌，含選用篩選條件 |
+
+查詢參數：
+
+| 參數 | 說明 |
+|-----------|-------------|
+| `page` | 頁碼（預設：1） |
+| `limit` | 每頁項目數（預設：50，上限：100） |
+| `action` | 依動作類型篩選（例如 `ROLE_CREATED`、`ROLE_DELETED`） |
+| `ip` | 依來源 IP 位址篩選 |
+| `from` | 篩選此 ISO 8601 日期之後的項目 |
+| `to` | 篩選此 ISO 8601 日期之前的項目 |
+
+## 分析 {#analytics}
+
+| Method | Path | 存取權限 | 說明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/config/analytics` | Public | 取得有效的分析設定（PostHog key、Sentry DSN、取樣率）。當分析關閉時（無論來自編譯時的烘焙或執行個體的 `analyticsEnabled` 設定），key、DSN 與執行個體 ID 皆為空白。 |
+| `POST` | `/api/v1/feedback` | Auth | 將明確的使用者意見回饋提交至設定的 PostHog 專案，作為 `feedback_submitted`。此路由遵守分析開關、對提交做速率限制，除非 `contactOk` 為 true 否則移除聯絡欄位，且永不接受檔案內容、檔名、上傳路徑或原始的私密錯誤文字。當分析停用時，回傳 `{ "ok": true, "accepted": false }`。 |
+| `PUT` | `/api/v1/settings` | Admin（`settings:write`） | 設定整個執行個體的退出。送出 JSON 主體 `{ "analyticsEnabled": "false" }` 為所有人關閉分析，或 `"true"` 重新開啟。 |
+
+## 功能 / AI Bundle {#features-ai-bundles}
+
+管理 AI 功能 bundle（在 Docker 環境中安裝／解除安裝 AI 模型套件）。從自訂自動化流程啟用工具時，建議使用工具層級的安裝端點：某些 AI 工具需要一個以上的共用 bundle，而此端點會略過已安裝的 bundle，只將缺少的排入佇列。
+
+| Method | Path | 存取權限 | 說明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/features` | Auth | 列出所有功能 bundle 及其安裝狀態 |
+| `POST` | `/api/v1/admin/features/:bundleId/install` | Admin（`features:manage`） | 安裝功能 bundle（非同步，回傳 `jobId` 以追蹤進度） |
+| `POST` | `/api/v1/admin/tools/:toolId/features/install` | Admin（`features:manage`） | 安裝某工具所需的每個 bundle；回傳各 bundle 的已排入佇列／已略過狀態 |
+| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Admin（`features:manage`） | 解除安裝功能 bundle 並清除模型檔案 |
+| `GET` | `/api/v1/admin/features/disk-usage` | Admin（`features:manage`） | 取得 AI 模型的總磁碟使用量 |
+| `POST` | `/api/v1/admin/features/import` | Admin（`features:manage`） | 匯入離線 AI bundle 封存 |
+
+## 管理操作 {#admin-operations}
+
+用於可觀測性、支援、使用量報告與備份狀態的維運端點。
+
+| Method | Path | 存取權限 | 說明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/admin/log-level` | Admin（`settings:write`） | 讀取目前執行時的日誌層級 |
+| `POST` | `/api/v1/admin/log-level` | Admin（`settings:write`） | 變更執行時的日誌層級（`fatal`、`error`、`warn`、`info`、`debug`、`trace` 或 `silent`） |
+| `GET` | `/api/v1/metrics` | Admin（`system:health`） | 文字格式的 Prometheus metrics |
+| `GET` | `/api/v1/admin/support-bundle` | Admin（`system:health`） | 下載已遮蔽的診斷支援 bundle ZIP |
+| `GET` | `/api/v1/admin/usage` | Admin（`audit:read`） | 使用量儀表板資料，含選用的 `days` 查詢參數 |
+| `GET` | `/api/v1/admin/backup-status` | Admin（`system:health`） | 讀取最近一次備份的中繼資料與新鮮度狀態 |
+| `POST` | `/api/v1/admin/backup-status` | Admin（`system:health`） | 記錄一次已完成的備份（`type`、選用 `sizeBytes`、選用 `notes`） |
+
+## 企業 API {#enterprise-apis}
+
+這些路由受其相關企業功能的授權控管。它們仍需要所列的 SnapOtter 權限。
+
+| Method | Path | 存取權限 | 說明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/enterprise/audit/export` | Admin（`audit:read`） | 以 JSON 或 CSV 匯出稽核項目，可加篩選 |
+| `GET` | `/api/v1/enterprise/config/export` | Admin（`system:health`） | 匯出已遮蔽的執行個體設定、自訂角色與團隊 |
+| `POST` | `/api/v1/enterprise/config/import` | Admin（`system:health`） | 匯入設定，可選乾跑 |
+| `GET` | `/api/v1/enterprise/ip-allowlist` | Admin（`security:manage`） | 讀取已設定的 CIDR 允許清單 |
+| `PUT` | `/api/v1/enterprise/ip-allowlist` | Admin（`security:manage`） | 更新 CIDR 允許清單，並防止自我鎖定 |
+| `GET` | `/api/v1/enterprise/legal-hold` | Admin（`compliance:manage`） | 列出使用者與團隊的法律保留 |
+| `PUT` | `/api/v1/enterprise/legal-hold` | Admin（`compliance:manage`） | 對使用者或團隊套用或解除法律保留 |
+| `POST` | `/api/v1/enterprise/scim/token` | Admin（`users:manage`） | 產生 SCIM bearer token，僅回傳一次 |
+| `DELETE` | `/api/v1/enterprise/scim/token` | Admin（`users:manage`） | 撤銷目前的 SCIM bearer token |
+| `GET` | `/api/v1/enterprise/siem/config` | Admin（`webhooks:manage`） | 讀取 SIEM 轉發設定 |
+| `PUT` | `/api/v1/enterprise/siem/config` | Admin（`webhooks:manage`） | 更新 SIEM 轉發設定 |
+| `GET` | `/api/v1/enterprise/webhooks` | Admin（`webhooks:manage`） | 列出 webhook 目的地 |
+| `POST` | `/api/v1/enterprise/webhooks` | Admin（`webhooks:manage`） | 建立 webhook 目的地 |
+| `PUT` | `/api/v1/enterprise/webhooks/:index` | Admin（`webhooks:manage`） | 更新 webhook 目的地 |
+| `DELETE` | `/api/v1/enterprise/webhooks/:index` | Admin（`webhooks:manage`） | 刪除 webhook 目的地 |
+| `POST` | `/api/v1/enterprise/webhooks/:index/test` | Admin（`webhooks:manage`） | 送出測試 webhook 酬載 |
+| `POST` | `/api/v1/enterprise/users/:id/export` | Admin（`compliance:manage`） | 啟動 GDPR 使用者匯出工作 |
+| `GET` | `/api/v1/enterprise/users/:id/export/:jobId` | Admin（`compliance:manage`） | 讀取 GDPR 匯出狀態與下載 URL |
+| `DELETE` | `/api/v1/enterprise/users/:id/purge` | Admin（`compliance:manage`） | 確認後永久清除某使用者的資料 |
+| `DELETE` | `/api/v1/enterprise/teams/:id/purge` | Admin（`compliance:manage`） | 確認後永久清除某團隊的資料 |
+| `GET` | `/api/v1/admin/version` | Admin（`system:health`） | 讀取 app、build、Node 與 schema 版本中繼資料 |
+| `GET` | `/api/v1/admin/migrations/pending` | Admin（`system:health`） | 比較封裝的遷移與已套用的遷移 |
+| `GET` | `/api/v1/admin/upgrade-check` | Admin（`system:health`） | 執行升級就緒性檢查 |
+
+### SCIM 2.0 {#scim-2-0}
+
+SCIM 探索端點為公開。使用者與群組端點需要上方產生的 SCIM bearer token。
+
+| Method | Path | 存取權限 | 說明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/scim/v2/ServiceProviderConfig` | Public | SCIM 伺服器能力 |
+| `GET` | `/api/v1/scim/v2/Schemas` | Public | SCIM schema 探索 |
+| `GET` | `/api/v1/scim/v2/ResourceTypes` | Public | SCIM 資源類型探索 |
+| `GET` | `/api/v1/scim/v2/Users` | SCIM token | 列出使用者，可加選用的 SCIM 篩選 |
+| `POST` | `/api/v1/scim/v2/Users` | SCIM token | 建立使用者 |
+| `GET` | `/api/v1/scim/v2/Users/:id` | SCIM token | 取得使用者 |
+| `PUT` | `/api/v1/scim/v2/Users/:id` | SCIM token | 取代使用者 |
+| `DELETE` | `/api/v1/scim/v2/Users/:id` | SCIM token | 軟性停用使用者 |
+| `GET` | `/api/v1/scim/v2/Groups` | SCIM token | 以 SCIM 群組列出團隊 |
+| `POST` | `/api/v1/scim/v2/Groups` | SCIM token | 建立團隊 |
+| `GET` | `/api/v1/scim/v2/Groups/:id` | SCIM token | 取得團隊 |
+| `PUT` | `/api/v1/scim/v2/Groups/:id` | SCIM token | 取代團隊與群組成員資格 |
+| `DELETE` | `/api/v1/scim/v2/Groups/:id` | SCIM token | 刪除團隊 |
+
+## 迷因範本 {#meme-templates}
+
+支援迷因產生器工具的 API。
+
+| Method | Path | 存取權限 | 說明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/meme-templates` | Auth | 列出所有可用的迷因範本及文字方塊位置 |
+| `GET` | `/api/v1/meme-templates/full/:filename` | Auth | 提供全尺寸範本圖片 |
+| `GET` | `/api/v1/meme-templates/thumbs/:filename` | Auth | 提供範本縮圖 |
+| `GET` | `/api/v1/meme-templates/fonts/:filename` | Auth | 提供迷因文字繪製所用的字型檔 |
+
+## 錯誤回應 {#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 功能 bundle（`FEATURE_NOT_INSTALLED`） |
+| 500 | 內部伺服器錯誤 |