docs: audit all 157 tool pages against live schemas

Reconcile every tool page's parameters, defaults, and response shape against the tool's Zod settings schema and executionHint in code. Notable fixes: color-palette (add count + format params, hex output, median-cut algorithm), favicon (add 5 params, was documented as having none), qr-generate (add logoDataUri), convert (add ppm/eps/tga formats), video-loudnorm (-16 LUFS not -14), smart-crop (async 202 not sync 200), images-to-video (1080x1080 square), and several output-filename and behavior-note corrections. Also normalize API endpoint paths to /api/v1/tools/<id> (no modality segment) and standardize curl examples on the Docker API port 1349. Verified with a clean docs build.
2026-08-03 07:46:42 +02:00 · 2026-06-18 14:12:28 +08:00
parent d24e244af4
commit 8532f3227b
160 changed files with 518 additions and 441 deletions
@@ -240,7 +240,7 @@ Analyzes the image and applies automatic corrections for exposure, contrast, whi
 | `corrections.sharpness` | boolean | true | Apply sharpness correction |
 | `corrections.denoise` | boolean | true | Apply denoising |

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

 ## Content-Aware Resize (Seam Carving)

@@ -279,7 +279,7 @@ Fixes "fake transparent" PNGs where the background was removed but left behind f
 | `outputFormat` | `"png"` \| `"webp"` | `"png"` | Output image format |

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \
+curl -X POST http://localhost:1349/api/v1/tools/transparency-fixer \
  -H "Authorization: Bearer <token>" \
  -F "file=@fake-transparent.png" \
  -F 'settings={"defringe":30,"outputFormat":"png"}'
@@ -25,7 +25,7 @@ curl -X POST http://localhost:1349/api/auth/login \
 # Returns: {"token":"<session-token>"}

 # Use token
-curl http://localhost:1349/api/v1/tools/image/resize \
+curl http://localhost:1349/api/v1/tools/resize \
  -H "Authorization: Bearer <session-token>"
 ```

@@ -42,7 +42,7 @@ curl -X POST http://localhost:1349/api/v1/api-keys \
 # Returns: {"key":"si_<96 hex chars>","id":"...","name":"my-script"}

 # Use the key
-curl http://localhost:1349/api/v1/tools/image/resize \
+curl http://localhost:1349/api/v1/tools/resize \
  -H "Authorization: Bearer si_<your-key>"
 ```

@@ -329,7 +329,7 @@ All AI tools run on your hardware (CPU or NVIDIA GPU). No internet required.

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

-**Endpoint:** `POST /api/v1/tools/image/html-to-image`
+**Endpoint:** `POST /api/v1/tools/html-to-image`

 **Content-Type:** `application/json`

@@ -346,7 +346,7 @@ Capture a webpage as an image. Unlike other tools, this endpoint accepts `applic
 **Example:**

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
+curl -X POST http://localhost:1349/api/v1/tools/html-to-image \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://snapotter.com", "format": "png", "devicePreset": "desktop"}'
@@ -369,24 +369,24 @@ Some tools expose additional endpoints beyond the standard `POST /api/v1/tools/<

 | Method | Path | Description |
 |--------|------|-------------|
-| `POST` | `/api/v1/tools/image/remove-background/effects` | Apply background effects (color/gradient/blur/shadow) without re-running AI. Uses cached mask from initial removal. |
-| `POST` | `/api/v1/tools/image/edit-metadata/inspect` | Read existing EXIF/IPTC/XMP metadata from an image |
-| `POST` | `/api/v1/tools/image/strip-metadata/inspect` | Inspect metadata fields before stripping |
-| `POST` | `/api/v1/tools/image/passport-photo/analyze` | Phase 1: AI face detection + background removal. Returns face landmarks and cached data. |
-| `POST` | `/api/v1/tools/image/passport-photo/generate` | Phase 2: Crop, resize, and tile using cached analysis. No AI re-run. |
-| `POST` | `/api/v1/tools/image/gif-tools/info` | Get GIF metadata (frame count, dimensions, duration) |
-| `POST` | `/api/v1/tools/pdf/pdf-to-image/info` | Get PDF metadata (page count, dimensions) |
-| `POST` | `/api/v1/tools/pdf/pdf-to-image/preview` | Generate a preview of a specific PDF page |
-| `POST` | `/api/v1/tools/image/svg-to-raster/batch` | Batch convert multiple SVGs to raster |
-| `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. |
+| `POST` | `/api/v1/tools/remove-background/effects` | Apply background effects (color/gradient/blur/shadow) without re-running AI. Uses cached mask from initial removal. |
+| `POST` | `/api/v1/tools/edit-metadata/inspect` | Read existing EXIF/IPTC/XMP metadata from an image |
+| `POST` | `/api/v1/tools/strip-metadata/inspect` | Inspect metadata fields before stripping |
+| `POST` | `/api/v1/tools/passport-photo/analyze` | Phase 1: AI face detection + background removal. Returns face landmarks and cached data. |
+| `POST` | `/api/v1/tools/passport-photo/generate` | Phase 2: Crop, resize, and tile using cached analysis. No AI re-run. |
+| `POST` | `/api/v1/tools/gif-tools/info` | Get GIF metadata (frame count, dimensions, duration) |
+| `POST` | `/api/v1/tools/pdf-to-image/info` | Get PDF metadata (page count, dimensions) |
+| `POST` | `/api/v1/tools/pdf-to-image/preview` | Generate a preview of a specific PDF page |
+| `POST` | `/api/v1/tools/svg-to-raster/batch` | Batch convert multiple SVGs to raster |
+| `POST` | `/api/v1/tools/image-enhancement/analyze` | Analyze image quality and return enhancement recommendations |
+| `POST` | `/api/v1/tools/optimize-for-web/preview` | Lightweight preview for live parameter tuning. Returns optimized image with size headers. |

 ## Batch Processing

 Apply any tool to multiple files at once. Returns a ZIP archive.

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \
+curl -X POST http://localhost:1349/api/v1/tools/compress/batch \
  -H "Authorization: Bearer <token>" \
  -F "files=@a.jpg" \
  -F "files=@b.jpg" \
@@ -139,7 +139,7 @@ Every file you process can be saved to your **Files** library. SnapOtter tracks
 Every tool is accessible via HTTP:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/resize \
+curl -X POST http://localhost:1349/api/v1/tools/resize \
  -H "Authorization: Bearer si_<your-api-key>" \
  -F "file=@photo.jpg" \
  -F 'settings={"width":800,"height":600,"fit":"cover"}'
@@ -8,7 +8,7 @@ Convert audio between mono and stereo layouts, or swap the left and right channe

 ## API Endpoint

-`POST /api/v1/tools/audio/audio-channels`
+`POST /api/v1/tools/audio-channels`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -21,7 +21,7 @@ Accepts multipart form data with an audio file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/audio-channels \
+curl -X POST http://localhost:1349/api/v1/tools/audio-channels \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"mode": "stereo-to-mono"}'
@@ -8,7 +8,7 @@ View, edit, or strip audio metadata tags such as title, artist, and album (ID3 a

 ## API Endpoint

-`POST /api/v1/tools/audio/audio-metadata`
+`POST /api/v1/tools/audio-metadata`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -26,7 +26,7 @@ Accepts multipart form data with an audio file and a JSON `settings` field.
 Edit metadata tags:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/audio-metadata \
+curl -X POST http://localhost:1349/api/v1/tools/audio-metadata \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"title": "My Song", "artist": "Artist Name", "album": "Album Name"}'
@@ -35,7 +35,7 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/audio-metadata \
 Strip all metadata:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/audio-metadata \
+curl -X POST http://localhost:1349/api/v1/tools/audio-metadata \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"strip": true}'
@@ -8,7 +8,7 @@ Speed up or slow down audio playback by applying a speed multiplier.

 ## API Endpoint

-`POST /api/v1/tools/audio/audio-speed`
+`POST /api/v1/tools/audio-speed`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -21,7 +21,7 @@ Accepts multipart form data with an audio file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/audio-speed \
+curl -X POST http://localhost:1349/api/v1/tools/audio-speed \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"factor": 2}'
@@ -41,5 +41,5 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/audio-speed \
 ## Notes

 - A factor of `0.25` plays at quarter speed (4x longer). A factor of `4` plays at quadruple speed (4x shorter).
- Pitch changes proportionally with speed. Use pitch-shift if you need to adjust pitch independently.
+- Pitch is preserved while speed changes (time-stretch). Use pitch-shift to adjust pitch independently.
 - Output format matches the input format.
@@ -8,7 +8,7 @@ Convert audio files between common formats including MP3, WAV, OGG, FLAC, and M4

 ## API Endpoint

-`POST /api/v1/tools/audio/convert-audio`
+`POST /api/v1/tools/convert-audio`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -22,7 +22,7 @@ Accepts multipart form data with an audio file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/convert-audio \
+curl -X POST http://localhost:1349/api/v1/tools/convert-audio \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"format": "flac", "bitrateKbps": 256}'
@@ -8,7 +8,7 @@ Add fade-in and fade-out effects to the beginning and end of an audio file.

 ## API Endpoint

-`POST /api/v1/tools/audio/fade-audio`
+`POST /api/v1/tools/fade-audio`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -22,7 +22,7 @@ Accepts multipart form data with an audio file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/fade-audio \
+curl -X POST http://localhost:1349/api/v1/tools/fade-audio \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"fadeInS": 2, "fadeOutS": 3}'
@@ -41,6 +41,6 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/fade-audio \

 ## Notes

- Set either value to `0` to skip that fade direction.
- The fade duration should not exceed the audio length.
+- 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.
@@ -8,7 +8,7 @@ Combine two or more audio files into a single sequential track, concatenated in

 ## API Endpoint

-`POST /api/v1/tools/audio/merge-audio`
+`POST /api/v1/tools/merge-audio`

 Accepts multipart form data with multiple audio files and a JSON `settings` field.

@@ -21,7 +21,7 @@ Accepts multipart form data with multiple audio files and a JSON `settings` fiel
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/merge-audio \
+curl -X POST http://localhost:1349/api/v1/tools/merge-audio \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@intro.mp3" \
  -F "file=@main.mp3" \
@@ -8,7 +8,7 @@ Reduce background noise in an audio file using FFT-based denoising with selectab

 ## API Endpoint

-`POST /api/v1/tools/audio/noise-reduction`
+`POST /api/v1/tools/noise-reduction`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -21,7 +21,7 @@ Accepts multipart form data with an audio file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/noise-reduction \
+curl -X POST http://localhost:1349/api/v1/tools/noise-reduction \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"strength": "strong"}'
@@ -8,7 +8,7 @@ Even out audio loudness to broadcast standard levels using EBU R128 normalizatio

 ## API Endpoint

-`POST /api/v1/tools/audio/normalize-audio`
+`POST /api/v1/tools/normalize-audio`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -19,7 +19,7 @@ This tool has no configurable parameters. It applies EBU R128 loudness normaliza
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/normalize-audio \
+curl -X POST http://localhost:1349/api/v1/tools/normalize-audio \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3"
 ```
@@ -8,7 +8,7 @@ Raise or lower the pitch of an audio file by a number of semitones without chang

 ## API Endpoint

