feat(i18n): 21-language pipeline, landing/docs/API wiring, landing+API translations

Shared Claude Code translation pipeline (scripts/i18n, no API key) plus Astro/VitePress/Scalar i18n wiring. Landing and API reference translated into all 20 languages; docs i18n wiring + English source anchors. The translated docs markdown (apps/docs/<locale>/**, 3,620 files) follows in a companion PR because it exceeds GitHub's per-PR CI file limit.
2026-08-03 07:46:42 +02:00 · 2026-07-11 13:01:55 +08:00
parent 2e91368816
commit 00b651c9f8
353 changed files with 564607 additions and 2594 deletions
@@ -2,7 +2,7 @@
 description: AI engine reference with all local ML tools. Background removal, upscaling, OCR, face detection, photo restoration, and more.
 ---

-# AI Engine Reference
+# AI Engine Reference {#ai-engine-reference}

 The `@snapotter/ai` package bridges Node.js to a **persistent Python sidecar** for all ML operations. The dispatcher process stays alive between requests for fast warm-start performance. NVIDIA CUDA is auto-detected at startup and used when available; otherwise AI tools run on CPU.

@@ -10,7 +10,7 @@ Intel/AMD iGPU acceleration through VA-API, Quick Sync, or OpenCL is not support

 19 Python sidecar AI tools across four modalities (image, audio, video, document), plus 2 tools with optional AI capabilities. All models run locally - no internet required after initial model download.

-## Architecture
+## Architecture {#architecture}

 ```
 Node.js Tool Route
@@ -43,7 +43,7 @@ A separate "docs" dispatcher profile replaces the AI allowlist with document-pro

 **Timeouts:** 300 s default; OCR and BiRefNet background removal get 600 s.

-## Feature Bundles
+## Feature Bundles {#feature-bundles}

 AI models are packaged by shared dependency stack, not one archive per tool. A feature bundle can enable several tools when they use the same model family, Python wheels, or native libraries. This keeps the release Docker image smaller and avoids storing duplicate copies of the same background matting, face detection, OCR, restoration, and speech models.

@@ -72,7 +72,7 @@ A tool is available only when all of its required bundles are installed. Partial

 ---

-## Background Removal
+## Background Removal {#background-removal}

 **Tool route:** `remove-background`  
 **Model:** rembg with BiRefNet (default) or U2-Net variants
@@ -93,7 +93,7 @@ A tool is available only when all of its required bundles are installed. Partial
 | `edgeRefine` | integer (0-3) | - | Edge refinement level |
 | `decontaminate` | boolean | - | Remove color bleed from edges |

-## Background Replace
+## Background Replace {#background-replace}

 **Tool route:** `background-replace`  
 **Model:** rembg / BiRefNet (shared with remove-background)
@@ -110,7 +110,7 @@ Removes the background and replaces it with a solid color or gradient.
 | `feather` | integer (0-20) | `0` | Edge feathering radius |
 | `format` | `"png"` \| `"webp"` | `"png"` | Output format |

-## Blur Background
+## Blur Background {#blur-background}

 **Tool route:** `blur-background`  
 **Model:** rembg / BiRefNet (shared with remove-background)
@@ -123,7 +123,7 @@ Blurs the background while keeping the subject sharp.
 | `feather` | integer (0-20) | `0` | Edge feathering radius |
 | `format` | `"png"` \| `"webp"` | `"png"` | Output format |

-## Image Upscaling
+## Image Upscaling {#image-upscaling}

 **Tool route:** `upscale`  
 **Model:** RealESRGAN (with Lanczos fallback when unavailable)
@@ -137,7 +137,7 @@ Blurs the background while keeping the subject sharp.
 | `format` | string | `"auto"` | Output format override |
 | `quality` | number | `95` | Output quality (1-100) |

-## OCR / Text Extraction
+## OCR / Text Extraction {#ocr-text-extraction}

 **Tool route:** `ocr`  
 **Models:** Tesseract (fast), PaddleOCR PP-OCRv5 (balanced), PaddleOCR-VL 1.5 (best)
@@ -151,7 +151,7 @@ Blurs the background while keeping the subject sharp.

 Returns structured results with bounding boxes, confidence scores, and extracted text blocks.

-## PDF OCR
+## PDF OCR {#pdf-ocr}

 **Tool route:** `ocr-pdf`  
 **Models:** Same tier system as image OCR
@@ -164,7 +164,7 @@ Extracts text from scanned PDF documents using AI-powered OCR, page by page.
 | `language` | string | `"auto"` | Language: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
 | `pages` | string | `"all"` | Page selection: `"all"`, `"1-3"`, `"1,3,5"` |

-## Face / PII Blur
+## Face / PII Blur {#face-pii-blur}

 **Tool route:** `blur-faces`  
 **Model:** MediaPipe face detection
@@ -174,7 +174,7 @@ Extracts text from scanned PDF documents using AI-powered OCR, page by page.
 | `blurRadius` | number (1-100) | `30` | Gaussian blur radius |
 | `sensitivity` | number (0-1) | `0.5` | Detection confidence threshold |

-## Face Enhancement
+## Face Enhancement {#face-enhancement}

 **Tool route:** `enhance-faces`  
 **Models:** GFPGAN, CodeFormer
@@ -186,7 +186,7 @@ Extracts text from scanned PDF documents using AI-powered OCR, page by page.
 | `sensitivity` | number (0-1) | `0.5` | Face detection threshold |
 | `onlyCenterFace` | boolean | `false` | Enhance only the most central face |

-## AI Colorization
+## AI Colorization {#ai-colorization}

 **Tool route:** `colorize`  
 **Model:** DDColor (with OpenCV DNN fallback)
@@ -198,7 +198,7 @@ Converts black-and-white or grayscale photos to full color.
 | `intensity` | number (0-1) | `1.0` | Color saturation strength |
 | `model` | `"auto"` \| `"ddcolor"` \| `"opencv"` | `"auto"` | Model variant |

-## Noise Removal
+## Noise Removal {#noise-removal}

 **Tool route:** `noise-removal`  
 **Model:** SCUNet (tiered denoising pipeline)
@@ -212,7 +212,7 @@ Converts black-and-white or grayscale photos to full color.
 | `format` | string | `"original"` | Output format: `original`, `png`, `jpeg`, `webp`, `avif`, `jxl` |
 | `quality` | number (1-100) | `90` | Output encoding quality |

-## Red Eye Removal
+## Red Eye Removal {#red-eye-removal}

 **Tool route:** `red-eye-removal`

@@ -225,7 +225,7 @@ Detects face landmarks, locates eye regions, and corrects red-channel oversatura
 | `format` | string | - | Output format override (optional) |
 | `quality` | number (1-100) | `90` | Output quality |

-## Photo Restoration
+## Photo Restoration {#photo-restoration}

 **Tool route:** `restore-photo`

@@ -241,20 +241,20 @@ Multi-step pipeline for old or damaged photos: scratch/tear detection and repair
 | `colorize` | boolean | `false` | Colorize after restoration |
 | `colorizeStrength` | number (0-100) | `85` | Colorization intensity |

-## Passport Photo
+## Passport Photo {#passport-photo}

 **Tool route:** `passport-photo`  
 **Models:** MediaPipe face landmarks + BiRefNet background removal

 Two-phase workflow: analyze (detect face + remove background) then generate (crop, resize, tile). Supports 37+ countries across 6 regions.

-### Phase 1: Analyze
+### Phase 1: Analyze {#phase-1-analyze}

 `POST /api/v1/tools/image/passport-photo/analyze`

 Accepts an image file (multipart). Returns face landmark data, a base64 preview, and image dimensions.

-### Phase 2: Generate
+### Phase 2: Generate {#phase-2-generate}

 `POST /api/v1/tools/image/passport-photo/generate`

@@ -279,7 +279,7 @@ Accepts a JSON body with the Phase 1 results plus generation settings:
 | `imageWidth` | number | (required) | Image width from Phase 1 |
 | `imageHeight` | number | (required) | Image height from Phase 1 |

-## Object Erasing (Inpainting)
+## Object Erasing (Inpainting) {#object-erasing-inpainting}

 **Tool route:** `erase-object`  
 **Model:** LaMa via ONNX Runtime
@@ -295,7 +295,7 @@ The mask is sent as a **second file part** (fieldname `mask`), not as base64. Wh

 CUDA-accelerated when an NVIDIA GPU is available.

-## AI Canvas Expand
+## AI Canvas Expand {#ai-canvas-expand}

 **Tool route:** `ai-canvas-expand`  
 **Model:** LaMa-based outpainting
@@ -314,7 +314,7 @@ Expands the canvas of an image in any direction and fills new areas with AI-gene

 At least one extend direction must be greater than 0.

-## Smart Crop
+## Smart Crop {#smart-crop}

 **Tool route:** `smart-crop`  
 **Model:** MediaPipe face detection (face mode only)
@@ -345,7 +345,7 @@ Legacy `mode` values `attention` and `content` are accepted and mapped to `subje
 | `upper-body` | LinkedIn / formal |
 | `half-body` | Full upper body |

-## Transcribe Audio
+## Transcribe Audio {#transcribe-audio}

 **Tool route:** `transcribe-audio`  
 **Model:** faster-whisper
@@ -357,7 +357,7 @@ Converts speech to text. Supports plain text, SRT, and VTT output formats.
 | `language` | string | `"auto"` | Language: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
 | `outputFormat` | `"txt"` \| `"srt"` \| `"vtt"` | `"txt"` | Output format |

-## Auto Subtitles
+## Auto Subtitles {#auto-subtitles}

 **Tool route:** `auto-subtitles`  
 **Model:** faster-whisper (extracts audio from video, then transcribes)
@@ -369,7 +369,7 @@ Generates subtitle files from a video's audio track.
 | `language` | string | `"auto"` | Language: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
 | `format` | `"srt"` \| `"vtt"` | `"srt"` | Output subtitle format |

-## PNG Transparency Fixer
+## PNG Transparency Fixer {#png-transparency-fixer}

 **Tool route:** `transparency-fixer`  
 **Model:** BiRefNet HR-matting (2048x2048 resolution)
@@ -393,11 +393,11 @@ curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \

 ---

-## Tools with Optional AI Capabilities
+## Tools with Optional AI Capabilities {#tools-with-optional-ai-capabilities}

 The following tools are not Python sidecar tools but use AI features when certain options are enabled.

-### Image Enhancement
+### Image Enhancement {#image-enhancement}

 **Tool route:** `image-enhancement`  
 **Engine:** Analysis-based (Sharp histogram and statistics)
@@ -418,7 +418,7 @@ Analyzes the image and applies automatic corrections for exposure, contrast, whi

 An additional analysis endpoint is available at `POST /api/v1/tools/image/image-enhancement/analyze` which returns the detected corrections without applying them.

-### Content-Aware Resize (Seam Carving)
+### Content-Aware Resize (Seam Carving) {#content-aware-resize-seam-carving}

 **Tool route:** `content-aware-resize`  
 **Engine:** Go `caire` binary (not Python - no GPU benefit)
@@ -2,13 +2,13 @@
 description: Image engine operations reference. All Sharp-based image processing operations and their parameters.
 ---

-# Image engine
+# Image engine {#image-engine}

 The `@snapotter/image-engine` package handles all non-AI image operations. It wraps [Sharp](https://sharp.pixelplumbing.com/) and runs entirely in-process with no external dependencies.

-## Operations
+## Operations {#operations}

-### resize
+### resize {#resize}

 Scale an image to specific dimensions or by percentage.

@@ -22,7 +22,7 @@ Scale an image to specific dimensions or by percentage.

 You can set `width`, `height`, or both. If you only set one, the other is calculated to maintain the aspect ratio.

-### crop
+### crop {#crop}

 Cut out a rectangular region from the image.

@@ -34,7 +34,7 @@ Cut out a rectangular region from the image.
 | `height` | number | Height of the crop area |
 | `unit` | string | `px` (default) or `percent` |

-### rotate
+### rotate {#rotate}

 Rotate the image by a given angle.

@@ -43,7 +43,7 @@ Rotate the image by a given angle.
 | `angle` | number | Rotation angle in degrees (0-360) |
 | `background` | string | Fill color for exposed area (default: `#000000`). Only applies to non-90-degree angles. |

-### flip
+### flip {#flip}

 Mirror the image horizontally, vertically, or both. At least one must be true.

@@ -52,7 +52,7 @@ Mirror the image horizontally, vertically, or both. At least one must be true.
 | `horizontal` | boolean | Mirror left to right |
 | `vertical` | boolean | Mirror top to bottom |

-### convert
+### convert {#convert}

 Change the image format.

@@ -63,7 +63,7 @@ Change the image format.

 The first seven formats (`jpg` through `jxl`) are encoded by Sharp in-process. The remaining formats use external encoders at the API layer: `heic`/`heif` via heif-enc, `bmp`/`ico` via ImageMagick, `jp2` via opj_compress, and `qoi` via an inline TypeScript codec.

-### compress
+### compress {#compress}

 Reduce file size while keeping the same format.

@@ -73,7 +73,7 @@ Reduce file size while keeping the same format.
 | `targetSizeBytes` | number | Optional target file size in bytes |
 | `format` | string | Optional format override |

-### strip-metadata
+### strip-metadata {#strip-metadata}

 Remove EXIF, IPTC, XMP, and ICC metadata from the image. With no parameters (or `stripAll: true`), strips everything. Pass individual flags for selective stripping.

@@ -85,7 +85,7 @@ Remove EXIF, IPTC, XMP, and ICC metadata from the image. With no parameters (or
 | `stripIcc` | boolean | Strip ICC color profile |
 | `stripXmp` | boolean | Strip XMP metadata |

-### Color adjustments
+### Color adjustments {#color-adjustments}

 These operations modify the color properties of an image. Each takes a single numeric value.

@@ -95,7 +95,7 @@ These operations modify the color properties of an image. Each takes a single nu
 | `contrast` | `value` | -100 to 100 | Adjust contrast |
 | `saturation` | `value` | -100 to 100 | Adjust color saturation |

-### Color filters
+### Color filters {#color-filters}

 These apply a fixed color transformation. They take no parameters.

@@ -105,7 +105,7 @@ These apply a fixed color transformation. They take no parameters.
 | `sepia` | Apply a sepia tone |
 | `invert` | Invert all colors |

-### Color channels
+### Color channels {#color-channels}

 Adjust individual RGB color channels. Values are multipliers where 100 = no change.

@@ -115,7 +115,7 @@ Adjust individual RGB color channels. Values are multipliers where 100 = no chan
 | `green` | number | Green channel multiplier (0 to 200, 100 = unchanged) |
 | `blue` | number | Blue channel multiplier (0 to 200, 100 = unchanged) |

-### sharpen
+### sharpen {#sharpen}

 Simple sharpening controlled by a single value.

@@ -123,7 +123,7 @@ Simple sharpening controlled by a single value.
 |---|---|---|
 | `value` | number | Sharpening intensity (0 to 100). Mapped to a Gaussian sigma of 0.5-10. |

-### sharpen-advanced
+### sharpen-advanced {#sharpen-advanced}

 Advanced sharpening with three selectable methods and an optional noise-reduction pre-pass.

@@ -145,7 +145,7 @@ Advanced sharpening with three selectable methods and an optional noise-reductio

 Parameters are method-specific. Only supply the ones relevant to the chosen method.

-### color-blindness
+### color-blindness {#color-blindness}

 Simulate a color vision deficiency using a 3x3 color-recombination matrix.

@@ -153,7 +153,7 @@ Simulate a color vision deficiency using a 3x3 color-recombination matrix.
 |---|---|---|
 | `type` | string | One of: `protanopia`, `deuteranopia`, `tritanopia`, `protanomaly`, `deuteranomaly`, `tritanomaly`, `achromatopsia`, `blueConeMonochromacy` |

-### edit-metadata
+### edit-metadata {#edit-metadata}

 Write or remove individual EXIF/IPTC metadata fields without stripping the entire block.

@@ -170,7 +170,7 @@ Write or remove individual EXIF/IPTC metadata fields without stripping the entir

 All parameters are optional. Fields listed in `fieldsToRemove` are deleted from the existing EXIF block. Fields set via the named parameters are written (or overwritten). Binary/unsafe keys like MakerNote are silently ignored.

-## Format detection
+## Format detection {#format-detection}

 The engine detects input formats automatically from file headers, not just file extensions. This means a `.jpg` file that is actually a PNG will be handled correctly. Detection uses a multi-layer approach: magic bytes first, then file extension as fallback.

@@ -178,7 +178,7 @@ SnapOtter supports **55+ input formats** and **13 output formats**, including 23

 See the [Supported Formats](/guide/supported-formats) page for the complete list.

-## Metadata extraction
+## Metadata extraction {#metadata-extraction}

 The `info` tool returns image metadata. See [Image Info](/tools/image/info) for the full field reference.

@@ -2,7 +2,7 @@
 description: Complete REST API reference. Tool endpoints, batch processing, pipelines, file library, authentication, teams, and admin operations.
 ---

-# REST API Reference
+# REST API Reference {#rest-api-reference}

 Interactive API docs with request/response examples are available at [http://localhost:1349/api/docs](http://localhost:1349/api/docs).

@@ -11,11 +11,11 @@ Machine-readable specs:
 - `/llms.txt` - LLM-friendly summary
 - `/llms-full.txt` - Complete LLM-friendly docs

-## Authentication
+## Authentication {#authentication}

 All endpoints require authentication unless `AUTH_ENABLED=false`.

-### Session Token
+### Session Token {#session-token}

 ```bash
 # Login
@@ -31,7 +31,7 @@ curl http://localhost:1349/api/v1/tools/image/resize \

 Sessions expire after 7 days (configurable via `SESSION_DURATION_HOURS`).

-### API Keys
+### API Keys {#api-keys}

 ```bash
 # Create a key (returns key once - store it)
@@ -48,7 +48,7 @@ curl http://localhost:1349/api/v1/tools/image/resize \

 Keys are prefixed `si_` and stored as scrypt hashes - the raw key is shown once and never retrievable again.

-### Auth Endpoints
+### Auth Endpoints {#auth-endpoints}

 | Method | Path | Access | Description |
 |--------|------|--------|-------------|
@@ -75,7 +75,7 @@ Keys are prefixed `si_` and stored as scrypt hashes - the raw key is shown once

 When MFA is enabled for a user, `POST /api/auth/login` returns `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` instead of a session token. Send that `mfaToken` plus a TOTP or recovery code to `/api/auth/mfa/complete`.

-### Permissions
+### Permissions {#permissions}

 | Permission | Admin | User |
 |-----------|:-----:|:----:|
@@ -86,7 +86,7 @@ When MFA is enabled for a user, `POST /api/auth/login` returns `{"requiresMfa":t
 | Manage users & teams | ✓ | - |
 | Manage branding | ✓ | - |

-## Health Check
+## Health Check {#health-check}

 | Method | Path | Access | Description |
 |--------|------|--------|-------------|
@@ -94,7 +94,7 @@ When MFA is enabled for a user, `POST /api/auth/login` returns `{"requiresMfa":t
 | `GET` | `/api/v1/readyz` | Public | Readiness probe. Checks PostgreSQL, Redis, disk space, and S3 when configured. Returns 503 when the instance should not receive traffic. |
 | `GET` | `/api/v1/admin/health` | Admin (`system:health`) | Detailed diagnostics including uptime, storage mode, database status, queue state, and GPU availability. |

-## Using Tools
+## Using Tools {#using-tools}

 Every tool follows the same pattern:

@@ -123,9 +123,9 @@ curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId>/batch \
 - **Any queued tool** can return 202 JSON if it is long-running or exceeds the synchronous wait window: `{"jobId":"...","async":true}`. Connect to SSE for progress, then download when complete (see [Progress Tracking](#progress-tracking)).
 - **Batch** routes return a ZIP archive streamed directly (with `X-Job-Id` header) for tools registered in the generic batch registry.

-## Tools Reference
+## Tools Reference {#tools-reference}

-### Conversion Presets
+### Conversion Presets {#conversion-presets}

 The shared catalog includes 83 dedicated conversion preset endpoints such as `jpg-to-png`, `mov-to-mp4`, `m4a-to-mp3`, `pdf-to-jpg`, and `excel-to-csv`. Presets are first-class tool routes:

@@ -133,7 +133,7 @@ The shared catalog includes 83 dedicated conversion preset endpoints such as `jp

 Each preset locks the output format and delegates to a base tool such as `convert`, `convert-video`, `extract-audio`, `convert-audio`, `image-to-pdf`, `pdf-to-image`, `svg-to-raster`, or `convert-spreadsheet`. See [Conversion Presets](/tools/conversion-presets) for the complete route table and optional settings.

-### Essentials
+### Essentials {#essentials}

 | Tool ID | Name | Key settings |
 |---------|------|-------------|
@@ -143,7 +143,7 @@ Each preset locks the output format and delegates to a base tool such as `conver
 | `convert` | Convert | `format` (jpg/png/webp/avif/tiff/gif/heic/heif), `quality` |
 | `compress` | Compress | `mode` (quality/targetSize), `quality` (1–100), `targetSizeKb` |

-### Optimization
+### Optimization {#optimization}

 | Tool ID | Name | Key settings |
 |---------|------|-------------|
@@ -154,7 +154,7 @@ Each preset locks the output format and delegates to a base tool such as `conver
 | `image-to-pdf` | Image to PDF | `pageSize` (A4/Letter/...), `orientation`, `margin`, `targetSize` ({value, unit}) |
 | `favicon` | Favicon Generator | `padding`, `backgroundColor`, `borderRadius` - generates all standard sizes |

-### Adjustments
+### Adjustments {#adjustments}

 | Tool ID | Name | Key settings |
 |---------|------|-------------|
@@ -166,7 +166,7 @@ Each preset locks the output format and delegates to a base tool such as `conver
 | `pixelate` | Pixelate | `blockSize` (2-128), `region` ({left, top, width, height} for partial pixelation) |
 | `vignette` | Vignette | `strength` (0.1-1), `color` (hex), `radius`, `softness`, `roundness`, `centerX`, `centerY` |

-### AI Tools
+### AI Tools {#ai-tools}

 All AI tools run on your hardware: CPU by default, or NVIDIA CUDA when a supported NVIDIA GPU is available. Intel/AMD iGPU acceleration through VA-API, Quick Sync, or OpenCL is not supported for AI inference today. No internet required.

@@ -191,7 +191,7 @@ All AI tools run on your hardware: CPU by default, or NVIDIA CUDA when a support
 | `blur-background` | Blur Background | rembg (BiRefNet) | `intensity` (1-100), `feather` (0-20), `format` (png/webp) |
 | `ai-canvas-expand` | AI Canvas Expand | LaMa (outpainting) | `extendTop`, `extendRight`, `extendBottom`, `extendLeft` (px), `tier` (fast/balanced/high), `format`, `quality` |

-### Watermark & Overlay
+### Watermark & Overlay {#watermark-overlay}

 | Tool ID | Name | Key settings |
 |---------|------|-------------|
@@ -201,7 +201,7 @@ All AI tools run on your hardware: CPU by default, or NVIDIA CUDA when a support
 | `compose` | Image Composition | `x`, `y`, `opacity`, `blend` - second file is layered on top |
 | `meme-generator` | 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`. Supports template mode (JSON body with `templateId`) or custom image mode (multipart with file). |

-### Utilities
+### Utilities {#utilities}

 | Tool ID | Name | Key settings |
 |---------|------|-------------|
@@ -217,7 +217,7 @@ All AI tools run on your hardware: CPU by default, or NVIDIA CUDA when a support
 | `lqip-placeholder` | LQIP Placeholder | `width` (4-64), `blur`, `strategy` (blur/pixelate/solid), `format` (webp/png/jpeg), `quality` |
 | `barcode-generate` | Barcode Generator | `text`, `type` (code128/ean13/upca/code39/itf14/datamatrix), `scale` (1-8), `includeText` (bool). JSON body, no file upload. |

-### Layout & Composition
+### Layout & Composition {#layout-composition}

 | Tool ID | Name | Key settings |
 |---------|------|-------------|
@@ -230,7 +230,7 @@ All AI tools run on your hardware: CPU by default, or NVIDIA CUDA when a support
 | `image-pad` | 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` | Sprite Sheet | `columns` (1-16), `padding`, `background` (hex), `format` (png/webp/jpeg), `quality` - multi-file (2-64 images) |

-### Format & Conversion
+### Format & Conversion {#format-conversion}

 | Tool ID | Name | Key settings |
 |---------|------|-------------|
@@ -239,7 +239,7 @@ All AI tools run on your hardware: CPU by default, or NVIDIA CUDA when a support
 | `gif-tools` | GIF Tools | `action` (resize/optimize/reverse/speed/extract-frames/rotate/add-text), action-specific params |
 | `gif-webp` | GIF/WebP Converter | `quality` (1-100), `lossless` (bool), `resizePercent` (10-100) |

-### Video Tools
+### Video Tools {#video-tools}

 | Tool ID | Name | Key settings |
 |---------|------|-------------|
@@ -273,7 +273,7 @@ All AI tools run on your hardware: CPU by default, or NVIDIA CUDA when a support
 | `auto-subtitles` | Auto Subtitles (AI) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `format` (srt/vtt) |
 | `extract-audio` | Extract Audio | `format` (mp3/wav/m4a/ogg) |

-### Audio Tools
+### Audio Tools {#audio-tools}

 | Tool ID | Name | Key settings |
 |---------|------|-------------|
@@ -295,7 +295,7 @@ All AI tools run on your hardware: CPU by default, or NVIDIA CUDA when a support
 | `audio-metadata` | Audio Metadata | `strip` (bool), `title`, `artist`, `album` |
 | `transcribe-audio` | Transcribe Audio (AI) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `outputFormat` (txt/srt/vtt) |

-### Document Tools
+### Document Tools {#document-tools}

 | Tool ID | Name | Key settings |
 |---------|------|-------------|
@@ -341,7 +341,7 @@ All AI tools run on your hardware: CPU by default, or NVIDIA CUDA when a support
 | `pdf-to-png` | PDF to PNG | `pages`, `dpi`, `quality`, `colorMode` |
 | `pdf-to-tiff` | PDF to TIFF | `pages`, `dpi`, `quality`, `colorMode` |

-### File Tools
+### File Tools {#file-tools}

 | Tool ID | Name | Key settings |
 |---------|------|-------------|
@@ -357,7 +357,7 @@ All AI tools run on your hardware: CPU by default, or NVIDIA CUDA when a support
 | `create-zip` | Create ZIP | - (multi-file, 2-50 files) |
 | `extract-zip` | Extract ZIP | - (bomb-protected) |

-### HTML to Image
+### HTML to Image {#html-to-image}

 Capture a webpage as an image. Unlike other tools, this endpoint accepts `application/json` instead of multipart form data (no file upload needed).

@@ -395,7 +395,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
 }
 ```

-### Tool Sub-Routes
+### Tool Sub-Routes {#tool-sub-routes}

 Some tools expose additional endpoints beyond the standard `POST /api/v1/tools/<section>/<toolId>`:

@@ -420,7 +420,7 @@ Some tools expose additional endpoints beyond the standard `POST /api/v1/tools/<
 | `POST` | `/api/v1/tools/image/image-enhancement/analyze` | Analyze image quality and return enhancement recommendations |
 | `POST` | `/api/v1/tools/image/optimize-for-web/preview` | Lightweight preview for live parameter tuning. Returns optimized image with size headers. |

-## Batch Processing
+## Batch Processing {#batch-processing}

 Apply a generic batch-enabled tool to multiple files at once. Returns a ZIP archive. Custom multi-file or multi-step routes, such as PDF signing, PDF OCR, and PDF-to-image preset routes, use their own endpoint contract instead of the generic `/batch` route.

@@ -435,9 +435,9 @@ curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \

 Concurrency is controlled by `CONCURRENT_JOBS` (default: auto-detected from CPU cores). `MAX_BATCH_SIZE` limits the number of files per batch (default: 100; set 0 for unlimited).

-## Pipelines
+## Pipelines {#pipelines}

-### Execute a pipeline
+### Execute a pipeline {#execute-a-pipeline}

 ```bash
 # Single file
@@ -460,7 +460,7 @@ curl -X POST http://localhost:1349/api/v1/pipeline/batch \

 Each step's output is the next step's input. Pipelines allow 20 steps by default, configurable via `MAX_PIPELINE_STEPS`. Set `MAX_PIPELINE_STEPS=0` to remove the limit.

-### Save and manage pipelines
+### Save and manage pipelines {#save-and-manage-pipelines}

 | Method | Path | Description |
 |--------|------|-------------|
@@ -469,7 +469,7 @@ Each step's output is the next step's input. Pipelines allow 20 steps by default
 | `DELETE` | `/api/v1/pipeline/:id` | Delete (owner or admin) |
 | `GET` | `/api/v1/pipeline/tools` | List tool IDs valid for pipeline steps |

-## Progress Tracking
+## Progress Tracking {#progress-tracking}

 Long-running jobs, queued tools, batch jobs, and pipelines emit real-time progress via Server-Sent Events. The progress stream is public and keyed by job ID, so clients do not need to send an Authorization header to read it.

@@ -487,7 +487,7 @@ data: {"jobId":"...","type":"batch","status":"processing","completedFiles":2,"to

 You can request cancellation for a queued or running job with `POST /api/v1/jobs/:jobId/cancel`. The response is `{"canceled":true|false}`.

-## File Library
+## File Library {#file-library}

 Persistent file storage with version history.

@@ -509,7 +509,7 @@ Persistent file storage with version history.

 To auto-save a tool result to the library, include `fileId` as a multipart form field referencing an existing library file. The processed result will be saved as a new version.

-## API Key Management
+## API Key Management {#api-key-management}

 | Method | Path | Access | Description |
 |--------|------|--------|-------------|
@@ -517,7 +517,7 @@ To auto-save a tool result to the library, include `fileId` as a multipart form
 | `GET` | `/api/v1/api-keys` | Auth | List keys (name, id, lastUsedAt - not raw key) |
 | `DELETE` | `/api/v1/api-keys/:id` | Auth | Delete key |

-## Teams
+## Teams {#teams}

 | Method | Path | Access | Description |
 |--------|------|--------|-------------|
@@ -526,7 +526,7 @@ To auto-save a tool result to the library, include `fileId` as a multipart form
 | `PUT` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Rename team |
 | `DELETE` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Delete team (cannot delete default team or teams with members) |

-## Settings
+## Settings {#settings}

 Runtime key-value configuration (read by any authenticated user, write by admin only).

@@ -538,7 +538,7 @@ Runtime key-value configuration (read by any authenticated user, write by admin

 Known keys: `disabledTools` (JSON array of tool IDs), `enableExperimentalTools` (bool string), `loginAttemptLimit` (number).

-## Preferences
+## Preferences {#preferences}

 Per-user preferences are separate from instance settings. Any authenticated user can read and update their own preference map.

@@ -547,7 +547,7 @@ Per-user preferences are separate from instance settings. Any authenticated user
 | `GET` | `/api/v1/preferences` | Get the current user's preferences as `{ "preferences": { ... } }` |
 | `PUT` | `/api/v1/preferences` | Upsert one or more preference keys for the current user |

-## Roles
+## Roles {#roles}

 Custom role management with granular permissions.

@@ -560,7 +560,7 @@ Custom role management with granular permissions.

 Available permissions (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
+## Audit Log {#audit-log}

 Admin-only endpoint for reviewing security-relevant actions.

@@ -579,7 +579,7 @@ Query parameters:
 | `from` | Filter entries after this ISO 8601 date |
 | `to` | Filter entries before this ISO 8601 date |

-## Analytics
+## Analytics {#analytics}

 | Method | Path | Access | Description |
 |--------|------|--------|-------------|
@@ -587,7 +587,7 @@ Query parameters:
 | `POST` | `/api/v1/feedback` | Auth | Submit explicit user feedback to the configured PostHog project as `feedback_submitted`. The route respects the analytics gate, rate-limits submissions, strips contact fields unless `contactOk` is true, and never accepts file contents, file names, upload paths, or raw private error text. When analytics is disabled, it returns `{ "ok": true, "accepted": false }`. |
 | `PUT` | `/api/v1/settings` | Admin (`settings:write`) | Set the instance-wide opt-out. Send a JSON body `{ "analyticsEnabled": "false" }` to turn analytics off for everyone, or `"true"` to turn it back on. |

-## Features / AI Bundles
+## Features / AI Bundles {#features-ai-bundles}

 Manage AI feature bundles (install/uninstall AI model packages in the Docker environment). Prefer the tool-level install endpoint when enabling a tool from custom automation: some AI tools need more than one shared bundle, and this endpoint skips already-installed bundles while queuing only the missing ones.

@@ -600,7 +600,7 @@ Manage AI feature bundles (install/uninstall AI model packages in the Docker env
 | `GET` | `/api/v1/admin/features/disk-usage` | Admin (`features:manage`) | Get total disk usage of AI models |
 | `POST` | `/api/v1/admin/features/import` | Admin (`features:manage`) | Import an offline AI bundle archive |

-## Admin Operations
+## Admin Operations {#admin-operations}

 Operational endpoints for observability, support, usage reporting, and backup status.

@@ -614,7 +614,7 @@ Operational endpoints for observability, support, usage reporting, and backup st
 | `GET` | `/api/v1/admin/backup-status` | Admin (`system:health`) | Read last backup metadata and freshness status |
 | `POST` | `/api/v1/admin/backup-status` | Admin (`system:health`) | Record a completed backup (`type`, optional `sizeBytes`, optional `notes`) |

-## Enterprise APIs
+## Enterprise APIs {#enterprise-apis}

 These routes are license-gated by their related enterprise feature. They still require the listed SnapOtter permission.

@@ -644,7 +644,7 @@ These routes are license-gated by their related enterprise feature. They still r
 | `GET` | `/api/v1/admin/migrations/pending` | Admin (`system:health`) | Compare packaged migrations with applied migrations |
 | `GET` | `/api/v1/admin/upgrade-check` | Admin (`system:health`) | Run upgrade readiness checks |

-### SCIM 2.0
+### SCIM 2.0 {#scim-2-0}

 SCIM discovery endpoints are public. User and group endpoints require the SCIM bearer token generated above.

@@ -664,7 +664,7 @@ SCIM discovery endpoints are public. User and group endpoints require the SCIM b
 | `PUT` | `/api/v1/scim/v2/Groups/:id` | SCIM token | Replace a team and group membership |
 | `DELETE` | `/api/v1/scim/v2/Groups/:id` | SCIM token | Delete a team |

-## Meme Templates
+## Meme Templates {#meme-templates}

 Supporting API for the meme generator tool.

@@ -675,7 +675,7 @@ Supporting API for the meme generator tool.
 | `GET` | `/api/v1/meme-templates/thumbs/:filename` | Auth | Serve template thumbnail |
 | `GET` | `/api/v1/meme-templates/fonts/:filename` | Auth | Serve font file used for meme text rendering |

-## Error Responses
+## Error Responses {#error-responses}

 All errors return JSON: