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: "すべてのローカル ML ツールを網羅した AI エンジンリファレンス。背景除去、アップスケーリング、OCR、顔検出、写真復元など。"
+i18n_source_hash: 14728c1dcd05
+i18n_provenance: machine
+i18n_output_hash: 721e8f11de40
+---
+
+# AI エンジンリファレンス {#ai-engine-reference}
+
+`@snapotter/ai` パッケージは、すべての ML 処理のために Node.js を**永続的な Python サイドカー**へ橋渡しします。ディスパッチャープロセスはリクエスト間で稼働し続けるため、高速なウォームスタート性能が得られます。NVIDIA CUDA は起動時に自動検出され、利用可能な場合に使用されます。それ以外の場合、AI ツールは CPU 上で動作します。
+
+VA-API、Quick Sync、OpenCL を介した Intel/AMD の iGPU アクセラレーションは、現時点では AI 推論に対応していません。`/dev/dri` をコンテナにマッピングしても、CUDA 対応の NVIDIA GPU が利用できない限り、これらの Python サイドカーツールは高速化されません。
+
+4 つのモダリティ（画像、音声、動画、ドキュメント）にわたる 19 個の Python サイドカー AI ツールに加え、AI 機能をオプションで備えた 2 個のツールがあります。すべてのモデルはローカルで動作します。初回のモデルダウンロード後はインターネットは不要です。
+
+## アーキテクチャ {#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」ディスパッチャープロファイルは、AI 許可リストをドキュメント処理スクリプト（`doc_pagecount`、`doc_health`、`doc_flatten`、`doc_redact`、`doc_text`、`doc_to_word`、`doc_metadata`、`doc_html_pdf`）に置き換え、重い ML インポートをスキップします。
+
+**タイムアウト:** デフォルトは 300 秒。OCR と BiRefNet 背景除去は 600 秒です。
+
+## フィーチャーバンドル {#feature-bundles}
+
+AI モデルは、ツールごとに 1 つのアーカイブとしてではなく、共有される依存関係スタックによってパッケージ化されています。フィーチャーバンドルは、同じモデルファミリー、Python ホイール、またはネイティブライブラリを使用するツールをまとめて有効化できます。これにより、リリース用の Docker イメージが小さく保たれ、同じ背景マッティング、顔検出、OCR、復元、音声モデルの重複コピーの保存を避けられます。
+
+Docker イメージには、アプリケーションと共通ランタイムが同梱されています。大きなモデルアーカイブはオンデマンドで永続的な `/data/ai` ボリュームにダウンロードされ、それを必要とするすべてのツールで再利用されます。別のツールがすでに必要としたためにバンドルがインストール済みの場合、新たに依存するツールを有効化してもそのバンドルは再ダウンロードされません。
+
+各 AI ツールは、実行前に 1 つ以上のフィーチャーバンドルを必要とします。管理 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` | 背景を除去した後、顔のランドマークを使って、パスポートや ID 写真の規則に合わせてクロップを構図します。 |
+| `enhance-faces` | `upscale-enhance`, `face-detection` | 選択した顔の領域で GFPGAN または CodeFormer による補正を実行する前に、顔を検出します。 |
+
+ツールは、必要なすべてのバンドルがインストールされている場合にのみ利用可能になります。部分的なインストールは有効であり、段階的に処理されます。インストール済みのバンドルは再利用され、不足しているバンドルはダウンロードとして表示され、キューに入れられたインストールは共有 Python 環境が同時に変更されないよう 1 つずつ実行されます。
+
+---
+
+## 背景除去 {#background-removal}
+
+**ツールルート:** `remove-background`  
+**モデル:** BiRefNet（デフォルト）または U2-Net バリアントを用いた rembg
+
+| パラメータ | 型 | デフォルト | 説明 |
+|-----------|------|---------|-------------|
+| `model` | string | - | モデルバリアント（任意の上書き） |
+| `backgroundType` | string | `"transparent"` | 次のいずれか: `transparent`, `color`, `gradient`, `blur`, `image` |
+| `backgroundColor` | string | - | 単色背景の 16 進カラー |
+| `gradientColor1` | string | - | グラデーションの 1 色目 |
+| `gradientColor2` | string | - | グラデーションの 2 色目 |
+| `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"` | 背景の 16 進カラー（`backgroundType` が `color` の場合） |
+| `gradientColor1` | string | - | グラデーションの 1 色目（16 進） |
+| `gradientColor2` | string | - | グラデーションの 2 色目（16 進） |
+| `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"` |
+
+## 顔 / 個人情報のぼかし {#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 背景除去
+
+2 フェーズのワークフロー: 分析（顔を検出 + 背景を除去）してから生成（クロップ、リサイズ、タイル配置）します。6 地域にわたる 37 か国以上に対応しています。
+
+### フェーズ 1: 分析 {#phase-1-analyze}
+
+`POST /api/v1/tools/image/passport-photo/analyze`
+
+画像ファイル（マルチパート）を受け付けます。顔のランドマークデータ、base64 のプレビュー、画像の寸法を返します。
+
+### フェーズ 2: 生成 {#phase-2-generate}
+
+`POST /api/v1/tools/image/passport-photo/generate`
+
+フェーズ 1 の結果に加えて生成設定を含む JSON ボディを受け付けます:
+
+| パラメータ | 型 | デフォルト | 説明 |
+|-----------|------|---------|-------------|
+| `jobId` | string | （必須） | フェーズ 1 のジョブ ID |
+| `filename` | string | （必須） | フェーズ 1 の元のファイル名 |
+| `countryCode` | string | （必須） | ISO 国コード（例: `US`, `GB`, `IN`） |
+| `documentType` | string | `"passport"` | ドキュメントの種類 |
+| `bgColor` | string | `"#FFFFFF"` | 背景色の 16 進 |
+| `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
+
+マスクは base64 ではなく、**2 つ目のファイルパート**（フィールド名 `mask`）として送信されます。マスク内の白いピクセルが消去する領域を示します。`format` と `quality` の設定はトップレベルのフォームフィールドとして送信されます。
+
+| パラメータ | 型 | デフォルト | 説明 |
+|-----------|------|---------|-------------|
+| `file` | file | （必須） | ソース画像（マルチパート） |
+| `mask` | file | （必須） | マスク画像（マルチパート、フィールド名 `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` | 出力品質 |
+
+少なくとも 1 つの拡張方向が 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 マッティング（2048x2048 解像度）
+
+背景が除去されたものの、フリンジ、ハロー、半透明のアーティファクトが残った「見せかけの透過」PNG を修正します。BiRefNet の高解像度マッティングモデルを使用してクリーンなアルファチャンネルを生成し、その後、設定可能なデフリンジ処理を適用してエッジに沿った色の混入を除去します。
+
+**OOM フォールバックチェーン:** BiRefNet HR マッティングが利用可能なメモリを超過した場合、ツールは自動的に `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: 3ee05b506af7
+---
+
+# 画像エンジン {#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}
+
+画像を水平方向、垂直方向、またはその両方に反転します。少なくとも 1 つは 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、非可逆形式に適用) |
+
+最初の 7 つの形式(`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 のガウスシグマにマッピングされます。 |
+
+### sharpen-advanced {#sharpen-advanced}
+
+3 つの選択可能な手法と、オプションのノイズ低減前処理を備えた高度なシャープ化。
+
+| パラメータ | 型 | 説明 |
+|---|---|---|
+| `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 | 3x3 / 5x5 カーネルの場合は `3` または `5`(ハイパス) |
+| `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 デコーダーへの自動フォールバックがあります。
+
+完全なリストについては、[対応形式](/ja/guide/supported-formats)ページを参照してください。
+
+## メタデータの抽出 {#metadata-extraction}
+
+`info` ツールは画像のメタデータを返します。フィールドの完全なリファレンスについては、[画像情報](/ja/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: aa42f6d4ddbe
+---
+
+# 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` | Public | ログインしてセッショントークンを取得 |
+| `POST` | `/api/auth/logout` | Auth | 現在のセッションを破棄 |
+| `GET` | `/api/auth/session` | Auth | 現在のセッションを検証 |
+| `POST` | `/api/auth/change-password` | Auth | 自分のパスワードを変更（他のすべてのセッションと API キーを無効化） |
+| `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 メタデータ XML |
+| `GET` | `/api/auth/saml/login` | Public | SAML ログインを開始 |
+| `POST` | `/api/auth/saml/callback` | Public | SAML アサーションコンシューマーサービス |
+
+ユーザーに対して MFA が有効な場合、`POST /api/auth/login` はセッショントークンの代わりに `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` を返します。その `mfaToken` と TOTP またはリカバリコードを `/api/auth/mfa/complete` に送信してください。
+
+### パーミッション {#permissions}
+
+| パーミッション | Admin | User |
+|-----------|:-----:|:----:|
+| ツールを使用 | ✓ | ✓ |
+| 自分のファイル/パイプライン/API キー | ✓ | ✓ |
+| 全ユーザーのファイル/パイプライン/キーを閲覧 | ✓ | - |
+| 設定の書き込み | ✓ | - |
+| ユーザーとチームの管理 | ✓ | - |
+| ブランディングの管理 | ✓ | - |
+
+## ヘルスチェック {#health-check}
+
+| メソッド | パス | アクセス | 説明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/health` | Public | 基本的なヘルスチェック。200 で `{"status":"healthy","version":"..."}` を返し、データベースに到達できない場合は 503 で `{"status":"unhealthy"}` を返します。 |
+| `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}
+
+共有カタログには、`jpg-to-png`、`mov-to-mp4`、`m4a-to-mp3`、`pdf-to-jpg`、`excel-to-csv` など、83 個の専用変換プリセットエンドポイントが含まれています。プリセットはファーストクラスのツールルートです:
+
+`POST /api/v1/tools/<section>/<presetId>`
+
+各プリセットは出力形式を固定し、`convert`、`convert-video`、`extract-audio`、`convert-audio`、`image-to-pdf`、`pdf-to-image`、`svg-to-raster`、`convert-spreadsheet` などのベースツールに委譲します。完全なルートテーブルとオプション設定については、[変換プリセット](/ja/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` | 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 iGPU アクセラレーションは、現在 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） | マスクは 2 番目のファイルパートとして送信（フィールド名 `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 ランドマーク | 2 フェーズフロー。解析はマルチパート `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（アウトペインティング） | `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` - 2 番目のファイルがウォーターマーク |
+| `text-overlay` | テキストオーバーレイ | `text`, `font`, `fontSize`, `color`, `x`, `y`, `background`, `padding`, `borderRadius` |
+| `compose` | 画像合成 | `x`, `y`, `opacity`, `blend` - 2 番目のファイルが上にレイヤーされる |
+| `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 ボディ）またはカスタム画像モード（ファイル付きマルチパート）に対応。 |
+
+### ユーティリティ {#utilities}
+
+| ツール ID | 名前 | 主な設定 |
+|---------|------|-------------|
+| `info` | 画像情報 | -（width, height, format, size, channels, hasAlpha, DPI, EXIF を返す） |
+| `compare` | 画像比較 | `mode`（side-by-side/overlay/diff）, `diffThreshold` - 2 番目のファイルが比較対象 |
+| `find-duplicates` | 重複の検出 | `threshold`（知覚ハッシュ距離、デフォルト 8） - 複数ファイル |
+| `color-palette` | カラーパレット | `count`（主要色の数）, `format`（hex/rgb） |
+| `qr-generate` | QR コードジェネレーター | `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 の変更 | `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` | 音声の置き換え | -（動画 + 音声ファイル、2 ファイル） |
+| `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 の Web 最適化 | -（高速な Web 表示のためにリニアライズ） |
+| `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 の署名 | 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 の展開 | -（ボム対策済み） |
+
+### HTML から画像 {#html-to-image}
+
+Web ページを画像としてキャプチャします。他のツールと異なり、このエンドポイントはマルチパートフォームデータの代わりに `application/json` を受け付けます（ファイルアップロードは不要）。
+
+**エンドポイント:** `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` | AI を再実行せずに背景エフェクト（color/gradient/blur/shadow）を適用。初回削除時のキャッシュされたマスクを使用。 |
+| `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` をマルチパートフォームフィールドとして含めます。処理結果は新しいバージョンとして保存されます。
+
+## API キー管理 {#api-key-management}
+
+| メソッド | パス | アクセス | 説明 |
+|--------|------|--------|-------------|
+| `POST` | `/api/v1/api-keys` | Auth | 新しいキーを生成 - 一度だけ表示 |
+| `GET` | `/api/v1/api-keys` | Auth | キーを一覧表示（name, id, lastUsedAt - 生のキーは含まない） |
+| `DELETE` | `/api/v1/api-keys/:id` | Auth | キーを削除 |
+
+## チーム {#teams}
+
+| メソッド | パス | アクセス | 説明 |
+|--------|------|--------|-------------|
+| `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}
+
+ランタイムのキー・バリュー設定（認証済みユーザーは誰でも読み取り可能、書き込みは管理者のみ）。
+
+| メソッド | パス | 説明 |
+|--------|------|-------------|
+| `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` | 現在のユーザーの 1 つ以上の環境設定キーをアップサート |
+
+## ロール {#roles}
+
+細分化されたパーミッションを持つカスタムロール管理。
+
+| メソッド | パス | アクセス | 説明 |
+|--------|------|--------|-------------|
+| `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}
+
+セキュリティ関連のアクションを確認するための管理者専用エンドポイント。
+
+| メソッド | パス | アクセス | 説明 |
+|--------|------|--------|-------------|
+| `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}
+
+| メソッド | パス | アクセス | 説明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/config/analytics` | Public | 有効なアナリティクス設定（PostHog キー、Sentry DSN、サンプルレート）を取得。アナリティクスがオフの場合（コンパイル時のベイクまたはインスタンスの `analyticsEnabled` 設定のいずれか）、キー、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 バンドル {#features-ai-bundles}
+
+AI 機能バンドル（Docker 環境での AI モデルパッケージのインストール/アンインストール）を管理します。カスタム自動化からツールを有効化する場合は、ツールレベルのインストールエンドポイントを推奨します。一部の AI ツールは複数の共有バンドルを必要とし、このエンドポイントはインストール済みのバンドルをスキップして、不足しているものだけをキューに入れます。
+
+| メソッド | パス | アクセス | 説明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/features` | Auth | すべての機能バンドルとそのインストール状況を一覧表示 |
+| `POST` | `/api/v1/admin/features/:bundleId/install` | Admin（`features:manage`） | 機能バンドルをインストール（非同期、進捗トラッキング用の `jobId` を返す） |
+| `POST` | `/api/v1/admin/tools/:toolId/features/install` | Admin（`features:manage`） | ツールが必要とするすべてのバンドルをインストール。バンドルごとの queued/skipped ステータスを返す |
+| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Admin（`features:manage`） | 機能バンドルをアンインストールし、モデルファイルをクリーンアップ |
+| `GET` | `/api/v1/admin/features/disk-usage` | Admin（`features:manage`） | AI モデルの合計ディスク使用量を取得 |
+| `POST` | `/api/v1/admin/features/import` | Admin（`features:manage`） | オフラインの AI バンドルアーカイブをインポート |
+
+## 管理者操作 {#admin-operations}
+
+オブザーバビリティ、サポート、使用状況レポート、バックアップステータスのための運用エンドポイント。
+
+| メソッド | パス | アクセス | 説明 |
+|--------|------|--------|-------------|
+| `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 メトリクス |
+| `GET` | `/api/v1/admin/support-bundle` | Admin（`system:health`） | 秘匿化された診断サポートバンドル 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 のパーミッションを必要とします。
+
+| メソッド | パス | アクセス | 説明 |
+|--------|------|--------|-------------|
+| `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 ベアラートークンを生成（一度だけ返される） |
+| `DELETE` | `/api/v1/enterprise/scim/token` | Admin（`users:manage`） | 現在の SCIM ベアラートークンを失効 |
+| `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`） | アプリ、ビルド、Node、スキーマのバージョンメタデータを読み取る |
+| `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 ベアラートークンが必要です。
+
+| メソッド | パス | アクセス | 説明 |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/scim/v2/ServiceProviderConfig` | Public | SCIM サーバーの機能 |
+| `GET` | `/api/v1/scim/v2/Schemas` | Public | SCIM スキーマのディスカバリ |
+| `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。
+
+| メソッド | パス | アクセス | 説明 |
+|--------|------|--------|-------------|
+| `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 機能バンドルがインストールされていない（`FEATURE_NOT_INSTALLED`） |
+| 500 | 内部サーバーエラー |