docs: sync api documentation

apps/docs/tools/audio/audio-channels.md

@@ -43,4 +43,4 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/audio-channels \
 - `stereo-to-mono` mixes both channels into a single mono track.
 - `mono-to-stereo` duplicates the mono channel to both left and right.
 - `swap` exchanges the left and right channels of a stereo file.
-- Output format matches the input format.
+- Output usually keeps the input container. AAC input is written as M4A, and unsupported decode-only inputs fall back to MP3.

apps/docs/tools/audio/audio-speed.md

@@ -42,4 +42,4 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/audio-speed \
 
 - A factor of `0.25` plays at quarter speed (4x longer). A factor of `4` plays at quadruple speed (4x shorter).
 - Pitch is preserved while speed changes (time-stretch). Use pitch-shift to adjust pitch independently.
-- Output format matches the input format.
+- Output usually keeps the input container. AAC input is written as M4A, and unsupported decode-only inputs fall back to MP3.

apps/docs/tools/audio/fade-audio.md

@@ -43,4 +43,4 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/fade-audio \
 
 - Set either value to `0` to skip that fade direction. At least one must be greater than 0.
 - The fade duration is clamped to the audio length if it exceeds it.
-- Output format matches the input format.
+- Output usually keeps the input container. AAC input is written as M4A, and unsupported decode-only inputs fall back to MP3.

apps/docs/tools/audio/noise-reduction.md

@@ -42,4 +42,4 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/noise-reduction \
 
 - `light` preserves more detail but removes less noise. `strong` removes more noise but may introduce subtle artifacts.
 - Best results on recordings with consistent background noise (fan hum, air conditioning, static).
-- Output format matches the input format.
+- Output usually keeps the input container. AAC input is written as M4A, and unsupported decode-only inputs fall back to MP3.

apps/docs/tools/audio/normalize-audio.md

@@ -40,4 +40,4 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/normalize-audio \
 - Uses the EBU R128 loudness standard, targeting -16 LUFS.
 - Ideal for podcasts, audiobooks, and broadcast content where consistent loudness is important.
 - The source sample rate is preserved in the output.
-- Output format matches the input format.
+- Output usually keeps the input container. AAC input is written as M4A, and unsupported decode-only inputs fall back to MP3.

apps/docs/tools/audio/pitch-shift.md

@@ -43,4 +43,4 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/pitch-shift \
 - Positive values raise the pitch; negative values lower it.
 - A shift of 12 semitones equals one octave up; -12 equals one octave down.
 - Playback duration stays the same regardless of the shift amount.
-- Output format matches the input format.
+- Output usually keeps the input container. AAC input is written as M4A, and unsupported decode-only inputs fall back to MP3.

apps/docs/tools/audio/reverse-audio.md

@@ -38,4 +38,4 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/reverse-audio \
 ## Notes
 
 - The full audio track is reversed from end to start.
-- Output format matches the input format.
+- Output usually keeps the input container. AAC input is written as M4A, and unsupported decode-only inputs fall back to MP3.

apps/docs/tools/audio/silence-removal.md

@@ -44,4 +44,4 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/silence-removal \
 - A higher (less negative) threshold is more aggressive and removes quieter passages as well as true silence.
 - Increase `minSilenceS` to only strip longer pauses while keeping short natural gaps.
 - Useful for cleaning up podcast recordings, lectures, and voice memos.
-- Output format matches the input format.
+- Output usually keeps the input container. AAC input is written as M4A, and unsupported decode-only inputs fall back to MP3.

apps/docs/tools/audio/transcribe-audio.md

@@ -43,7 +43,7 @@ Track progress via SSE at `GET /api/v1/jobs/{jobId}/progress`. When the job comp
 
 ## Notes
 
-- Requires the **transcription** feature bundle to be installed. Returns `501 Not Implemented` if the bundle is not available.
+- Requires the **transcription** feature bundle to be installed. Returns `501` with code `FEATURE_NOT_INSTALLED`, the missing `feature`, `featureName`, and `estimatedSize` if the bundle is not available.
 - Uses faster-whisper for transcription. Language `auto` detects the spoken language automatically.
 - `srt` and `vtt` formats include timestamps for each segment, suitable for subtitles.
 - `txt` format returns plain text without timestamps.