-`POST /api/v1/tools/audio/pitch-shift`
+`POST /api/v1/tools/pitch-shift`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -21,7 +21,7 @@ Accepts multipart form data with an audio file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/pitch-shift \
+curl -X POST http://localhost:1349/api/v1/tools/pitch-shift \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"semitones": -5}'
@@ -8,7 +8,7 @@ Reverse an audio file so it plays backwards.

 ## API Endpoint

-`POST /api/v1/tools/audio/reverse-audio`
+`POST /api/v1/tools/reverse-audio`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -19,7 +19,7 @@ This tool has no configurable parameters. The entire audio file is reversed.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/reverse-audio \
+curl -X POST http://localhost:1349/api/v1/tools/reverse-audio \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3"
 ```
@@ -8,7 +8,7 @@ Create a ringtone clip (.m4r) from any audio file by selecting a start time and

 ## API Endpoint

-`POST /api/v1/tools/audio/ringtone-maker`
+`POST /api/v1/tools/ringtone-maker`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -22,7 +22,7 @@ Accepts multipart form data with an audio file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/ringtone-maker \
+curl -X POST http://localhost:1349/api/v1/tools/ringtone-maker \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"startS": 15, "durationS": 20}'
@@ -8,7 +8,7 @@ Detect and remove silent sections from an audio file based on a configurable thr

 ## API Endpoint

-`POST /api/v1/tools/audio/silence-removal`
+`POST /api/v1/tools/silence-removal`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -22,7 +22,7 @@ Accepts multipart form data with an audio file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/silence-removal \
+curl -X POST http://localhost:1349/api/v1/tools/silence-removal \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"thresholdDb": -45, "minSilenceS": 1}'
@@ -8,7 +8,7 @@ Split an audio file into segments by fixed time intervals, equal parts, or autom

 ## API Endpoint

-`POST /api/v1/tools/audio/split-audio`
+`POST /api/v1/tools/split-audio`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -27,7 +27,7 @@ Accepts multipart form data with an audio file and a JSON `settings` field.
 Split into 30-second segments:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/split-audio \
+curl -X POST http://localhost:1349/api/v1/tools/split-audio \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"mode": "time", "segmentS": 30}'
@@ -36,7 +36,7 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/split-audio \
 Split by silence detection:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/split-audio \
+curl -X POST http://localhost:1349/api/v1/tools/split-audio \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"mode": "silence", "thresholdDb": -35, "minSilenceS": 0.5}'
@@ -47,7 +47,7 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/split-audio \
 ```json
 {
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/audio-segments.zip",
+  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/audio_parts.zip",
  "originalSize": 4500000,
  "processedSize": 4600000
 }
@@ -57,5 +57,5 @@ curl -X POST http://localhost:1349/api/v1/tools/audio/split-audio \

 - The `downloadUrl` points to a ZIP archive containing all segments.
 - Only the parameters relevant to the chosen `mode` are used; others are ignored.
- Segment filenames are numbered sequentially (e.g. `001.mp3`, `002.mp3`).
+- Segment filenames are numbered sequentially (e.g. `part-000.mp3`, `part-001.mp3`).
 - Output format matches the input format.
@@ -8,7 +8,7 @@ Convert speech to text using AI-powered transcription (faster-whisper). Supports

 ## API Endpoint

-`POST /api/v1/tools/audio/transcribe-audio`
+`POST /api/v1/tools/transcribe-audio`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -22,7 +22,7 @@ Accepts multipart form data with an audio file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/transcribe-audio \
+curl -X POST http://localhost:1349/api/v1/tools/transcribe-audio \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"language": "en", "outputFormat": "srt"}'
@@ -8,7 +8,7 @@ Cut a section out of an audio file by specifying start and end times in seconds.

 ## API Endpoint

-`POST /api/v1/tools/audio/trim-audio`
+`POST /api/v1/tools/trim-audio`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -22,7 +22,7 @@ Accepts multipart form data with an audio file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/trim-audio \
+curl -X POST http://localhost:1349/api/v1/tools/trim-audio \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"startS": 10, "endS": 45}'
@@ -8,7 +8,7 @@ Increase or decrease the volume of an audio file by applying a fixed gain in dec

 ## API Endpoint

-`POST /api/v1/tools/audio/volume-adjust`
+`POST /api/v1/tools/volume-adjust`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -21,7 +21,7 @@ Accepts multipart form data with an audio file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/volume-adjust \
+curl -X POST http://localhost:1349/api/v1/tools/volume-adjust \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"gainDb": 6}'
@@ -8,7 +8,7 @@ Generate a waveform visualization as a PNG image from an audio file, with config

 ## API Endpoint

-`POST /api/v1/tools/audio/waveform-image`
+`POST /api/v1/tools/waveform-image`

 Accepts multipart form data with an audio file and a JSON `settings` field.

@@ -23,7 +23,7 @@ Accepts multipart form data with an audio file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/audio/waveform-image \
+curl -X POST http://localhost:1349/api/v1/tools/waveform-image \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@audio.mp3" \
  -F 'settings={"width": 1920, "height": 400, "color": "#e07832"}'
@@ -8,7 +8,7 @@ Create bar, line, or pie charts from CSV or JSON data. Returns a PNG image of th

 ## API Endpoint

-`POST /api/v1/tools/data/chart-maker`
+`POST /api/v1/tools/chart-maker`

 Accepts multipart form data with a CSV or JSON file and a JSON `settings` field.

@@ -24,7 +24,7 @@ Accepts multipart form data with a CSV or JSON file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/data/chart-maker \
+curl -X POST http://localhost:1349/api/v1/tools/chart-maker \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@sales.csv" \
  -F 'settings={"kind": "line", "title": "Monthly Sales", "width": 960, "height": 540}'
@@ -35,7 +35,7 @@ curl -X POST http://localhost:1349/api/v1/tools/data/chart-maker \
 ```json
 {
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/sales.png",
+  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/sales_chart.png",
  "originalSize": 1024,
  "processedSize": 48500
 }
@@ -44,6 +44,7 @@ curl -X POST http://localhost:1349/api/v1/tools/data/chart-maker \
 ## Notes

 - Input must be a `.csv` or `.json` file. CSV files should have a header row with column names.
- The first column is used as the category axis; remaining numeric columns become data series.
- JSON input should be an array of objects with consistent keys.
+- The first column is used as the category label; the second column must be numeric and provides the data values. Only two columns are used.
+- JSON input should be an array of `{label, value}` objects, or a plain object whose keys become labels and values become data points.
+- Maximum 100 data points. All values must be zero or greater.
 - Output is always a PNG image regardless of input format.
@@ -8,7 +8,7 @@ Bundle multiple files of any type into a single ZIP archive. Duplicate filenames

 ## API Endpoint

-`POST /api/v1/tools/data/create-zip`
+`POST /api/v1/tools/create-zip`

 Accepts multipart form data with two or more files. No settings field is required.

@@ -19,7 +19,7 @@ This tool has no configurable parameters. Upload 2--50 files of any type to bund
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/data/create-zip \
+curl -X POST http://localhost:1349/api/v1/tools/create-zip \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@report.pdf" \
  -F "file=@data.csv" \
@@ -8,7 +8,7 @@ Convert between CSV and Excel (XLSX) formats in both directions. Upload a CSV or

 ## API Endpoint

-`POST /api/v1/tools/data/csv-excel`
+`POST /api/v1/tools/csv-excel`

 Accepts multipart form data with a CSV, TSV, or XLSX file and a JSON `settings` field.

@@ -23,7 +23,7 @@ Accepts multipart form data with a CSV, TSV, or XLSX file and a JSON `settings`
 CSV to Excel:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/data/csv-excel \
+curl -X POST http://localhost:1349/api/v1/tools/csv-excel \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@data.csv" \
  -F 'settings={"sheet": 1}'
@@ -32,7 +32,7 @@ curl -X POST http://localhost:1349/api/v1/tools/data/csv-excel \
 Excel to CSV:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/data/csv-excel \
+curl -X POST http://localhost:1349/api/v1/tools/csv-excel \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@report.xlsx" \
  -F 'settings={"sheet": 2}'
@@ -8,7 +8,7 @@ Convert between CSV and JSON formats in both directions. Upload a CSV or TSV fil

 ## API Endpoint

-`POST /api/v1/tools/data/csv-json`
+`POST /api/v1/tools/csv-json`

 Accepts multipart form data with a CSV, TSV, or JSON file and a JSON `settings` field.

@@ -23,7 +23,7 @@ Accepts multipart form data with a CSV, TSV, or JSON file and a JSON `settings`
 CSV to JSON:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/data/csv-json \
+curl -X POST http://localhost:1349/api/v1/tools/csv-json \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@users.csv" \
  -F 'settings={"pretty": true}'
@@ -32,7 +32,7 @@ curl -X POST http://localhost:1349/api/v1/tools/data/csv-json \
 JSON to CSV:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/data/csv-json \
+curl -X POST http://localhost:1349/api/v1/tools/csv-json \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@users.json" \
  -F 'settings={}'
@@ -8,7 +8,7 @@ Safely extract files from a ZIP archive. Single-file archives return the contain

 ## API Endpoint

-`POST /api/v1/tools/data/extract-zip`
+`POST /api/v1/tools/extract-zip`

 Accepts multipart form data with a ZIP file. No settings field is required.

@@ -19,7 +19,7 @@ This tool has no configurable parameters. Upload a `.zip` file to extract.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/data/extract-zip \
+curl -X POST http://localhost:1349/api/v1/tools/extract-zip \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@archive.zip"
 ```
@@ -29,7 +29,7 @@ curl -X POST http://localhost:1349/api/v1/tools/data/extract-zip \
 ```json
 {
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/archive.zip",
+  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/archive_extracted.zip",
  "originalSize": 2800000,
  "processedSize": 3500000
 }
@@ -8,7 +8,7 @@ Convert between JSON and XML formats in both directions. Upload a JSON file to g

 ## API Endpoint

-`POST /api/v1/tools/data/json-xml`
+`POST /api/v1/tools/json-xml`

 Accepts multipart form data with a JSON or XML file and a JSON `settings` field.

@@ -23,7 +23,7 @@ Accepts multipart form data with a JSON or XML file and a JSON `settings` field.
 JSON to XML:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/data/json-xml \
+curl -X POST http://localhost:1349/api/v1/tools/json-xml \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@config.json" \
  -F 'settings={"pretty": true}'
@@ -32,7 +32,7 @@ curl -X POST http://localhost:1349/api/v1/tools/data/json-xml \
 XML to JSON:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/data/json-xml \
+curl -X POST http://localhost:1349/api/v1/tools/json-xml \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@config.xml" \
  -F 'settings={"pretty": true}'
@@ -8,7 +8,7 @@ Combine multiple CSV or TSV files with matching columns into a single merged fil

 ## API Endpoint

-`POST /api/v1/tools/data/merge-csvs`
+`POST /api/v1/tools/merge-csvs`

 Accepts multipart form data with two or more CSV files. No settings field is required.

@@ -19,7 +19,7 @@ This tool has no configurable parameters. Upload 2--20 CSV or TSV files with mat
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/data/merge-csvs \
+curl -X POST http://localhost:1349/api/v1/tools/merge-csvs \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@january.csv" \
  -F "file=@february.csv" \
@@ -8,7 +8,7 @@ Split a large CSV or TSV file into smaller files by row count. Returns a ZIP arc

 ## API Endpoint

-`POST /api/v1/tools/data/split-csv`
+`POST /api/v1/tools/split-csv`

 Accepts multipart form data with a CSV file and a JSON `settings` field.

@@ -22,7 +22,7 @@ Accepts multipart form data with a CSV file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/data/split-csv \
+curl -X POST http://localhost:1349/api/v1/tools/split-csv \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@large-dataset.csv" \
  -F 'settings={"rowsPerFile": 500, "keepHeader": true}'
@@ -33,7 +33,7 @@ curl -X POST http://localhost:1349/api/v1/tools/data/split-csv \
 ```json
 {
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/large-dataset-split.zip",
+  "downloadUrl": "/api/v1/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890/large-dataset_parts.zip",
  "originalSize": 1048576,
  "processedSize": 1050000
 }
@@ -8,7 +8,7 @@ Extract repeating elements from an XML file into a flat CSV table. The tool auto

 ## API Endpoint

-`POST /api/v1/tools/data/xml-to-csv`
+`POST /api/v1/tools/xml-to-csv`

 Accepts multipart form data with an XML file. No settings field is required.

@@ -19,7 +19,7 @@ This tool has no configurable parameters. The repeating element is auto-detected
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/data/xml-to-csv \
+curl -X POST http://localhost:1349/api/v1/tools/xml-to-csv \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@catalog.xml"
 ```
@@ -8,7 +8,7 @@ Convert between YAML and JSON formats in both directions. Upload a YAML file to

 ## API Endpoint

-`POST /api/v1/tools/data/yaml-json`
+`POST /api/v1/tools/yaml-json`

 Accepts multipart form data with a YAML or JSON file. No settings field is required.

@@ -21,7 +21,7 @@ This tool has no configurable parameters. The conversion direction is determined
 YAML to JSON:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/data/yaml-json \
+curl -X POST http://localhost:1349/api/v1/tools/yaml-json \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@config.yaml"
 ```
@@ -29,7 +29,7 @@ curl -X POST http://localhost:1349/api/v1/tools/data/yaml-json \
 JSON to YAML:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/data/yaml-json \
+curl -X POST http://localhost:1349/api/v1/tools/yaml-json \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@config.json"
 ```
@@ -49,4 +49,4 @@ curl -X POST http://localhost:1349/api/v1/tools/data/yaml-json \

 - Conversion direction is auto-detected from the input file extension: `.yaml` or `.yml` produces `.json`, and `.json` produces `.yaml`.
 - Both `.yaml` and `.yml` extensions are accepted.
- Multi-document YAML files (separated by `---`) are supported.
+- Only the first document in a multi-document YAML file is converted; additional documents separated by `---` are ignored.
@@ -8,7 +8,7 @@ Comprehensive color adjustment tool combining brightness, contrast, exposure, sa

 ## API Endpoint

-`POST /api/v1/tools/image/adjust-colors`
+`POST /api/v1/tools/adjust-colors`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -32,7 +32,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/adjust-colors \
+curl -X POST http://localhost:1349/api/v1/tools/adjust-colors \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"brightness": 20, "contrast": 10, "saturation": -30, "effect": "none"}'
@@ -41,7 +41,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/adjust-colors \
 Apply a warm vintage look:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/adjust-colors \
+curl -X POST http://localhost:1349/api/v1/tools/adjust-colors \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"temperature": 40, "saturation": -15, "contrast": 10, "effect": "sepia"}'
@@ -64,5 +64,5 @@ curl -X POST http://localhost:1349/api/v1/tools/image/adjust-colors \
 - Adjustments are applied in this order: brightness, contrast, exposure, saturation/hue, temperature/tint, sharpness, channels, effects.
 - Temperature uses a 3x3 color recombination matrix on the blue-orange and green-magenta axes.
 - Exposure maps to Sharp's gamma function (positive brightens midtones, negative darkens them).
- This endpoint also responds at the legacy paths `/api/v1/tools/brightness-contrast`, `/api/v1/tools/saturation`, `/api/v1/tools/color-channels`, and `/api/v1/tools/color-effects`.
+- This endpoint also responds at the legacy paths `/api/v1/tools/brightness-contrast`, `/api/v1/tools/saturation`, `/api/v1/tools/color-channels`, and `/api/v1/tools/color-effects`. All use the same schema.
 - Output format matches the input format. HEIC, RAW, PSD, and SVG inputs are automatically decoded before processing.
@@ -4,7 +4,7 @@ Expand the canvas of an image with AI-powered fill (outpainting). Extends the im

 ## API Endpoint

-`POST /api/v1/tools/image/ai-canvas-expand`
+`POST /api/v1/tools/ai-canvas-expand`

 **Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)

@@ -28,7 +28,7 @@ At least one extend direction must be greater than 0.
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/ai-canvas-expand \
+curl -X POST http://localhost:1349/api/v1/tools/ai-canvas-expand \
  -F "file=@photo.jpg" \
  -F 'settings={"extendTop":200,"extendBottom":200,"extendLeft":100,"extendRight":100,"tier":"balanced"}'
 ```
@@ -8,7 +8,7 @@ Replace the background of an image with a solid color or gradient. The AI model

 ## API Endpoint

-`POST /api/v1/tools/image/background-replace`
+`POST /api/v1/tools/background-replace`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -27,7 +27,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/background-replace \
+curl -X POST http://localhost:1349/api/v1/tools/background-replace \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"backgroundType": "color", "color": "#2563eb", "feather": 2}'
@@ -8,7 +8,7 @@ Generate barcode images from text input. Supports Code 128, EAN-13, UPC-A, Code

 ## API Endpoint

-`POST /api/v1/tools/image/barcode-generate`
+`POST /api/v1/tools/barcode-generate`

 Accepts an `application/json` body (not multipart). The barcode is generated from the provided text, not from an uploaded file.

@@ -24,7 +24,7 @@ Accepts an `application/json` body (not multipart). The barcode is generated fro
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/barcode-generate \
+curl -X POST http://localhost:1349/api/v1/tools/barcode-generate \
  -H "Authorization: Bearer si_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"text": "5901234123457", "type": "ean13", "scale": 4}'
@@ -8,7 +8,7 @@ Scan uploaded images for all types of barcodes and QR codes. Returns decoded tex

 ## API Endpoint

-`POST /api/v1/tools/image/barcode-read`
+`POST /api/v1/tools/barcode-read`

 Accepts multipart form data with an image file and an optional JSON `settings` field.

@@ -21,7 +21,7 @@ Accepts multipart form data with an image file and an optional JSON `settings` f
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/barcode-read \
+curl -X POST http://localhost:1349/api/v1/tools/barcode-read \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@receipt.jpg" \
  -F 'settings={"tryHarder": true}'
@@ -4,7 +4,7 @@ Add gradient backgrounds, device frames, shadows, watermarks, and social media s

 ## API Endpoint

-`POST /api/v1/tools/image/beautify`
+`POST /api/v1/tools/beautify`

 ## Parameters

@@ -33,7 +33,7 @@ Add gradient backgrounds, device frames, shadows, watermarks, and social media s
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/beautify \
+curl -X POST http://localhost:1349/api/v1/tools/beautify \
  -F "file=@screenshot.png" \
  -F 'settings={"backgroundType":"linear-gradient","gradientStops":[{"color":"#667eea","position":0},{"color":"#764ba2","position":100}],"gradientAngle":135,"padding":64,"borderRadius":12,"shadowPreset":"medium","frame":"macos-dark","socialPreset":"twitter"}'
 ```
@@ -41,7 +41,7 @@ curl -X POST http://localhost:13490/api/v1/tools/image/beautify \
 ### With Background Image

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/beautify \
+curl -X POST http://localhost:1349/api/v1/tools/beautify \
  -F "file=@screenshot.png" \
  -F "backgroundImage=@bg-texture.jpg" \
  -F 'settings={"backgroundType":"image","padding":80,"borderRadius":16,"shadowPreset":"dramatic"}'
@@ -8,7 +8,7 @@ Blur the background of an image while keeping the subject sharp. The AI model is

 ## API Endpoint

-`POST /api/v1/tools/image/blur-background`
+`POST /api/v1/tools/blur-background`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -23,7 +23,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/blur-background \
+curl -X POST http://localhost:1349/api/v1/tools/blur-background \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"intensity": 75, "feather": 3}'
@@ -4,7 +4,7 @@ Auto-detect and blur faces in images using AI-powered face detection (MediaPipe)

 ## API Endpoint

-`POST /api/v1/tools/image/blur-faces`
+`POST /api/v1/tools/blur-faces`

 **Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)

@@ -21,7 +21,7 @@ Auto-detect and blur faces in images using AI-powered face detection (MediaPipe)
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/blur-faces \
+curl -X POST http://localhost:1349/api/v1/tools/blur-faces \
  -F "file=@group-photo.jpg" \
  -F 'settings={"blurRadius":40,"sensitivity":0.3}'
 ```
@@ -4,7 +4,7 @@ Add borders, padding, rounded corners, and drop shadows to images. The tool appl

 ## API Endpoint

-`POST /api/v1/tools/image/border`
+`POST /api/v1/tools/border`

 ## Parameters

@@ -25,7 +25,7 @@ Add borders, padding, rounded corners, and drop shadows to images. The tool appl
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/border \
+curl -X POST http://localhost:1349/api/v1/tools/border \
  -F "file=@photo.jpg" \
  -F 'settings={"borderWidth":20,"borderColor":"#333333","cornerRadius":16,"shadow":true,"shadowBlur":25,"shadowOpacity":50}'
 ```
@@ -8,7 +8,7 @@ Rename multiple files using a pattern template with placeholders for index, padd

 ## API Endpoint

-`POST /api/v1/tools/image/bulk-rename`
+`POST /api/v1/tools/bulk-rename`

 Accepts multipart form data with multiple files and a JSON `settings` field.

@@ -32,7 +32,7 @@ The original file extension is always preserved.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/bulk-rename \
+curl -X POST http://localhost:1349/api/v1/tools/bulk-rename \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo1.jpg" \
  -F "file=@photo2.jpg" \
@@ -45,7 +45,7 @@ This produces: `vacation-1.jpg`, `vacation-2.jpg`, `vacation-3.jpg`
 Using original filename:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/bulk-rename \
+curl -X POST http://localhost:1349/api/v1/tools/bulk-rename \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@IMG_001.jpg" \
  -F "file=@IMG_002.jpg" \
@@ -8,7 +8,7 @@ Crop an image to a centered circle with transparent corners. Supports adjustable

 ## API Endpoint

-`POST /api/v1/tools/image/circle-crop`
+`POST /api/v1/tools/circle-crop`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -27,7 +27,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/circle-crop \
+curl -X POST http://localhost:1349/api/v1/tools/circle-crop \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"zoom": 1.2, "borderWidth": 4, "borderColor": "#333333"}'
@@ -4,7 +4,7 @@ Combine multiple images into beautiful grid collages with 25+ templates. Support

 ## API Endpoint

-`POST /api/v1/tools/image/collage`
+`POST /api/v1/tools/collage`

 ## Parameters

@@ -55,7 +55,7 @@ Combine multiple images into beautiful grid collages with 25+ templates. Support
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/collage \
+curl -X POST http://localhost:1349/api/v1/tools/collage \
  -F "file=@photo1.jpg" \
  -F "file=@photo2.jpg" \
  -F "file=@photo3.jpg" \
@@ -8,7 +8,7 @@ Simulate color vision deficiency (CVD) to preview how images appear to people wi

 ## API Endpoint

-`POST /api/v1/tools/image/color-blindness`
+`POST /api/v1/tools/color-blindness`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -34,7 +34,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/color-blindness \
+curl -X POST http://localhost:1349/api/v1/tools/color-blindness \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@design.png" \
  -F 'settings={"simulationType": "deuteranopia"}'
@@ -8,24 +8,24 @@ Extract the dominant colors from an image and return them as hex color values. U

 ## API Endpoint

-`POST /api/v1/tools/image/color-palette`
+`POST /api/v1/tools/color-palette`

-Accepts multipart form data with an image file. No settings field is needed.
+Accepts multipart form data with an image file and an optional JSON `settings` field.

 ## Parameters

-This tool has no configurable parameters. Simply upload the image file.
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| file | file | Yes | The image to extract colors from |
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| count | integer | No | `8` | Number of colors to extract (2-16) |
+| format | string | No | `"hex"` | Color format: `hex`, `rgb`, `hsl` |

 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/color-palette \
+curl -X POST http://localhost:1349/api/v1/tools/color-palette \
  -H "Authorization: Bearer si_your-api-key" \
-  -F "file=@photo.jpg"
+  -F "file=@photo.jpg" \
+  -F 'settings={"count": 6, "format": "hex"}'
 ```

 ## Example Response