apps/docs/tools/audio/trim-audio.md

@@ -44,4 +44,4 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/trim-audio \
 - Times are specified in seconds and can include decimals (e.g. `10.5`).
 - The `endS` value must be greater than `startS`.
 - If `endS` exceeds the audio duration, the file is trimmed to the end.
-- Output format matches the input format.
+- Output usually keeps the input container. AAC input is written as M4A, and unsupported decode-only inputs fall back to MP3.

apps/docs/tools/audio/volume-adjust.md

@@ -42,4 +42,4 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/volume-adjust \
 
 - Positive values increase volume; negative values decrease it.
 - Large positive gains can cause clipping. Use normalize-audio for loudness-safe leveling.
-- Output format matches the input format.
+- Output usually keeps the input container. AAC input is written as M4A, and unsupported decode-only inputs fall back to MP3.

apps/docs/tools/conversion-presets.md

@@ -10,7 +10,7 @@ SnapOtter exposes 83 dedicated conversion preset endpoints in addition to the ba
 
 `POST /api/v1/tools/<section>/<presetId>`
 
-Send `multipart/form-data` with a `file` part and optional `settings` JSON string. Fast presets return `200` with a `downloadUrl`; long-running presets return `202` and progress streams from `/api/v1/jobs/<jobId>/progress`.
+Send `multipart/form-data` with a `file` part and optional `settings` JSON string. Presets follow the response contract of the base tool. Fast presets usually return `200` with a `downloadUrl`, but can return `202` if they exceed the synchronous wait window. Video presets and long file/document presets return `202` and progress streams from `/api/v1/jobs/<jobId>/progress`. PDF-to-image presets return page download URLs plus a ZIP URL.
 
 ## Image Presets
 

apps/docs/tools/image/content-aware-resize.md

@@ -51,7 +51,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/content-aware-resize \
 
 ## Notes
 
-- This tool returns a synchronous response (not 202 async). Processing happens inline.
+- This custom route currently returns a synchronous 200 response.
 - Uses the `caire` seam carving library for content-aware resizing.
 - Only reduces dimensions (removes seams). Cannot expand an image beyond its original size.
 - The `protectFaces` option uses AI face detection to mark face regions as high-energy, preventing seams from passing through faces.

apps/docs/tools/image/enhance-faces.md

@@ -12,7 +12,7 @@ Restore and enhance faces in images using AI models (GFPGAN/CodeFormer).
 
 **Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)
 
-**Model bundle:** `upscale-enhance` (4-5 GB)
+**Model bundles:** `upscale-enhance` (5-6 GB) and `face-detection` (200-300 MB)
 
 ## Parameters
 
@@ -74,7 +74,7 @@ data: {"phase":"processing","stage":"Enhancing faces...","percent":60}
 
 ## Notes
 
-- Requires the `upscale-enhance` model bundle to be installed (4-5 GB).
+- Requires both the `upscale-enhance` model bundle (5-6 GB) and the `face-detection` model bundle (200-300 MB).
 - GFPGAN produces more aggressive enhancement; CodeFormer better preserves identity. `auto` selects the best model for the input.
 - Output is always PNG format for maximum quality.
 - A WebP preview is generated alongside the full-resolution output for faster frontend display.

apps/docs/tools/image/image-enhancement.md

@@ -12,7 +12,7 @@ One-click auto-improve with smart analysis. Analyzes the image and applies expos
 
 **Processing:** Synchronous (uses `createToolRoute` factory, returns result directly)
 
-**Model bundle:** None required for basic enhancement. The `upscale-enhance` bundle (4-5 GB) is used only when `deepEnhance` is enabled (for AI noise removal via SCUNet).
+**Model bundle:** None required for basic enhancement. The `upscale-enhance` bundle (5-6 GB) is used only when `deepEnhance` is enabled (for AI noise removal via SCUNet).
 
 ## Parameters
 

apps/docs/tools/image/noise-removal.md

@@ -12,7 +12,7 @@ AI-powered noise and grain removal with multi-tier quality options, using the Py
 
 **Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)
 
-**Model bundle:** `upscale-enhance` (4-5 GB)
+**Model bundle:** `upscale-enhance` (5-6 GB)
 
 ## Parameters
 
@@ -69,7 +69,7 @@ data: {"phase":"processing","stage":"Denoising...","percent":65}
 
 ## Notes
 
-- Requires the `upscale-enhance` model bundle to be installed (4-5 GB).
+- Requires the `upscale-enhance` model bundle to be installed (5-6 GB).
 - Quality tiers trade speed for quality: `quick` is fastest with basic denoising, `maximum` uses the most thorough multi-pass approach.
 - The `detailPreservation` parameter is critical for textured subjects (fabric, hair, foliage). Higher values prevent the denoiser from smoothing away fine detail.
 - When `format` is set to `"original"`, the output format matches the input file format.

apps/docs/tools/image/ocr.md

@@ -10,9 +10,9 @@ Extract text from images using AI-powered optical character recognition. Support
 
 `POST /api/v1/tools/image/ocr`
 
-**Processing:** Synchronous (returns extracted text directly, though progress is reported via SSE if a `clientJobId` is provided)
+**Processing:** Synchronous JSON response. If `clientJobId` is provided, progress is also reported through SSE.
 
-**Model bundle:** `ocr` (3-4 GB)
+**Model bundle:** `ocr` (5-6 GB)
 
 ## Parameters
 
@@ -45,7 +45,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/ocr \
 
 ### Progress (SSE, optional)
 