@@ -41,6 +41,14 @@ curl -X POST http://localhost:1349/api/v1/tools/image/color-palette \
    "#a0c0e0",
    "#806040"
  ],
+  "hex": [
+    "#304080",
+    "#e0a060",
+    "#f0f0f0",
+    "#203020",
+    "#a0c0e0",
+    "#806040"
+  ],
  "count": 6
 }
 ```
@@ -50,14 +58,15 @@ curl -X POST http://localhost:1349/api/v1/tools/image/color-palette \
 | Field | Type | Description |
 |-------|------|-------------|
 | filename | string | Sanitized filename |
-| colors | array | Array of hex color strings, ordered by dominance (most frequent first) |
+| colors | array | Array of color strings in the requested format, ordered by dominance (most frequent first) |
+| hex | array | Array of hex color strings (always hex, regardless of the `format` setting) |
 | count | number | Number of colors extracted |

 ## Notes

- Returns up to 8 dominant colors, sorted by frequency (most common first).
- The image is internally resized to 50x50 pixels for analysis, so the palette represents overall color distribution rather than small details.
- Colors are quantized to the nearest multiple of 16 to reduce noise, then similar colors (within RGB Manhattan distance of 48) are merged to avoid near-duplicate entries.
+- Returns up to `count` dominant colors (default 8, range 2-16), sorted by frequency (most common first).
+- The image is internally resized to 100x100 pixels for analysis, so the palette represents overall color distribution rather than small details.
+- Colors are extracted using median-cut quantization, which recursively splits pixel populations along the channel with the widest range.
 - The alpha channel is removed before analysis, so transparent areas are not considered.
 - This is a read-only endpoint. It does not produce a downloadable output file or a `jobId`.
 - HEIC, RAW, PSD, and SVG inputs are automatically decoded before analysis.
@@ -4,7 +4,7 @@ Convert black-and-white or grayscale photos to full color using AI (DDColor mode

 ## API Endpoint

-`POST /api/v1/tools/image/colorize`
+`POST /api/v1/tools/colorize`

 **Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)

@@ -21,7 +21,7 @@ Convert black-and-white or grayscale photos to full color using AI (DDColor mode
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/colorize \
+curl -X POST http://localhost:1349/api/v1/tools/colorize \
  -F "file=@old-bw-photo.jpg" \
  -F 'settings={"intensity":0.9,"model":"auto"}'
 ```
@@ -8,7 +8,7 @@ Upload two images to compute a pixel-level difference map and a numerical simila

 ## API Endpoint

-`POST /api/v1/tools/image/compare`
+`POST /api/v1/tools/compare`

 Accepts multipart form data with **two** image files. No settings field is needed.

@@ -24,7 +24,7 @@ This tool has no configurable parameters. Upload exactly two image files.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/compare \
+curl -X POST http://localhost:1349/api/v1/tools/compare \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@original.jpg" \
  -F "file=@modified.jpg"
@@ -8,7 +8,7 @@ Layer an overlay image on top of a base image with configurable position, opacit

 ## API Endpoint

-`POST /api/v1/tools/image/compose`
+`POST /api/v1/tools/compose`

 Accepts multipart form data with **two** image files and a JSON `settings` field.

@@ -46,7 +46,7 @@ Accepts multipart form data with **two** image files and a JSON `settings` field
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/compose \
+curl -X POST http://localhost:1349/api/v1/tools/compose \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@background.jpg" \
  -F "overlay=@graphic.png" \
@@ -56,7 +56,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/compose \
 Using multiply blend mode:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/compose \
+curl -X POST http://localhost:1349/api/v1/tools/compose \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F "overlay=@texture.jpg" \
@@ -8,7 +8,7 @@ Reduce image file size by specifying a quality level or a target file size in ki

 ## API Endpoint

-`POST /api/v1/tools/image/compress`
+`POST /api/v1/tools/compress`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -25,7 +25,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 Compress to quality 60:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/compress \
+curl -X POST http://localhost:1349/api/v1/tools/compress \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"mode": "quality", "quality": 60}'
@@ -34,7 +34,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/compress \
 Compress to target size of 200 KB:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/compress \
+curl -X POST http://localhost:1349/api/v1/tools/compress \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"mode": "targetSize", "targetSizeKb": 200}'
@@ -4,7 +4,7 @@ Seam carving resize that intelligently removes or adds pixels along paths of lea

 ## API Endpoint

-`POST /api/v1/tools/image/content-aware-resize`
+`POST /api/v1/tools/content-aware-resize`

 **Processing:** Synchronous (returns result directly)

@@ -15,8 +15,8 @@ Seam carving resize that intelligently removes or adds pixels along paths of lea
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
 | file | file | Yes | - | Image file (multipart) |
-| width | integer | No | - | Target width in pixels |
-| height | integer | No | - | Target height in pixels |
+| width | number | No | - | Target width in pixels |
+| height | number | No | - | Target height in pixels |
 | protectFaces | boolean | No | `false` | Detect and protect faces from seam removal |
 | blurRadius | number | No | `4` | Pre-processing blur radius for energy calculation (0-20) |
 | sobelThreshold | number | No | `2` | Sobel edge detection threshold (1-20). Higher values make the algorithm more aggressive |
@@ -27,7 +27,7 @@ At least one of `width`, `height`, or `square` must be specified.
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/content-aware-resize \
+curl -X POST http://localhost:1349/api/v1/tools/content-aware-resize \
  -F "file=@landscape.jpg" \
  -F 'settings={"width":800,"protectFaces":true}'
 ```
@@ -8,7 +8,7 @@ Convert images between formats. Supports common web formats as well as specializ

 ## API Endpoint

-`POST /api/v1/tools/image/convert`
+`POST /api/v1/tools/convert`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -16,7 +16,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.

 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| format | string | Yes | - | Target format: `jpg`, `png`, `webp`, `avif`, `tiff`, `gif`, `heic`, `heif`, `jxl`, `bmp`, `ico`, `jp2`, `qoi`, `psd` |
+| format | string | Yes | - | Target format: `jpg`, `png`, `webp`, `avif`, `tiff`, `gif`, `heic`, `heif`, `jxl`, `bmp`, `ico`, `jp2`, `qoi`, `psd`, `ppm`, `eps`, `tga` |
 | quality | number | No | - | Output quality (1-100). Applies to lossy formats like jpg, webp, avif, heic. |

 ## Supported Output Formats
@@ -36,13 +36,16 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 | jp2 | Lossy | JPEG 2000 |
 | qoi | Lossless | Quite OK Image format |
 | psd | Layered | Adobe Photoshop (requires ImageMagick) |
+| ppm | Lossless | Portable Pixmap (PPM/PGM/PBM) |
+| eps | Vector | Encapsulated PostScript |
+| tga | Lossless | Targa image format |

 ## Example Request

 Convert to WebP:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/convert \
+curl -X POST http://localhost:1349/api/v1/tools/convert \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"format": "webp", "quality": 85}'
@@ -51,7 +54,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/convert \
 Convert to PNG (lossless):

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/convert \
+curl -X POST http://localhost:1349/api/v1/tools/convert \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"format": "png"}'
@@ -73,6 +76,6 @@ curl -X POST http://localhost:1349/api/v1/tools/image/convert \
 - The output filename extension is automatically updated to match the target format.
 - SVG inputs are rasterized at 300 DPI before conversion.
 - PSD conversion requires ImageMagick to be installed on the server.
- BMP, ICO, JP2, JXL, and QOI use specialized CLI encoders and bypass Sharp processing.
+- BMP, EPS, ICO, JP2, JXL, PPM, QOI, and TGA use specialized CLI encoders and bypass Sharp processing.
 - HEIC/HEIF encoding uses the system HEIC encoder library.
 - Input formats are broad: JPEG, PNG, WebP, AVIF, TIFF, GIF, HEIC, RAW (CR2, NEF, ARW, etc.), PSD, SVG, BMP, and more.
@@ -8,7 +8,7 @@ Crop images by defining a rectangular region using position and size. Supports b

 ## API Endpoint

-`POST /api/v1/tools/image/crop`
+`POST /api/v1/tools/crop`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -25,7 +25,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/crop \
+curl -X POST http://localhost:1349/api/v1/tools/crop \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"left": 100, "top": 50, "width": 800, "height": 600}'
@@ -34,7 +34,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/crop \
 Crop using percentage values:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/crop \
+curl -X POST http://localhost:1349/api/v1/tools/crop \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"left": 10, "top": 10, "width": 80, "height": 80, "unit": "percent"}'
@@ -8,7 +8,7 @@ Apply a two-color duotone effect to an image. The image is converted to grayscal

 ## API Endpoint

-`POST /api/v1/tools/image/duotone`
+`POST /api/v1/tools/duotone`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -23,7 +23,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/duotone \
+curl -X POST http://localhost:1349/api/v1/tools/duotone \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"shadow": "#0f172a", "highlight": "#f97316", "intensity": 80}'
@@ -10,13 +10,13 @@ Edit image metadata fields including EXIF, IPTC, GPS coordinates, dates, and key

 ### Edit Metadata

-`POST /api/v1/tools/image/edit-metadata`
+`POST /api/v1/tools/edit-metadata`

 Writes metadata fields to the image and returns the modified file.

 ### Inspect Metadata

-`POST /api/v1/tools/image/edit-metadata/inspect`
+`POST /api/v1/tools/edit-metadata/inspect`

 Returns the full metadata from the image via ExifTool as JSON. Does not modify the image.

@@ -52,7 +52,7 @@ Returns the full metadata from the image via ExifTool as JSON. Does not modify t
 Set author and copyright:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/edit-metadata \
+curl -X POST http://localhost:1349/api/v1/tools/edit-metadata \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"author": "Jane Smith", "copyright": "2024 Jane Smith"}'
@@ -61,7 +61,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/edit-metadata \
 Set GPS coordinates:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/edit-metadata \
+curl -X POST http://localhost:1349/api/v1/tools/edit-metadata \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"gpsLatitude": 48.8566, "gpsLongitude": 2.3522, "gpsAltitude": 35}'
@@ -70,7 +70,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/edit-metadata \
 Remove GPS and add keywords:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/edit-metadata \
+curl -X POST http://localhost:1349/api/v1/tools/edit-metadata \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"clearGps": true, "keywords": ["landscape", "sunset"], "keywordsMode": "add"}'
@@ -79,7 +79,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/edit-metadata \
 Inspect metadata:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/edit-metadata/inspect \
+curl -X POST http://localhost:1349/api/v1/tools/edit-metadata/inspect \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg"
 ```
@@ -4,7 +4,7 @@ Restore and enhance faces in images using AI models (GFPGAN/CodeFormer).

 ## API Endpoint

-`POST /api/v1/tools/image/enhance-faces`
+`POST /api/v1/tools/enhance-faces`

 **Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)

@@ -23,7 +23,7 @@ Restore and enhance faces in images using AI models (GFPGAN/CodeFormer).
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/enhance-faces \
+curl -X POST http://localhost:1349/api/v1/tools/enhance-faces \
  -F "file=@portrait.jpg" \
  -F 'settings={"model":"codeformer","strength":0.7,"onlyCenterFace":false}'
 ```
@@ -4,7 +4,7 @@ Remove unwanted objects from images using AI inpainting (LaMa model). Accepts an

 ## API Endpoint

-`POST /api/v1/tools/image/erase-object`
+`POST /api/v1/tools/erase-object`

 **Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)

@@ -22,7 +22,7 @@ Remove unwanted objects from images using AI inpainting (LaMa model). Accepts an
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/erase-object \
+curl -X POST http://localhost:1349/api/v1/tools/erase-object \
  -F "file=@photo.jpg" \
  -F "mask=@mask.png" \
  -F "format=png" \
@@ -8,13 +8,19 @@ Generate a complete set of favicon and app icon files from a source image. Produ

 ## API Endpoint

-`POST /api/v1/tools/image/favicon`
+`POST /api/v1/tools/favicon`

-Accepts multipart form data with one or more image files. No settings are required.
+Accepts multipart form data with one or more image files and an optional JSON `settings` field.

 ## Parameters

-This tool has no configurable parameters. It generates all standard sizes automatically.
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| background | string | No | - | Background hex color (e.g. `"#ffffff"`). When set, the icon is flattened onto this color. |
+| padding | integer | No | `0` | Padding percentage around the icon content (0 to 40) |
+| radius | integer | No | `0` | Corner radius percentage for rounded icons (0 to 50) |
+| sizes | integer[] | No | - | Restrict output to specific pixel sizes (e.g. `[16, 32, 180]`). Omit to generate all standard sizes. |
+| themeColor | string | No | `"#ffffff"` | Theme color hex for the web manifest |

 ## Generated Files

@@ -34,18 +40,19 @@ For each input image, the following files are produced:

 ## Example Request

-Single source image:
+Single source image with rounded corners and padding:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/favicon \
+curl -X POST http://localhost:1349/api/v1/tools/favicon \
  -H "Authorization: Bearer si_your-api-key" \
-  -F "file=@logo.png"
+  -F "file=@logo.png" \
+  -F 'settings={"padding": 10, "radius": 20, "themeColor": "#0a0a0a"}'
 ```

 Multiple source images (each gets its own set in a subfolder):

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/favicon \
+curl -X POST http://localhost:1349/api/v1/tools/favicon \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@logo-light.png" \
  -F "file=@logo-dark.png"
@@ -8,7 +8,7 @@ Upload multiple images to detect duplicates and near-duplicates using perceptual

 ## API Endpoint

-`POST /api/v1/tools/image/find-duplicates`
+`POST /api/v1/tools/find-duplicates`

 Accepts multipart form data with multiple image files and an optional JSON `settings` field.

@@ -25,7 +25,7 @@ Upload at least 2 image files in the multipart request (all using the `file` fie
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/find-duplicates \
+curl -X POST http://localhost:1349/api/v1/tools/find-duplicates \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo1.jpg" \
  -F "file=@photo2.jpg" \
@@ -4,7 +4,7 @@ Resize, optimize, change speed, reverse, extract frames, and rotate animated GIF

 ## API Endpoint

-`POST /api/v1/tools/image/gif-tools`
+`POST /api/v1/tools/gif-tools`

 ## Parameters

@@ -60,7 +60,7 @@ Resize, optimize, change speed, reverse, extract frames, and rotate animated GIF
 ### Resize

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/gif-tools \
+curl -X POST http://localhost:1349/api/v1/tools/gif-tools \
  -F "file=@animation.gif" \
  -F 'settings={"mode":"resize","percentage":50}'
 ```
@@ -68,7 +68,7 @@ curl -X POST http://localhost:13490/api/v1/tools/image/gif-tools \
 ### Optimize

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/gif-tools \
+curl -X POST http://localhost:1349/api/v1/tools/gif-tools \
  -F "file=@large.gif" \
  -F 'settings={"mode":"optimize","colors":128,"effort":9}'
 ```
@@ -76,7 +76,7 @@ curl -X POST http://localhost:13490/api/v1/tools/image/gif-tools \
 ### Speed Up

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/gif-tools \
+curl -X POST http://localhost:1349/api/v1/tools/gif-tools \
  -F "file=@animation.gif" \
  -F 'settings={"mode":"speed","speedFactor":2.0}'
 ```
@@ -84,7 +84,7 @@ curl -X POST http://localhost:13490/api/v1/tools/image/gif-tools \
 ### Extract Single Frame

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/gif-tools \
+curl -X POST http://localhost:1349/api/v1/tools/gif-tools \
  -F "file=@animation.gif" \
  -F 'settings={"mode":"extract","extractMode":"single","frameNumber":5,"extractFormat":"png"}'
 ```
@@ -102,14 +102,14 @@ curl -X POST http://localhost:13490/api/v1/tools/image/gif-tools \

 ## Info Sub-Route

-`POST /api/v1/tools/image/gif-tools/info`
+`POST /api/v1/tools/gif-tools/info`

 Returns metadata about an animated GIF without processing it.

 ### Info Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/gif-tools/info \
+curl -X POST http://localhost:1349/api/v1/tools/gif-tools/info \
  -F "file=@animation.gif"
 ```

@@ -8,7 +8,7 @@ Convert animated GIF files to WebP and vice versa, preserving all frames and ani

 ## API Endpoint

-`POST /api/v1/tools/image/gif-webp`
+`POST /api/v1/tools/gif-webp`

 Accepts multipart form data with a GIF or WebP file and a JSON `settings` field.

@@ -23,7 +23,7 @@ Accepts multipart form data with a GIF or WebP file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/gif-webp \
+curl -X POST http://localhost:1349/api/v1/tools/gif-webp \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@animation.gif" \
  -F 'settings={"quality": 85, "resizePercent": 50}'
@@ -8,7 +8,7 @@ Generate an RGB histogram chart from an image. Returns a PNG histogram image alo

 ## API Endpoint

-`POST /api/v1/tools/image/histogram`
+`POST /api/v1/tools/histogram`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -21,7 +21,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/histogram \
+curl -X POST http://localhost:1349/api/v1/tools/histogram \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"scale": "linear"}'
@@ -8,7 +8,7 @@ Capture a webpage URL or raw HTML content as a screenshot image. Supports device

 ## API Endpoint

-`POST /api/v1/tools/image/html-to-image`
+`POST /api/v1/tools/html-to-image`

 Accepts a **JSON body** (not multipart). No file upload is needed.

@@ -41,7 +41,7 @@ Either `url` or `html` must be provided, but not both.
 Capture a webpage:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
+curl -X POST http://localhost:1349/api/v1/tools/html-to-image \
  -H "Authorization: Bearer si_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "format": "png", "fullPage": true, "devicePreset": "desktop"}'
@@ -50,7 +50,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
 Render HTML content:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
+curl -X POST http://localhost:1349/api/v1/tools/html-to-image \
  -H "Authorization: Bearer si_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"html": "<div style=\"padding: 20px; background: #f0f0f0;\"><h1>Hello</h1></div>", "format": "png"}'
@@ -4,7 +4,7 @@ One-click auto-improve with smart analysis. Analyzes the image and applies expos

 ## API Endpoint

-`POST /api/v1/tools/image/image-enhancement`
+`POST /api/v1/tools/image-enhancement`

 **Processing:** Synchronous (uses `createToolRoute` factory, returns result directly)

@@ -34,7 +34,7 @@ One-click auto-improve with smart analysis. Analyzes the image and applies expos
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/image-enhancement \
+curl -X POST http://localhost:1349/api/v1/tools/image-enhancement \
  -F "file=@photo.jpg" \
  -F 'settings={"mode":"portrait","intensity":70,"corrections":{"exposure":true,"contrast":true,"sharpness":false}}'
 ```
@@ -44,7 +44,7 @@ curl -X POST http://localhost:13490/api/v1/tools/image/image-enhancement \
 ```json
 {
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "downloadUrl": "/api/v1/download/{jobId}/photo_enhanced.jpg",
+  "downloadUrl": "/api/v1/download/{jobId}/photo.jpg",
  "originalSize": 300000,
  "processedSize": 310000
 }
@@ -52,7 +52,7 @@ curl -X POST http://localhost:13490/api/v1/tools/image/image-enhancement \

 ## Analyze Endpoint

-`POST /api/v1/tools/image/image-enhancement/analyze`
+`POST /api/v1/tools/image-enhancement/analyze`

 Analyzes an image and returns correction recommendations without applying them.

@@ -65,7 +65,7 @@ Analyzes an image and returns correction recommendations without applying them.
 ### Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/image-enhancement/analyze \
+curl -X POST http://localhost:1349/api/v1/tools/image-enhancement/analyze \
  -F "file=@photo.jpg"
 ```

@@ -8,7 +8,7 @@ Pad an image to a target aspect ratio by adding a solid color, transparent, or b

 ## API Endpoint

-`POST /api/v1/tools/image/image-pad`
+`POST /api/v1/tools/image-pad`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -26,7 +26,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/image-pad \
+curl -X POST http://localhost:1349/api/v1/tools/image-pad \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"target": "16:9", "background": "blur", "padding": 5}'
@@ -8,7 +8,7 @@ Convert one or more images to base64-encoded strings and data URIs. Supports opt

 ## API Endpoint

-`POST /api/v1/tools/image/image-to-base64`
+`POST /api/v1/tools/image-to-base64`

 Accepts multipart form data with one or more image files and an optional JSON `settings` field.

@@ -24,7 +24,7 @@ Accepts multipart form data with one or more image files and an optional JSON `s
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/image-to-base64 \
+curl -X POST http://localhost:1349/api/v1/tools/image-to-base64 \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@icon.png" \
  -F 'settings={"outputFormat": "webp", "quality": 80, "maxWidth": 200}'
@@ -33,7 +33,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/image-to-base64 \
 Multiple files:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/image-to-base64 \
+curl -X POST http://localhost:1349/api/v1/tools/image-to-base64 \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@icon1.png" \
  -F "file=@icon2.png" \
@@ -8,7 +8,7 @@ Combine one or more images into a PDF document. Supports multiple page sizes, or

 ## API Endpoint

-`POST /api/v1/tools/image/image-to-pdf`
+`POST /api/v1/tools/image-to-pdf`

 Accepts multipart form data with one or more image files and a JSON `settings` field.

@@ -36,7 +36,7 @@ Minimum target size is 50 KB.
 Basic multi-image PDF:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/image-to-pdf \
+curl -X POST http://localhost:1349/api/v1/tools/image-to-pdf \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@page1.jpg" \
  -F "file=@page2.jpg" \
@@ -47,7 +47,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/image-to-pdf \
 With file size target:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/image-to-pdf \
+curl -X POST http://localhost:1349/api/v1/tools/image-to-pdf \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@scan1.jpg" \
  -F "file=@scan2.jpg" \
@@ -57,7 +57,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/image-to-pdf \
 One PDF per image:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/image-to-pdf \
+curl -X POST http://localhost:1349/api/v1/tools/image-to-pdf \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo1.jpg" \
  -F "file=@photo2.jpg" \
@@ -8,7 +8,7 @@ Read-only analysis tool that returns comprehensive image metadata including dime

 ## API Endpoint

-`POST /api/v1/tools/image/info`
+`POST /api/v1/tools/info`

 Accepts multipart form data with an image file. No settings field is needed.

@@ -23,7 +23,7 @@ This tool has no configurable parameters. Simply upload the image file.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/info \
+curl -X POST http://localhost:1349/api/v1/tools/info \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg"
 ```
@@ -8,7 +8,7 @@ Generate a tiny low-quality image placeholder (LQIP) from a source image. Return

 ## API Endpoint

-`POST /api/v1/tools/image/lqip-placeholder`
+`POST /api/v1/tools/lqip-placeholder`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -25,7 +25,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/lqip-placeholder \
+curl -X POST http://localhost:1349/api/v1/tools/lqip-placeholder \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"width": 20, "strategy": "blur", "format": "webp"}'
@@ -44,8 +44,8 @@ curl -X POST http://localhost:1349/api/v1/tools/image/lqip-placeholder \
  "height": 13,
  "bytes": 280,
  "strategy": "blur",
-  "html": "<img src=\"data:image/webp;base64,UklGR...\" width=\"20\" height=\"13\" alt=\"\" />",
-  "css": "background-image: url(data:image/webp;base64,UklGR...);"
+  "html": "<img src=\"data:image/webp;base64,UklGR...\" />",
+  "css": "background-image:url('data:image/webp;base64,UklGR...');background-size:cover;background-position:center;"
 }
 ```

@@ -8,7 +8,7 @@ Create memes using built-in templates or custom images. Add text with classic me

 ## API Endpoint

-`POST /api/v1/tools/image/meme-generator`
+`POST /api/v1/tools/meme-generator`

 Accepts either:
 - **Multipart form data** with an image file and a JSON `settings` field (custom image mode)
@@ -52,7 +52,7 @@ Each entry in the `textBoxes` array should have:
 Custom image with top and bottom text:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/meme-generator \
+curl -X POST http://localhost:1349/api/v1/tools/meme-generator \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"textLayout": "top-bottom", "textBoxes": [{"id": "top", "text": "When the code works"}, {"id": "bottom", "text": "On the first try"}], "fontFamily": "anton", "allCaps": true}'
@@ -61,7 +61,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/meme-generator \
 Using a built-in template (JSON body, no file upload):

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/meme-generator \
+curl -X POST http://localhost:1349/api/v1/tools/meme-generator \
  -H "Authorization: Bearer si_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"templateId": "drake", "textBoxes": [{"id": "top", "text": "Manual testing"}, {"id": "bottom", "text": "Automated tests"}]}'
@@ -1,10 +1,14 @@
+---
+description: AI-powered noise and grain removal with multi-tier quality options.
+---
+
 # Noise Removal

 AI-powered noise and grain removal with multi-tier quality options, using the Python sidecar (SCUNet model).

 ## API Endpoint

-`POST /api/v1/tools/image/noise-removal`
+`POST /api/v1/tools/noise-removal`

 **Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)

@@ -25,7 +29,7 @@ AI-powered noise and grain removal with multi-tier quality options, using the Py
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/noise-removal \
+curl -X POST http://localhost:1349/api/v1/tools/noise-removal \
  -F "file=@noisy-photo.jpg" \
  -F 'settings={"tier":"quality","strength":60,"detailPreservation":70,"colorNoise":40}'
 ```