-If a `clientJobId` is provided, progress events are streamed:
+If a `clientJobId` form field is provided, progress events are streamed:
 
 ```
 event: progress
@@ -54,8 +54,8 @@ data: {"phase":"processing","stage":"Recognizing text...","percent":50}
 
 ## Notes
 
-- Requires the `ocr` model bundle to be installed (3-4 GB).
-- Unlike most AI tools, OCR returns a synchronous JSON response with extracted text (not an image download URL).
+- Requires the `ocr` model bundle to be installed (5-6 GB).
+- OCR returns extracted text directly rather than an image download URL.
 - Uses a fallback chain: if a higher-quality tier crashes (e.g., PaddleOCR segfault), it automatically retries with the next lower tier.
 - If a tier returns empty text without crashing, it also falls back to the next tier.
 - Quality tiers map to engines: `fast` = Tesseract, `balanced` = PaddleOCR v5, `best` = PaddleOCR VL.

apps/docs/tools/image/restore-photo.md

@@ -12,7 +12,7 @@ Fix scratches, tears, and damage on old photos using a multi-step AI pipeline. C
 
 **Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)
 
-**Model bundle:** `photo-restoration` (800 MB - 1 GB)
+**Model bundle:** `photo-restoration` (4-5 GB)
 
 ## Parameters
 
@@ -83,7 +83,7 @@ data: {"phase":"processing","stage":"Enhancing faces...","percent":60}
 
 ## Notes
 
-- Requires the `photo-restoration` model bundle to be installed (800 MB - 1 GB).
+- Requires the `photo-restoration` model bundle to be installed (4-5 GB).
 - The pipeline runs multiple AI steps sequentially: scratch repair, face enhancement (GFPGAN), denoising, and optionally colorization.
 - The `steps` array in the result shows which processing steps were actually executed.
 - `scratchCoverage` is an estimated percentage of the image area that had scratch damage.

apps/docs/tools/image/upscale.md

@@ -12,7 +12,7 @@ AI super-resolution enhancement using Real-ESRGAN. Upscales images 2x-4x while p
 
 **Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)
 
-**Model bundle:** `upscale-enhance` (4-5 GB)
+**Model bundle:** `upscale-enhance` (5-6 GB)
 
 ## Parameters
 
@@ -73,7 +73,7 @@ data: {"phase":"processing","stage":"Upscaling...","percent":60}
 
 ## Notes
 
-- Requires the `upscale-enhance` model bundle to be installed (4-5 GB).
+- Requires the `upscale-enhance` model bundle to be installed (5-6 GB).
 - Uses Real-ESRGAN when available; falls back to Lanczos interpolation if the AI model is unavailable.
 - The `faceEnhance` option applies GFPGAN face restoration during upscaling for better face quality.
 - For non-browser-previewable output formats (HEIC, JXL, TIFF), a WebP preview is generated alongside the main output.

apps/docs/tools/video/convert-video.md

@@ -1,10 +1,10 @@
 ---
-description: Convert videos between MP4, MOV, and WebM.
+description: Convert videos between MP4, MOV, WebM, AVI, and MKV.
 ---
 
 # Convert Video
 
-Convert videos between MP4, MOV, and WebM formats with configurable quality presets.
+Convert videos between MP4, MOV, WebM, AVI, and MKV formats with configurable quality presets.
 
 ## API Endpoint
 
@@ -16,7 +16,7 @@ Accepts multipart form data with a video file and a JSON `settings` field. This
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| format | string | No | `"mp4"` | Output format: `mp4`, `mov`, `webm` |
+| format | string | No | `"mp4"` | Output format: `mp4`, `mov`, `webm`, `avi`, `mkv` |
 | quality | string | No | `"balanced"` | Quality preset: `high`, `balanced`, `small` |
 
 ## Example Request
@@ -40,5 +40,5 @@ curl -X POST http://localhost:1349/api/v1/tools/video/convert-video \
 ## Notes
 
 - The `high` quality preset produces the best visual fidelity but larger files. The `small` preset aggressively compresses for minimum file size.
-- WebM output uses VP9 encoding. MP4 and MOV use H.264.
+- WebM output uses VP9 encoding. MP4 and MOV use H.264. AVI and MKV are available for legacy or archival workflows.
 - Progress updates are available via SSE at `GET /api/v1/jobs/{jobId}/progress` until the job completes.

apps/docs/tools/video/extract-audio.md

@@ -4,7 +4,7 @@ description: Pull the audio track out of a video.
 
 # Extract Audio
 
-Extract the audio track from a video file and save it as MP3, WAV, or M4A.
+Extract the audio track from a video file and save it as MP3, WAV, M4A, or OGG.
 
 ## API Endpoint
 
@@ -16,7 +16,7 @@ Accepts multipart form data with a video file and a JSON `settings` field.
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| format | string | No | `"mp3"` | Output audio format: `mp3`, `wav`, `m4a` |
+| format | string | No | `"mp3"` | Output audio format: `mp3`, `wav`, `m4a`, `ogg` |
 
 ## Example Request
 
@@ -41,5 +41,5 @@ curl -X POST http://localhost:1349/api/v1/tools/video/extract-audio \
 ## Notes
 
 - If the video has no audio track, the request returns a 400 error.
-- MP3 is lossy but widely compatible. WAV is lossless but large. M4A (AAC) offers a good balance of quality and size.
+- MP3 is lossy but widely compatible. WAV is lossless but large. M4A (AAC) offers a good balance of quality and size. OGG is available for open codec workflows.
 - When the source audio is already AAC and the output format is M4A, the audio stream is copied without re-encoding.

apps/docs/tools/video/gif-to-video.md

@@ -1,10 +1,10 @@
 ---
-description: Convert an animated GIF into an MP4 or WebM video.
+description: Convert an animated GIF into an MP4, WebM, or MOV video.
 ---
 
 # GIF to Video
 
-Convert an animated GIF into a compact MP4 or WebM video file.
+Convert an animated GIF into a compact MP4, WebM, or MOV video file.
 
 ## API Endpoint
 
@@ -16,7 +16,7 @@ Accepts multipart form data with a GIF file and a JSON `settings` field.
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| format | string | No | `"mp4"` | Output format: `mp4`, `webm` |
+| format | string | No | `"mp4"` | Output format: `mp4`, `webm`, `mov` |
 
 ## Example Request
 
@@ -42,4 +42,4 @@ curl -X POST http://localhost:1349/api/v1/tools/video/gif-to-video \
 
 - Converting GIF to video typically reduces file size by 80-90% while maintaining the same visual quality.
 - Only animated GIF files are accepted. Static images should use the image Convert tool.
-- MP4 uses H.264 encoding, WebM uses VP9.
+- MP4 and MOV use H.264 encoding, WebM uses VP9.