@@ -1,10 +1,14 @@
+---
+description: Extract text from images using AI-powered optical character recognition.
+---
+
 # OCR / Text Extraction

 Extract text from images using AI-powered optical character recognition. Supports multiple languages and quality tiers.

 ## API Endpoint

-`POST /api/v1/tools/image/ocr`
+`POST /api/v1/tools/ocr`

 **Processing:** Synchronous (returns extracted text directly, though progress is reported via SSE if a `clientJobId` is provided)

@@ -23,7 +27,7 @@ Extract text from images using AI-powered optical character recognition. Support
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/ocr \
+curl -X POST http://localhost:1349/api/v1/tools/ocr \
  -F "file=@document.png" \
  -F 'settings={"quality":"best","language":"en","enhance":true}'
 ```
@@ -8,11 +8,11 @@ Optimize images for web delivery in a single step. Combines format conversion, q

 ## API Endpoint

-`POST /api/v1/tools/image/optimize-for-web`
+`POST /api/v1/tools/optimize-for-web`

 Accepts multipart form data with an image file and a JSON `settings` field.

-A live preview endpoint is also available at `POST /api/v1/tools/image/optimize-for-web/preview`, which returns the processed image directly as binary (no workspace creation) for real-time parameter tuning.
+A live preview endpoint is also available at `POST /api/v1/tools/optimize-for-web/preview`, which returns the processed image directly as binary (no workspace creation) for real-time parameter tuning.

 ## Parameters

@@ -28,7 +28,7 @@ A live preview endpoint is also available at `POST /api/v1/tools/image/optimize-
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/optimize-for-web \
+curl -X POST http://localhost:1349/api/v1/tools/optimize-for-web \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"format": "webp", "quality": 75, "maxWidth": 1920}'
@@ -37,7 +37,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/optimize-for-web \
 Optimize for AVIF with aggressive compression:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/optimize-for-web \
+curl -X POST http://localhost:1349/api/v1/tools/optimize-for-web \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"format": "avif", "quality": 50, "maxWidth": 1200, "maxHeight": 800}'
@@ -56,7 +56,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/optimize-for-web \

 ### Preview Endpoint Response

-The preview endpoint (`/api/v1/tools/image/optimize-for-web/preview`) returns the binary image directly with informational headers:
+The preview endpoint (`/api/v1/tools/optimize-for-web/preview`) returns the binary image directly with informational headers:

 - `X-Original-Size` - Original file size in bytes
 - `X-Processed-Size` - Processed file size in bytes
@@ -1,3 +1,7 @@
+---
+description: AI-powered passport and ID photo generator with face detection, background removal, and print sheet tiling.
+---
+
 # Passport Photo

 AI-powered passport and ID photo generator. Two-phase workflow: analyze (face detection + background removal) then generate (crop, resize, and tile for printing).
@@ -12,7 +16,7 @@ This tool uses a two-phase flow with separate endpoints for analysis and generat

 ### Phase 1: Analyze

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

 Detects face landmarks and removes the background. Returns landmark data and a preview for the frontend to display a crop preview.

@@ -26,7 +30,7 @@ Detects face landmarks and removes the background. Returns landmark data and a p
 #### Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/passport-photo/analyze \
+curl -X POST http://localhost:1349/api/v1/tools/passport-photo/analyze \
  -F "file=@headshot.jpg"
 ```

@@ -71,7 +75,7 @@ If `clientJobId` is provided, progress is streamed (0-30% for face detection, 30

 ### Phase 2: Generate

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

 Crops, resizes, and optionally tiles the photo onto a print sheet. Uses cached images from Phase 1 (no AI re-run).

@@ -99,7 +103,7 @@ Crops, resizes, and optionally tiles the photo onto a print sheet. Uses cached i
 #### Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/passport-photo/generate \
+curl -X POST http://localhost:1349/api/v1/tools/passport-photo/generate \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "a1b2c3d4-...",
@@ -145,13 +149,13 @@ curl -X POST http://localhost:13490/api/v1/tools/image/passport-photo/generate \

 ### Base Route

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

 Returns guidance to use the correct sub-endpoint.

 ```json
 {
-  "error": "Use /api/v1/tools/image/passport-photo/analyze or /generate"
+  "error": "Use /api/v1/tools/passport-photo/analyze or /generate"
 }
 ```

@@ -8,7 +8,7 @@ Apply a pixelation effect to an entire image or a specific rectangular region. U

 ## API Endpoint

-`POST /api/v1/tools/image/pixelate`
+`POST /api/v1/tools/pixelate`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -33,7 +33,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 Pixelate the full image:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/pixelate \
+curl -X POST http://localhost:1349/api/v1/tools/pixelate \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"blockSize": 20}'
@@ -42,7 +42,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/pixelate \
 Pixelate a specific region:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/pixelate \
+curl -X POST http://localhost:1349/api/v1/tools/pixelate \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"blockSize": 16, "region": {"left": 100, "top": 50, "width": 200, "height": 150}}'
@@ -8,7 +8,7 @@ Generate QR code images from text or URLs with configurable size, error correcti

 ## API Endpoint

-`POST /api/v1/tools/image/qr-generate`
+`POST /api/v1/tools/qr-generate`

 Accepts a **JSON body** (not multipart). No file upload is needed.

@@ -21,6 +21,7 @@ Accepts a **JSON body** (not multipart). No file upload is needed.
 | errorCorrection | string | No | `"M"` | Error correction level: `L` (7%), `M` (15%), `Q` (25%), `H` (30%) |
 | foreground | string | No | `"#000000"` | QR code foreground/module color in hex (`#RRGGBB`) |
 | background | string | No | `"#FFFFFF"` | QR code background color in hex (`#RRGGBB`) |
+| logoDataUri | string | No | - | Logo image as a data URI (`data:image/png;base64,...` or `data:image/jpeg;base64,...`, max 700 KB). Centered on the QR code at 22% of the QR size. Forces error correction to `H` |

 ### Error Correction Levels

@@ -34,7 +35,7 @@ Accepts a **JSON body** (not multipart). No file upload is needed.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/qr-generate \
+curl -X POST http://localhost:1349/api/v1/tools/qr-generate \
  -H "Authorization: Bearer si_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"text": "https://snapotter.com", "size": 500, "errorCorrection": "H"}'
@@ -43,7 +44,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/qr-generate \
 Branded QR code with custom colors:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/qr-generate \
+curl -X POST http://localhost:1349/api/v1/tools/qr-generate \
  -H "Authorization: Bearer si_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello World", "size": 300, "foreground": "#1a365d", "background": "#f7fafc"}'
@@ -69,3 +70,4 @@ curl -X POST http://localhost:1349/api/v1/tools/image/qr-generate \
 - A 2-module quiet zone (margin) is included around the QR code.
 - Maximum text length is 2000 characters. Actual capacity depends on error correction level and character encoding.
 - Higher error correction levels allow the QR code to remain scannable even if partially obscured but reduce data capacity.
+- When a `logoDataUri` is provided, error correction is automatically forced to `H` (30%) so the QR code remains scannable despite the logo occluding the center.
@@ -1,10 +1,14 @@
+---
+description: AI-powered detection and correction of red eye caused by camera flash.
+---
+
 # Red Eye Removal

 AI-powered detection and correction of red eye caused by camera flash.

 ## API Endpoint

-`POST /api/v1/tools/image/red-eye-removal`
+`POST /api/v1/tools/red-eye-removal`

 **Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)

@@ -23,7 +27,7 @@ AI-powered detection and correction of red eye caused by camera flash.
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/red-eye-removal \
+curl -X POST http://localhost:1349/api/v1/tools/red-eye-removal \
  -F "file=@flash-photo.jpg" \
  -F 'settings={"sensitivity":60,"strength":80}'
 ```
@@ -1,10 +1,14 @@
+---
+description: AI-powered background removal with optional effects (blur, shadow, gradient, custom background).
+---
+
 # Remove Background

 AI-powered background removal with optional effects (blur, shadow, gradient, custom background).

 ## API Endpoint

-`POST /api/v1/tools/image/remove-background`
+`POST /api/v1/tools/remove-background`

 **Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)

@@ -32,7 +36,7 @@ AI-powered background removal with optional effects (blur, shadow, gradient, cus
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/remove-background \
+curl -X POST http://localhost:1349/api/v1/tools/remove-background \
  -F "file=@photo.jpg" \
  -F 'settings={"backgroundType":"transparent","edgeRefine":2,"outputFormat":"png"}'
 ```
@@ -76,7 +80,7 @@ data: {"phase":"processing","stage":"Removing background...","percent":50}

 ## Effects Endpoint (Phase 2)

-`POST /api/v1/tools/image/remove-background/effects`
+`POST /api/v1/tools/remove-background/effects`

 Re-applies background effects without re-running the AI model. Uses cached mask and original from Phase 1.

@@ -107,7 +111,7 @@ Re-applies background effects without re-running the AI model. Uses cached mask
 ### Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/remove-background/effects \
+curl -X POST http://localhost:1349/api/v1/tools/remove-background/effects \
  -F 'settings={"jobId":"a1b2c3d4-...","filename":"photo.jpg","backgroundType":"color","backgroundColor":"#FF5500","outputFormat":"png"}'
 ```

@@ -8,7 +8,7 @@ Replace pixels matching a source color with a target color, or make them transpa

 ## API Endpoint

-`POST /api/v1/tools/image/replace-color`
+`POST /api/v1/tools/replace-color`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -24,7 +24,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/replace-color \
+curl -X POST http://localhost:1349/api/v1/tools/replace-color \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"sourceColor": "#FF0000", "targetColor": "#0000FF", "tolerance": 40}'
@@ -33,7 +33,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/replace-color \
 Make a green background transparent:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/replace-color \
+curl -X POST http://localhost:1349/api/v1/tools/replace-color \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@greenscreen.png" \
  -F 'settings={"sourceColor": "#00FF00", "makeTransparent": true, "tolerance": 50}'
@@ -8,7 +8,7 @@ Resize images by specifying exact pixel dimensions, a percentage scale factor, o

 ## API Endpoint

-`POST /api/v1/tools/image/resize`
+`POST /api/v1/tools/resize`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -35,7 +35,7 @@ At least one of `width`, `height`, or `percentage` must be provided.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/resize \
+curl -X POST http://localhost:1349/api/v1/tools/resize \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"width": 800, "height": 600, "fit": "contain"}'
@@ -44,7 +44,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/resize \
 Resize by percentage:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/resize \
+curl -X POST http://localhost:1349/api/v1/tools/resize \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"percentage": 50}'
@@ -4,7 +4,7 @@ Fix scratches, tears, and damage on old photos using a multi-step AI pipeline. C

 ## API Endpoint

-`POST /api/v1/tools/image/restore-photo`
+`POST /api/v1/tools/restore-photo`

 **Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)

@@ -26,7 +26,7 @@ Fix scratches, tears, and damage on old photos using a multi-step AI pipeline. C
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/restore-photo \
+curl -X POST http://localhost:1349/api/v1/tools/restore-photo \
  -F "file=@damaged-old-photo.jpg" \
  -F 'settings={"scratchRemoval":true,"faceEnhancement":true,"fidelity":0.6,"colorize":true}'
 ```
@@ -8,7 +8,7 @@ Rotate images by an arbitrary angle and/or flip them horizontally or vertically.

 ## API Endpoint

-`POST /api/v1/tools/image/rotate`
+`POST /api/v1/tools/rotate`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -25,7 +25,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 Rotate 90 degrees clockwise:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/rotate \
+curl -X POST http://localhost:1349/api/v1/tools/rotate \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"angle": 90}'
@@ -34,7 +34,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/rotate \
 Flip horizontally:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/rotate \
+curl -X POST http://localhost:1349/api/v1/tools/rotate \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"horizontal": true}'
@@ -43,7 +43,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/rotate \
 Rotate and flip together:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/rotate \
+curl -X POST http://localhost:1349/api/v1/tools/rotate \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"angle": 45, "vertical": true}'
@@ -8,7 +8,7 @@ Advanced sharpening tool with three methods: adaptive (smart edge-aware), unshar

 ## API Endpoint

-`POST /api/v1/tools/image/sharpening`
+`POST /api/v1/tools/sharpening`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -33,7 +33,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/sharpening \
+curl -X POST http://localhost:1349/api/v1/tools/sharpening \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"method": "adaptive", "sigma": 1.5}'
@@ -42,7 +42,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/sharpening \
 Unsharp mask with threshold to protect smooth areas:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/sharpening \
+curl -X POST http://localhost:1349/api/v1/tools/sharpening \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"method": "unsharp-mask", "amount": 150, "radius": 1.5, "threshold": 10}'
@@ -4,9 +4,9 @@ Smart subject-aware, face-aware, or trim-based cropping. Uses Sharp's attention/

 ## API Endpoint

-`POST /api/v1/tools/image/smart-crop`
+`POST /api/v1/tools/smart-crop`

-**Processing:** Synchronous (uses `createToolRoute` factory, returns result directly)
+**Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)

 **Model bundle:** `face-detection` (200-300 MB) -- required only for `face` mode

@@ -31,19 +31,41 @@ Smart subject-aware, face-aware, or trim-based cropping. Uses Sharp's attention/
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/smart-crop \
+curl -X POST http://localhost:1349/api/v1/tools/smart-crop \
  -F "file=@portrait.jpg" \
  -F 'settings={"mode":"face","width":1080,"height":1080,"facePreset":"head-shoulders"}'
 ```

-## Response (200 OK)
+## Response
+
+### Initial Response (202 Accepted)

 ```json
 {
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "downloadUrl": "/api/v1/download/{jobId}/portrait_smartcrop.jpg",
-  "originalSize": 500000,
-  "processedSize": 320000
+  "async": true
+}
+```
+
+### Progress (SSE at `/api/v1/jobs/{jobId}/progress`)
+
+```
+event: progress
+data: {"phase":"processing","percent":50}
+```
+
+### Final Result (via SSE)
+
+```json
+{
+  "phase": "complete",
+  "percent": 100,
+  "result": {
+    "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    "downloadUrl": "/api/v1/download/{jobId}/portrait_smartcrop.jpg",
+    "originalSize": 500000,
+    "processedSize": 320000
+  }
 }
 ```

@@ -60,7 +82,7 @@ Removes uniform borders/background from the image. Optionally pads the result to

 ## Notes

- This tool uses the synchronous `createToolRoute` factory, so it returns a standard response (not 202 async).
+- This tool uses the `createToolRoute` factory with `executionHint: "long"`, so it returns 202 with SSE progress.
 - Face mode requires the `face-detection` model bundle (200-300 MB).
 - Subject and trim modes work without any AI model bundle.
 - The `facePreset` determines how tightly the crop frames detected faces: `closeup` is the tightest, `half-body` is the widest.
@@ -4,7 +4,7 @@ Split a single image into grid tiles by column/row count or by specific pixel di

 ## API Endpoint

-`POST /api/v1/tools/image/split`
+`POST /api/v1/tools/split`

 ## Parameters

@@ -20,7 +20,7 @@ Split a single image into grid tiles by column/row count or by specific pixel di
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/split \
+curl -X POST http://localhost:1349/api/v1/tools/split \
  -F "file=@large-image.png" \
  -F 'settings={"columns":3,"rows":3,"outputFormat":"png"}' \
  --output split-tiles.zip
@@ -8,7 +8,7 @@ Combine multiple images into a single sprite sheet grid. Each image is resized t

 ## API Endpoint

-`POST /api/v1/tools/image/sprite-sheet`
+`POST /api/v1/tools/sprite-sheet`

 Accepts multipart form data with two or more image files and a JSON `settings` field.

@@ -25,7 +25,7 @@ Accepts multipart form data with two or more image files and a JSON `settings` f
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/sprite-sheet \
+curl -X POST http://localhost:1349/api/v1/tools/sprite-sheet \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@frame1.png" \
  -F "file=@frame2.png" \
@@ -4,7 +4,7 @@ Join multiple images side by side, stacked vertically, or arranged in a grid. Su

 ## API Endpoint

-`POST /api/v1/tools/image/stitch`
+`POST /api/v1/tools/stitch`

 ## Parameters

@@ -24,7 +24,7 @@ Join multiple images side by side, stacked vertically, or arranged in a grid. Su
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/stitch \
+curl -X POST http://localhost:1349/api/v1/tools/stitch \
  -F "file=@image1.png" \
  -F "file=@image2.png" \
  -F "file=@image3.png" \
@@ -10,13 +10,13 @@ Remove EXIF, GPS, ICC color profiles, and XMP metadata from images. Useful for p

 ### Strip Metadata

-`POST /api/v1/tools/image/strip-metadata`
+`POST /api/v1/tools/strip-metadata`

 Processes the image and returns a cleaned version with selected metadata removed.

 ### Inspect Metadata

-`POST /api/v1/tools/image/strip-metadata/inspect`
+`POST /api/v1/tools/strip-metadata/inspect`

 Returns the parsed metadata as JSON without modifying the image. Useful for previewing what metadata exists before stripping.

@@ -37,7 +37,7 @@ When `stripAll` is `true`, it overrides the individual flags and removes everyth
 Strip all metadata:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/strip-metadata \
+curl -X POST http://localhost:1349/api/v1/tools/strip-metadata \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"stripAll": true}'
@@ -46,7 +46,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/strip-metadata \
 Strip only GPS data (keep camera info and color profile):

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/strip-metadata \
+curl -X POST http://localhost:1349/api/v1/tools/strip-metadata \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"stripAll": false, "stripGps": true}'
@@ -55,7 +55,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/strip-metadata \
 Inspect metadata without modifying:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/strip-metadata/inspect \
+curl -X POST http://localhost:1349/api/v1/tools/strip-metadata/inspect \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg"
 ```
@@ -4,7 +4,7 @@ Convert SVG files to raster image formats (PNG, JPEG, WebP, AVIF, TIFF, GIF, HEI

 ## API Endpoint

-`POST /api/v1/tools/image/svg-to-raster`
+`POST /api/v1/tools/svg-to-raster`

 ## Parameters

@@ -20,7 +20,7 @@ Convert SVG files to raster image formats (PNG, JPEG, WebP, AVIF, TIFF, GIF, HEI
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/svg-to-raster \
+curl -X POST http://localhost:1349/api/v1/tools/svg-to-raster \
  -F "file=@logo.svg" \
  -F 'settings={"width":1024,"dpi":300,"outputFormat":"png","backgroundColor":"#FFFFFF"}'
 ```
@@ -39,7 +39,7 @@ curl -X POST http://localhost:13490/api/v1/tools/image/svg-to-raster \

 ## Batch Endpoint

-`POST /api/v1/tools/image/svg-to-raster/batch`
+`POST /api/v1/tools/svg-to-raster/batch`

 Convert multiple SVG files in one request. Returns a ZIP archive.

@@ -52,7 +52,7 @@ Convert multiple SVG files in one request. Returns a ZIP archive.
 ### Batch Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/svg-to-raster/batch \
+curl -X POST http://localhost:1349/api/v1/tools/svg-to-raster/batch \
  -F "file=@icon1.svg" \
  -F "file=@icon2.svg" \
  -F "file=@icon3.svg" \
@@ -8,7 +8,7 @@ Add styled text to images with optional drop shadow and semi-transparent backgro

 ## API Endpoint

-`POST /api/v1/tools/image/text-overlay`
+`POST /api/v1/tools/text-overlay`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -27,7 +27,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/text-overlay \
+curl -X POST http://localhost:1349/api/v1/tools/text-overlay \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"text": "Hello World", "fontSize": 64, "color": "#FFFFFF", "position": "bottom", "shadow": true}'
@@ -36,7 +36,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/text-overlay \
 With a background box:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/text-overlay \
+curl -X POST http://localhost:1349/api/v1/tools/text-overlay \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"text": "Caption", "fontSize": 36, "position": "bottom", "backgroundBox": true, "backgroundColor": "#000000"}'
@@ -4,7 +4,7 @@ Fix fake transparent PNGs in one click. Uses AI matting (BiRefNet HR Matting mod

 ## API Endpoint

-`POST /api/v1/tools/image/transparency-fixer`
+`POST /api/v1/tools/transparency-fixer`

 **Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)

@@ -22,7 +22,7 @@ Fix fake transparent PNGs in one click. Uses AI matting (BiRefNet HR Matting mod
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/transparency-fixer \
+curl -X POST http://localhost:1349/api/v1/tools/transparency-fixer \
  -F "file=@fake-transparent.png" \
  -F 'settings={"defringe":40,"outputFormat":"png"}'
 ```
@@ -4,7 +4,7 @@ AI super-resolution enhancement using Real-ESRGAN. Upscales images 2x-4x while p

 ## API Endpoint

-`POST /api/v1/tools/image/upscale`
+`POST /api/v1/tools/upscale`

 **Processing:** Asynchronous (returns 202, poll `/api/v1/jobs/{jobId}/progress` for status via SSE)

@@ -25,7 +25,7 @@ AI super-resolution enhancement using Real-ESRGAN. Upscales images 2x-4x while p
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/upscale \
+curl -X POST http://localhost:1349/api/v1/tools/upscale \
  -F "file=@photo.jpg" \
  -F 'settings={"scale":4,"model":"auto","faceEnhance":true,"format":"png"}'
 ```
@@ -4,7 +4,7 @@ Vectorize raster images into SVG using tracing algorithms. Supports black-and-wh

 ## API Endpoint

-`POST /api/v1/tools/image/vectorize`
+`POST /api/v1/tools/vectorize`

 ## Parameters

@@ -22,7 +22,7 @@ Vectorize raster images into SVG using tracing algorithms. Supports black-and-wh
 ## Example Request

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/vectorize \
+curl -X POST http://localhost:1349/api/v1/tools/vectorize \
  -F "file=@logo.png" \
  -F 'settings={"colorMode":"bw","threshold":128,"filterSpeckle":4,"pathMode":"spline"}'
 ```
@@ -30,7 +30,7 @@ curl -X POST http://localhost:13490/api/v1/tools/image/vectorize \
 ### Color Vectorization

 ```bash
-curl -X POST http://localhost:13490/api/v1/tools/image/vectorize \
+curl -X POST http://localhost:1349/api/v1/tools/vectorize \
  -F "file=@illustration.png" \
  -F 'settings={"colorMode":"color","colorPrecision":8,"layerDifference":6,"filterSpeckle":4}'
 ```
@@ -8,7 +8,7 @@ Add a vignette effect that darkens or tints the edges of an image. Supports adju

 ## API Endpoint

-`POST /api/v1/tools/image/vignette`
+`POST /api/v1/tools/vignette`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -27,7 +27,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/vignette \
+curl -X POST http://localhost:1349/api/v1/tools/vignette \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"strength": 0.7, "radius": 60, "softness": 70}'
@@ -8,7 +8,7 @@ Overlay a logo or secondary image as a watermark on a base image. The watermark

 ## API Endpoint

-`POST /api/v1/tools/image/watermark-image`
+`POST /api/v1/tools/watermark-image`

 Accepts multipart form data with **two** image files and a JSON `settings` field.

@@ -30,7 +30,7 @@ Accepts multipart form data with **two** image files and a JSON `settings` field
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/watermark-image \
+curl -X POST http://localhost:1349/api/v1/tools/watermark-image \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F "watermark=@logo.png" \
@@ -8,7 +8,7 @@ Add a text watermark overlay to images. Supports single placement at corners/cen

 ## API Endpoint

-`POST /api/v1/tools/image/watermark-text`
+`POST /api/v1/tools/watermark-text`

 Accepts multipart form data with an image file and a JSON `settings` field.

@@ -26,7 +26,7 @@ Accepts multipart form data with an image file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/watermark-text \
+curl -X POST http://localhost:1349/api/v1/tools/watermark-text \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"text": "SAMPLE", "fontSize": 64, "opacity": 30, "position": "center", "rotation": -30}'
@@ -35,7 +35,7 @@ curl -X POST http://localhost:1349/api/v1/tools/image/watermark-text \
 Tiled watermark across the entire image:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/image/watermark-text \
+curl -X POST http://localhost:1349/api/v1/tools/watermark-text \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@photo.jpg" \
  -F 'settings={"text": "DRAFT", "fontSize": 36, "opacity": 20, "position": "tiled", "rotation": -45}'
@@ -8,7 +8,7 @@ Impose pages for duplex printing so the printed sheets can be folded into a book

 ## API Endpoint

-`POST /api/v1/tools/pdf/booklet-pdf`
+`POST /api/v1/tools/booklet-pdf`

 Accepts multipart form data with a PDF file and a JSON `settings` field.

@@ -21,7 +21,7 @@ Accepts multipart form data with a PDF file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/pdf/booklet-pdf \
+curl -X POST http://localhost:1349/api/v1/tools/booklet-pdf \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@document.pdf" \
  -F 'settings={"perSheet": 2}'
@@ -8,7 +8,7 @@ Reduce PDF file size by downsampling embedded images. Choose between a quality s

 ## API Endpoint

-`POST /api/v1/tools/pdf/compress-pdf`
+`POST /api/v1/tools/compress-pdf`

 Accepts multipart form data with a PDF file and a JSON `settings` field.

@@ -17,7 +17,7 @@ Accepts multipart form data with a PDF file and a JSON `settings` field.
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
 | mode | string | No | `"quality"` | Compression mode: `quality` or `targetSize` |
-| quality | integer | No | - | Compression quality, 1-100 (higher = less compression). Used in `quality` mode |
+| quality | integer | No | `75` | Compression quality, 1-100 (higher = less compression). Used in `quality` mode |
 | targetSizeKb | number | No | - | Target file size in kilobytes. Used in `targetSize` mode |

 ## Example Request
@@ -25,7 +25,7 @@ Accepts multipart form data with a PDF file and a JSON `settings` field.
 Compress by quality:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/pdf/compress-pdf \
+curl -X POST http://localhost:1349/api/v1/tools/compress-pdf \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@document.pdf" \
  -F 'settings={"mode": "quality", "quality": 60}'
@@ -34,7 +34,7 @@ curl -X POST http://localhost:1349/api/v1/tools/pdf/compress-pdf \
 Compress to a target size:

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/pdf/compress-pdf \
+curl -X POST http://localhost:1349/api/v1/tools/compress-pdf \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@document.pdf" \
  -F 'settings={"mode": "targetSize", "targetSizeKb": 500}'
@@ -8,7 +8,7 @@ Convert documents between Word (DOCX), OpenDocument (ODT), RTF, and plain text f

 ## API Endpoint

-`POST /api/v1/tools/pdf/convert-document`
+`POST /api/v1/tools/convert-document`

 Accepts multipart form data with a Word/ODT/RTF/TXT file and a JSON `settings` field.

@@ -21,7 +21,7 @@ Accepts multipart form data with a Word/ODT/RTF/TXT file and a JSON `settings` f
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/pdf/convert-document \
+curl -X POST http://localhost:1349/api/v1/tools/convert-document \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@report.docx" \
  -F 'settings={"format": "odt"}'
@@ -8,7 +8,7 @@ Convert presentations between PowerPoint (PPTX) and OpenDocument Presentation (O

 ## API Endpoint

-`POST /api/v1/tools/pdf/convert-presentation`
+`POST /api/v1/tools/convert-presentation`

 Accepts multipart form data with a PowerPoint/ODP file and a JSON `settings` field.

@@ -21,7 +21,7 @@ Accepts multipart form data with a PowerPoint/ODP file and a JSON `settings` fie
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/pdf/convert-presentation \
+curl -X POST http://localhost:1349/api/v1/tools/convert-presentation \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@slides.pptx" \
  -F 'settings={"format": "odp"}'
@@ -8,7 +8,7 @@ Convert spreadsheets between Excel (XLSX), OpenDocument Spreadsheet (ODS), and C

 ## API Endpoint

-`POST /api/v1/tools/pdf/convert-spreadsheet`
+`POST /api/v1/tools/convert-spreadsheet`

 Accepts multipart form data with an Excel/ODS/CSV file and a JSON `settings` field.

@@ -21,7 +21,7 @@ Accepts multipart form data with an Excel/ODS/CSV file and a JSON `settings` fie
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/pdf/convert-spreadsheet \
+curl -X POST http://localhost:1349/api/v1/tools/convert-spreadsheet \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@data.xlsx" \
  -F 'settings={"format": "csv"}'
@@ -8,7 +8,7 @@ Crop all pages of a PDF by applying a uniform margin, trimming content from each

 ## API Endpoint

-`POST /api/v1/tools/pdf/crop-pdf`
+`POST /api/v1/tools/crop-pdf`

 Accepts multipart form data with a PDF file and a JSON `settings` field.

@@ -21,7 +21,7 @@ Accepts multipart form data with a PDF file and a JSON `settings` field.
 ## Example Request

 ```bash
-curl -X POST http://localhost:1349/api/v1/tools/pdf/crop-pdf \
+curl -X POST http://localhost:1349/api/v1/tools/crop-pdf \
  -H "Authorization: Bearer si_your-api-key" \
  -F "file=@document.pdf" \
  -F 'settings={"margin": 50}'
--- a/Show More
+++ b/Show More