feat(docs-i18n): translate all documentation into 20 languages

All 181 docs markdown files translated into 20 languages (apps/docs/<locale>/**). Companion to the i18n code PR; admin-merged because the file count exceeds GitHub's per-PR CI trigger limit. Validated by pnpm i18n:check (all surfaces, 0 stale/missing) and a clean all-locale docs build.
2026-08-03 07:46:42 +02:00 · 2026-07-11 13:52:47 +08:00
parent 00b651c9f8
commit 4963ab3bbd
3620 changed files with 306134 additions and 0 deletions
@@ -0,0 +1,438 @@
+---
+description: "Dokumentacja silnika AI ze wszystkimi lokalnymi narzędziami ML. Usuwanie tła, powiększanie, OCR, wykrywanie twarzy, renowacja zdjęć i więcej."
+i18n_source_hash: 14728c1dcd05
+i18n_provenance: machine
+i18n_output_hash: d38bde507e84
+---
+
+# Dokumentacja silnika AI {#ai-engine-reference}
+
+Pakiet `@snapotter/ai` łączy Node.js z **trwałym procesem pomocniczym Pythona (sidecar)** dla wszystkich operacji ML. Proces dyspozytora pozostaje aktywny między żądaniami, co zapewnia szybkie działanie z rozgrzanego startu. NVIDIA CUDA jest automatycznie wykrywana przy uruchomieniu i używana, gdy jest dostępna; w przeciwnym razie narzędzia AI działają na CPU.
+
+Przyspieszenie iGPU Intel/AMD za pośrednictwem VA-API, Quick Sync lub OpenCL nie jest obecnie obsługiwane dla wnioskowania AI. Mapowanie `/dev/dri` do kontenera nie przyspiesza tych narzędzi procesu pomocniczego Pythona, chyba że dostępny jest GPU NVIDIA obsługujący CUDA.
+
+19 narzędzi AI procesu pomocniczego Pythona w czterech modalnościach (obraz, dźwięk, wideo, dokument), plus 2 narzędzia z opcjonalnymi funkcjami AI. Wszystkie modele działają lokalnie - po początkowym pobraniu modeli internet nie jest wymagany.
+
+## Architektura {#architecture}
+
+```
+Node.js Tool Route
+      |
+      v
+ @snapotter/ai bridge.ts
+      | (stdin/stdout JSON + stderr progress events)
+      v
+ Python dispatcher (persistent process, "ai" profile)
+      |
+      |-- remove_bg.py        (rembg / BiRefNet)
+      |-- upscale.py          (RealESRGAN)
+      |-- inpaint.py          (LaMa ONNX)
+      |-- outpaint.py         (LaMa canvas expansion)
+      |-- ocr.py              (PaddleOCR / Tesseract)
+      |-- ocr_pdf.py          (page-by-page document OCR)
+      |-- ocr_preprocess.py   (image enhancement for OCR)
+      |-- detect_faces.py     (MediaPipe)
+      |-- face_landmarks.py   (MediaPipe landmarks)
+      |-- enhance_faces.py    (GFPGAN / CodeFormer)
+      |-- colorize.py         (DDColor)
+      |-- noise_removal.py    (SCUNet / tiered denoising)
+      |-- red_eye_removal.py  (landmark + color analysis)
+      |-- restore.py          (scratch repair + enhancement + denoising)
+      |-- transcribe.py       (faster-whisper speech-to-text)
+      +-- install_feature.py  (on-demand bundle installer)
+```
+
+Oddzielny profil dyspozytora "docs" zastępuje listę dozwolonych AI skryptami do przetwarzania dokumentów (`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`) i pomija ciężkie importy ML.
+
+**Limity czasu:** 300 s domyślnie; OCR i usuwanie tła BiRefNet otrzymują 600 s.
+
+## Pakiety funkcji {#feature-bundles}
+
+Modele AI są pakowane według współdzielonego stosu zależności, a nie jako jedno archiwum na narzędzie. Pakiet funkcji może włączyć kilka narzędzi, gdy używają tej samej rodziny modeli, tych samych pakietów wheel Pythona lub natywnych bibliotek. Utrzymuje to mniejszy rozmiar wydania obrazu Docker i pozwala uniknąć przechowywania zduplikowanych kopii tych samych modeli mattingu tła, wykrywania twarzy, OCR, renowacji i mowy.
+
+Obraz Docker dostarcza aplikację oraz wspólne środowisko uruchomieniowe. Duże archiwa modeli są pobierane na żądanie do trwałego woluminu `/data/ai`, a następnie ponownie wykorzystywane przez każde narzędzie, które ich potrzebuje. Jeśli pakiet jest już zainstalowany, ponieważ inne narzędzie go potrzebowało, włączenie nowego zależnego narzędzia nie powoduje ponownego pobrania tego pakietu.
+
+Każde narzędzie AI wymaga jednego lub więcej pakietów funkcji, zanim będzie mogło działać. Interfejs administratora instaluje według narzędzia poprzez `POST /api/v1/admin/tools/:toolId/features/install`, które rozwiązuje pełną listę pakietów, pomija pakiety już zainstalowane i kolejkuje tylko brakujące pobrania. Na przykład włączenie Zdjęcia paszportowego na świeżej instancji kolejkuje `background-removal` i `face-detection`; włączenie go po zainstalowaniu już Usuwania tła kolejkuje tylko `face-detection`.
+
+| Pakiet | Rozmiar | Współdzielona grupa zależności | Narzędzia, które go używają |
+|--------|------|-------------------------|-------------------|
+| `background-removal` | 4-5 GB | matting tła rembg / BiRefNet | remove-background, passport-photo, transparency-fixer, background-replace, blur-background |
+| `face-detection` | 200-300 MB | wykrywanie twarzy i punktów charakterystycznych MediaPipe | blur-faces, red-eye-removal, smart-crop |
+| `object-eraser-colorize` | 1-2 GB | inpainting/outpainting LaMa oraz DDColor | erase-object, colorize, ai-canvas-expand |
+| `upscale-enhance` | 5-6 GB | RealESRGAN, GFPGAN / CodeFormer, odszumianie | upscale, enhance-faces, noise-removal |
+| `photo-restoration` | 4-5 GB | naprawa rys i potok renowacji | restore-photo |
+| `ocr` | 5-6 GB | stos OCR PaddleOCR / Tesseract | ocr, ocr-pdf |
+| `transcription` | ~600 MB | modele mowy na tekst faster-whisper | transcribe-audio, auto-subtitles |
+
+Narzędzia z zależnościami międzypakietowymi:
+
+| Narzędzie | Wymagane pakiety | Dlaczego |
+|------|------------------|-----|
+| `passport-photo` | `background-removal`, `face-detection` | Usuwa tło, a następnie używa punktów charakterystycznych twarzy do wykadrowania zgodnie z zasadami zdjęć paszportowych i dowodowych. |
+| `enhance-faces` | `upscale-enhance`, `face-detection` | Wykrywa twarze przed uruchomieniem ulepszenia GFPGAN lub CodeFormer na wybranych obszarach twarzy. |
+
+Narzędzie jest dostępne tylko wtedy, gdy zainstalowane są wszystkie jego wymagane pakiety. Częściowe instalacje są prawidłowe i obsługiwane przyrostowo: zainstalowane pakiety są ponownie wykorzystywane, brakujące pakiety są pokazywane jako pobrania, a zakolejkowane instalacje uruchamiają się pojedynczo, aby współdzielone środowisko Pythona nie było modyfikowane równocześnie.
+
+---
+
+## Usuwanie tła {#background-removal}
+
+**Trasa narzędzia:** `remove-background`  
+**Model:** rembg z BiRefNet (domyślnie) lub warianty U2-Net
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `model` | string | - | Wariant modelu (opcjonalne nadpisanie) |
+| `backgroundType` | string | `"transparent"` | Jeden z: `transparent`, `color`, `gradient`, `blur`, `image` |
+| `backgroundColor` | string | - | Kolor hex dla jednolitego tła |
+| `gradientColor1` | string | - | Pierwszy kolor gradientu |
+| `gradientColor2` | string | - | Drugi kolor gradientu |
+| `gradientAngle` | number | - | Kąt gradientu w stopniach |
+| `blurEnabled` | boolean | - | Włącz efekt rozmycia tła |
+| `blurIntensity` | number (0-100) | - | Intensywność rozmycia |
+| `shadowEnabled` | boolean | - | Włącz cień pod obiektem |
+| `shadowOpacity` | number (0-100) | - | Krycie cienia |
+| `outputFormat` | string | - | Format wyjściowy: `png`, `webp` lub `avif` |
+| `edgeRefine` | integer (0-3) | - | Poziom wygładzania krawędzi |
+| `decontaminate` | boolean | - | Usuń przenikanie koloru z krawędzi |
+
+## Zamiana tła {#background-replace}
+
+**Trasa narzędzia:** `background-replace`  
+**Model:** rembg / BiRefNet (współdzielony z remove-background)
+
+Usuwa tło i zastępuje je jednolitym kolorem lub gradientem.
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `backgroundType` | `"color"` \| `"gradient"` | `"color"` | Tryb tła |
+| `color` | string | `"#ffffff"` | Kolor hex tła (gdy `backgroundType` to `color`) |
+| `gradientColor1` | string | - | Pierwszy kolor hex gradientu |
+| `gradientColor2` | string | - | Drugi kolor hex gradientu |
+| `gradientAngle` | integer (0-360) | `180` | Kąt gradientu w stopniach |
+| `feather` | integer (0-20) | `0` | Promień wtapiania krawędzi |
+| `format` | `"png"` \| `"webp"` | `"png"` | Format wyjściowy |
+
+## Rozmycie tła {#blur-background}
+
+**Trasa narzędzia:** `blur-background`  
+**Model:** rembg / BiRefNet (współdzielony z remove-background)
+
+Rozmywa tło, zachowując ostrość obiektu.
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `intensity` | integer (1-100) | `50` | Intensywność rozmycia |
+| `feather` | integer (0-20) | `0` | Promień wtapiania krawędzi |
+| `format` | `"png"` \| `"webp"` | `"png"` | Format wyjściowy |
+
+## Powiększanie obrazu {#image-upscaling}
+
+**Trasa narzędzia:** `upscale`  
+**Model:** RealESRGAN (z rezerwowym Lanczos, gdy niedostępny)
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `scale` | number | `2` | Współczynnik powiększenia |
+| `model` | string | `"auto"` | Wariant modelu |
+| `faceEnhance` | boolean | `false` | Zastosuj przebieg ulepszania twarzy GFPGAN |
+| `denoise` | number | `0` | Siła odszumiania |
+| `format` | string | `"auto"` | Nadpisanie formatu wyjściowego |
+| `quality` | number | `95` | Jakość wyjściowa (1-100) |
+
+## OCR / Wyodrębnianie tekstu {#ocr-text-extraction}
+
+**Trasa narzędzia:** `ocr`  
+**Modele:** Tesseract (szybki), PaddleOCR PP-OCRv5 (zrównoważony), PaddleOCR-VL 1.5 (najlepszy)
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Poziom przetwarzania |
+| `language` | string | `"auto"` | Język: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
+| `enhance` | boolean | `true` | Wstępnie przetwórz obraz, aby poprawić dokładność OCR |
+| `engine` | string | - | Przestarzałe. Mapuje `tesseract` na `fast`, `paddleocr` na `balanced` |
+
+Zwraca uporządkowane wyniki z ramkami ograniczającymi, wynikami pewności i wyodrębnionymi blokami tekstu.
+
+## OCR PDF {#pdf-ocr}
+
+**Trasa narzędzia:** `ocr-pdf`  
+**Modele:** Ten sam system poziomów co OCR obrazu
+
+Wyodrębnia tekst ze skanowanych dokumentów PDF przy użyciu OCR wspieranego przez AI, strona po stronie.
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Poziom przetwarzania |
+| `language` | string | `"auto"` | Język: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
+| `pages` | string | `"all"` | Wybór stron: `"all"`, `"1-3"`, `"1,3,5"` |
+
+## Rozmycie twarzy / danych osobowych {#face-pii-blur}
+
+**Trasa narzędzia:** `blur-faces`  
+**Model:** wykrywanie twarzy MediaPipe
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `blurRadius` | number (1-100) | `30` | Promień rozmycia gaussowskiego |
+| `sensitivity` | number (0-1) | `0.5` | Próg pewności wykrywania |
+
+## Ulepszanie twarzy {#face-enhancement}
+
+**Trasa narzędzia:** `enhance-faces`  
+**Modele:** GFPGAN, CodeFormer
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `model` | `"auto"` \| `"gfpgan"` \| `"codeformer"` | `"auto"` | Model ulepszania |
+| `strength` | number (0-1) | `0.8` | Siła ulepszania |
+| `sensitivity` | number (0-1) | `0.5` | Próg wykrywania twarzy |
+| `onlyCenterFace` | boolean | `false` | Ulepsz tylko najbardziej centralną twarz |
+
+## Koloryzacja AI {#ai-colorization}
+
+**Trasa narzędzia:** `colorize`  
+**Model:** DDColor (z rezerwowym OpenCV DNN)
+
+Przekształca zdjęcia czarno-białe lub w skali szarości na pełny kolor.
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `intensity` | number (0-1) | `1.0` | Siła nasycenia kolorów |
+| `model` | `"auto"` \| `"ddcolor"` \| `"opencv"` | `"auto"` | Wariant modelu |
+
+## Usuwanie szumu {#noise-removal}
+
+**Trasa narzędzia:** `noise-removal`  
+**Model:** SCUNet (wielopoziomowy potok odszumiania)
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `tier` | `"quick"` \| `"balanced"` \| `"quality"` \| `"maximum"` | `"balanced"` | Poziom przetwarzania |
+| `strength` | number (0-100) | `50` | Siła odszumiania |
+| `detailPreservation` | number (0-100) | `50` | Ile detali zachować; wyższa wartość zachowuje więcej tekstury |
+| `colorNoise` | number (0-100) | `30` | Siła redukcji szumu kolorów |
+| `format` | string | `"original"` | Format wyjściowy: `original`, `png`, `jpeg`, `webp`, `avif`, `jxl` |
+| `quality` | number (1-100) | `90` | Jakość kodowania wyjścia |
+
+## Usuwanie czerwonych oczu {#red-eye-removal}
+
+**Trasa narzędzia:** `red-eye-removal`
+
+Wykrywa punkty charakterystyczne twarzy, lokalizuje obszary oczu i koryguje nadmierne nasycenie kanału czerwonego.
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `sensitivity` | number (0-100) | `50` | Próg wykrywania czerwonych pikseli |
+| `strength` | number (0-100) | `70` | Siła korekcji |
+| `format` | string | - | Nadpisanie formatu wyjściowego (opcjonalne) |
+| `quality` | number (1-100) | `90` | Jakość wyjściowa |
+
+## Renowacja zdjęć {#photo-restoration}
+
+**Trasa narzędzia:** `restore-photo`
+
+Wieloetapowy potok dla starych lub uszkodzonych zdjęć: wykrywanie i naprawa rys/rozdarć, ulepszanie twarzy, odszumianie oraz opcjonalna koloryzacja.
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `scratchRemoval` | boolean | `true` | Wykryj i napraw rysy, rozdarcia |
+| `faceEnhancement` | boolean | `true` | Zastosuj przebieg ulepszania twarzy |
+| `fidelity` | number (0-1) | `0.7` | Siła ulepszania twarzy (wyższa = bardziej zachowawcza) |
+| `denoise` | boolean | `true` | Zastosuj przebieg odszumiania |
+| `denoiseStrength` | number (0-100) | `25` | Siła odszumiania |
+| `colorize` | boolean | `false` | Koloryzuj po renowacji |
+| `colorizeStrength` | number (0-100) | `85` | Intensywność koloryzacji |
+
+## Zdjęcie paszportowe {#passport-photo}
+
+**Trasa narzędzia:** `passport-photo`  
+**Modele:** punkty charakterystyczne twarzy MediaPipe + usuwanie tła BiRefNet
+
+Dwufazowy przepływ pracy: analiza (wykryj twarz + usuń tło), a następnie generowanie (kadrowanie, zmiana rozmiaru, kafelkowanie). Obsługuje ponad 37 krajów w 6 regionach.
+
+### Faza 1: Analiza {#phase-1-analyze}
+
+`POST /api/v1/tools/image/passport-photo/analyze`
+
+Przyjmuje plik obrazu (multipart). Zwraca dane punktów charakterystycznych twarzy, podgląd base64 oraz wymiary obrazu.
+
+### Faza 2: Generowanie {#phase-2-generate}
+
+`POST /api/v1/tools/image/passport-photo/generate`
+
+Przyjmuje treść JSON z wynikami Fazy 1 oraz ustawieniami generowania:
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `jobId` | string | (wymagane) | Identyfikator zadania z Fazy 1 |
+| `filename` | string | (wymagane) | Oryginalna nazwa pliku z Fazy 1 |
+| `countryCode` | string | (wymagane) | Kod kraju ISO (np. `US`, `GB`, `IN`) |
+| `documentType` | string | `"passport"` | Typ dokumentu |
+| `bgColor` | string | `"#FFFFFF"` | Kolor tła hex |
+| `printLayout` | string | `"none"` | Układ wydruku: `none`, `4x6`, `a4`, `letter` |
+| `maxFileSizeKb` | number | `0` | Maksymalny rozmiar pliku w KB (0 = brak limitu) |
+| `dpi` | number (72-1200) | `300` | DPI wyjścia |
+| `customWidthMm` | number | - | Niestandardowa szerokość w mm (nadpisuje specyfikację kraju) |
+| `customHeightMm` | number | - | Niestandardowa wysokość w mm (nadpisuje specyfikację kraju) |
+| `zoom` | number (0.5-3) | `1` | Współczynnik przybliżenia |
+| `adjustX` | number | `0` | Korekta położenia w poziomie |
+| `adjustY` | number | `0` | Korekta położenia w pionie |
+| `landmarks` | object | (wymagane) | Punkty charakterystyczne z Fazy 1 |
+| `imageWidth` | number | (wymagane) | Szerokość obrazu z Fazy 1 |
+| `imageHeight` | number | (wymagane) | Wysokość obrazu z Fazy 1 |
+
+## Usuwanie obiektów (Inpainting) {#object-erasing-inpainting}
+
+**Trasa narzędzia:** `erase-object`  
+**Model:** LaMa przez ONNX Runtime
+
+Maska jest wysyłana jako **druga część pliku** (nazwa pola `mask`), a nie jako base64. Białe piksele w masce wskazują obszary do usunięcia. Ustawienia `format` i `quality` są wysyłane jako pola formularza najwyższego poziomu.
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `file` | file | (wymagane) | Obraz źródłowy (multipart) |
+| `mask` | file | (wymagane) | Obraz maski (multipart, nazwa pola `mask`, biały = usuń) |
+| `format` | string | `"auto"` | Format wyjściowy: `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl` |
+| `quality` | integer (1-100) | `95` | Jakość wyjściowa |
+
+Przyspieszane przez CUDA, gdy dostępny jest GPU NVIDIA.
+
+## Rozszerzanie kadru AI {#ai-canvas-expand}
+
+**Trasa narzędzia:** `ai-canvas-expand`  
+**Model:** outpainting oparty na LaMa
+
+Rozszerza kadr obrazu w dowolnym kierunku i wypełnia nowe obszary treścią wygenerowaną przez AI, która pasuje do istniejącego obrazu.
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `extendTop` | integer | `0` | Piksele do rozszerzenia u góry |
+| `extendRight` | integer | `0` | Piksele do rozszerzenia po prawej |
+| `extendBottom` | integer | `0` | Piksele do rozszerzenia u dołu |
+| `extendLeft` | integer | `0` | Piksele do rozszerzenia po lewej |
+| `tier` | `"fast"` \| `"balanced"` \| `"high"` | `"balanced"` | Poziom jakości |
+| `format` | string | `"auto"` | Format wyjściowy: `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl` |
+| `quality` | integer (1-100) | `95` | Jakość wyjściowa |
+
+Co najmniej jeden kierunek rozszerzenia musi być większy niż 0.
+
+## Inteligentne kadrowanie {#smart-crop}
+
+**Trasa narzędzia:** `smart-crop`  
+**Model:** wykrywanie twarzy MediaPipe (tylko tryb twarzy)
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `mode` | string | `"subject"` | Strategia kadrowania: `subject`, `face`, `trim` |
+| `strategy` | `"attention"` \| `"entropy"` | `"attention"` | Strategia dla trybu obiektu |
+| `width` | integer | - | Szerokość wyjścia |
+| `height` | integer | - | Wysokość wyjścia |
+| `padding` | integer (0-50) | `0` | Procent marginesu wokół obiektu |
+| `facePreset` | string | `"head-shoulders"` | Predefiniowane kadrowanie, gdy `mode=face` |
+| `sensitivity` | number (0-1) | `0.5` | Próg wykrywania twarzy |
+| `threshold` | integer (0-255) | `30` | Próg wykrywania tła (tryb przycinania) |
+| `padToSquare` | boolean | `false` | Dopełnij przycięty wynik do kwadratu |
+| `padColor` | string | `"#ffffff"` | Kolor tła dla dopełnienia kwadratowego |
+| `targetSize` | integer | - | Docelowy rozmiar dla dopełnionego wyjścia (piksele) |
+| `quality` | integer (1-100) | - | Jakość wyjściowa |
+
+Starsze wartości `mode` `attention` i `content` są akceptowane i mapowane odpowiednio na `subject` i `trim`.
+
+**Predefiniowane ustawienia twarzy:**
+
+| Predefiniowane | Najlepsze do |
+|--------|---------|
+| `closeup` | Zdjęcia portretowe |
+| `head-shoulders` | Zdjęcia profilowe |
+| `upper-body` | LinkedIn / formalne |
+| `half-body` | Pełna górna część ciała |
+
+## Transkrypcja dźwięku {#transcribe-audio}
+
+**Trasa narzędzia:** `transcribe-audio`  
+**Model:** faster-whisper
+
+Przekształca mowę na tekst. Obsługuje formaty wyjściowe zwykły tekst, SRT i VTT.
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `language` | string | `"auto"` | Język: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
+| `outputFormat` | `"txt"` \| `"srt"` \| `"vtt"` | `"txt"` | Format wyjściowy |
+
+## Automatyczne napisy {#auto-subtitles}
+
+**Trasa narzędzia:** `auto-subtitles`  
+**Model:** faster-whisper (wyodrębnia dźwięk z wideo, a następnie transkrybuje)
+
+Generuje pliki napisów ze ścieżki dźwiękowej wideo.
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `language` | string | `"auto"` | Język: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
+| `format` | `"srt"` \| `"vtt"` | `"srt"` | Format wyjściowy napisów |
+
+## Naprawa przezroczystości PNG {#png-transparency-fixer}
+
+**Trasa narzędzia:** `transparency-fixer`  
+**Model:** BiRefNet HR-matting (rozdzielczość 2048x2048)
+
+Naprawia "fałszywie przezroczyste" pliki PNG, w których tło zostało usunięte, ale pozostawiło obwódki, aureole lub półprzezroczyste artefakty. Używa modelu mattingu wysokiej rozdzielczości BiRefNet, aby uzyskać czysty kanał alfa, a następnie stosuje konfigurowalne przetwarzanie usuwające przebarwienia w celu usunięcia zanieczyszczenia kolorem wzdłuż krawędzi.
+
+**Łańcuch rezerwowy OOM:** Jeśli BiRefNet HR-matting przekroczy dostępną pamięć, narzędzie automatycznie przechodzi na `birefnet-general`, a następnie na `u2net`.
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `defringe` | number (0-100) | `30` | Siła usuwania obwódek krawędzi w celu usunięcia zanieczyszczenia kolorem |
+| `outputFormat` | `"png"` \| `"webp"` | `"png"` | Format obrazu wyjściowego |
+| `removeWatermark` | boolean | `false` | Zastosuj wstępne przetwarzanie usuwania znaku wodnego (filtr medianowy) |
+
+```bash
+curl -X POST http://localhost:1349/api/v1/tools/image/transparency-fixer \
+  -H "Authorization: Bearer <token>" \
+  -F "file=@fake-transparent.png" \
+  -F 'settings={"defringe":30,"outputFormat":"png"}'
+```
+
+---
+
+## Narzędzia z opcjonalnymi funkcjami AI {#tools-with-optional-ai-capabilities}
+
+Poniższe narzędzia nie są narzędziami procesu pomocniczego Pythona, ale używają funkcji AI, gdy włączone są określone opcje.
+
+### Ulepszanie obrazu {#image-enhancement}
+
+**Trasa narzędzia:** `image-enhancement`  
+**Silnik:** oparty na analizie (histogram i statystyki Sharp)
+
+Analizuje obraz i stosuje automatyczne korekcje ekspozycji, kontrastu, balansu bieli, nasycenia, ostrości i szumu. Obsługuje tryby dostosowane do sceny.
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `mode` | `"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"` | `"auto"` | Tryb sceny do dostrajania korekcji |
+| `intensity` | number (0-100) | `50` | Ogólna siła korekcji |
+| `corrections.exposure` | boolean | `true` | Zastosuj korekcję ekspozycji |
+| `corrections.contrast` | boolean | `true` | Zastosuj korekcję kontrastu |
+| `corrections.whiteBalance` | boolean | `true` | Zastosuj korekcję balansu bieli |
+| `corrections.saturation` | boolean | `true` | Zastosuj korekcję nasycenia |
+| `corrections.sharpness` | boolean | `true` | Zastosuj korekcję ostrości |
+| `corrections.denoise` | boolean | `true` | Zastosuj odszumianie |
+| `deepEnhance` | boolean | `false` | Włącz usuwanie szumu AI przez SCUNet (wymaga pakietu `upscale-enhance`) |
+
+Dodatkowy punkt końcowy analizy jest dostępny pod `POST /api/v1/tools/image/image-enhancement/analyze`, który zwraca wykryte korekcje bez ich stosowania.
+
+### Zmiana rozmiaru z uwzględnieniem treści (Seam Carving) {#content-aware-resize-seam-carving}
+
+**Trasa narzędzia:** `content-aware-resize`  
+**Silnik:** binarka Go `caire` (nie Python - brak korzyści z GPU)
+
+Inteligentnie zmienia rozmiar obrazów, usuwając szwy o niskiej energii i zachowując ważną treść.
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `width` | number | - | Docelowa szerokość |
+| `height` | number | - | Docelowa wysokość |
+| `protectFaces` | boolean | `false` | Chroń wykryte obszary twarzy (wymaga pakietu `face-detection`) |
+| `blurRadius` | number (0-20) | `4` | Wstępne rozmycie do obliczania energii |
+| `sobelThreshold` | number (1-20) | `2` | Próg czułości krawędzi |
+| `square` | boolean | `false` | Wymuś kwadratowe wyjście |
@@ -0,0 +1,211 @@
+---
+description: "Dokumentacja operacji silnika obrazu. Wszystkie operacje przetwarzania obrazu oparte na Sharp i ich parametry."
+i18n_source_hash: 42febdf85fa8
+i18n_provenance: human
+i18n_output_hash: 15a5c0432318
+---
+
+# Silnik obrazu {#image-engine}
+
+Pakiet `@snapotter/image-engine` obsługuje wszystkie operacje na obrazach niezwiązane z AI. Opakowuje [Sharp](https://sharp.pixelplumbing.com/) i działa w całości w procesie, bez zewnętrznych zależności.
+
+## Operacje {#operations}
+
+### resize {#resize}
+
+Skaluje obraz do określonych wymiarów lub o procent.
+
+| Parametr | Typ | Opis |
+|---|---|---|
+| `width` | number | Docelowa szerokość w pikselach |
+| `height` | number | Docelowa wysokość w pikselach |
+| `fit` | string | `cover`, `contain`, `fill`, `inside` lub `outside` |
+| `withoutEnlargement` | boolean | Jeśli true, nie powiększa mniejszych obrazów |
+| `percentage` | number | Skaluj o procent zamiast wymiarów bezwzględnych |
+
+Możesz ustawić `width`, `height` lub oba. Jeśli ustawisz tylko jeden, drugi jest obliczany w celu zachowania proporcji.
+
+### crop {#crop}
+
+Wytnij prostokątny obszar z obrazu.
+
+| Parametr | Typ | Opis |
+|---|---|---|
+| `left` | number | Przesunięcie X od lewej krawędzi |
+| `top` | number | Przesunięcie Y od górnej krawędzi |
+| `width` | number | Szerokość obszaru kadrowania |
+| `height` | number | Wysokość obszaru kadrowania |
+| `unit` | string | `px` (domyślnie) lub `percent` |
+
+### rotate {#rotate}
+
+Obróć obraz o zadany kąt.
+
+| Parametr | Typ | Opis |
+|---|---|---|
+| `angle` | number | Kąt obrotu w stopniach (0-360) |
+| `background` | string | Kolor wypełnienia dla odsłoniętego obszaru (domyślnie: `#000000`). Dotyczy tylko kątów innych niż 90 stopni. |
+
+### flip {#flip}
+
+Odbij obraz w poziomie, w pionie lub oba. Co najmniej jeden musi być true.
+
+| Parametr | Typ | Opis |
+|---|---|---|
+| `horizontal` | boolean | Odbij z lewej na prawą |
+| `vertical` | boolean | Odbij z góry na dół |
+
+### convert {#convert}
+
+Zmień format obrazu.
+
+| Parametr | Typ | Opis |
+|---|---|---|
+| `format` | string | Format docelowy: `jpg`, `png`, `webp`, `avif`, `tiff`, `gif`, `jxl`, `heic`, `heif`, `bmp`, `ico`, `jp2`, `qoi` |
+| `quality` | number | Jakość kompresji (1-100, dotyczy formatów stratnych) |
+
+Pierwszych siedem formatów (od `jpg` do `jxl`) jest kodowanych przez Sharp w procesie. Pozostałe formaty używają zewnętrznych koderów na warstwie API: `heic`/`heif` przez heif-enc, `bmp`/`ico` przez ImageMagick, `jp2` przez opj_compress, a `qoi` przez wbudowany kodek TypeScript.
+
+### compress {#compress}
+
+Zmniejsz rozmiar pliku przy zachowaniu tego samego formatu.
+
+| Parametr | Typ | Opis |
+|---|---|---|
+| `quality` | number | Docelowa jakość (1-100) |
+| `targetSizeBytes` | number | Opcjonalny docelowy rozmiar pliku w bajtach |
+| `format` | string | Opcjonalne nadpisanie formatu |
+
+### strip-metadata {#strip-metadata}
+
+Usuń metadane EXIF, IPTC, XMP i ICC z obrazu. Bez parametrów (lub z `stripAll: true`) usuwa wszystko. Przekaż pojedyncze flagi, aby usuwać selektywnie.
+
+| Parametr | Typ | Opis |
+|---|---|---|
+| `stripAll` | boolean | Usuń wszystkie metadane (domyślnie, gdy nie ustawiono flag) |
+| `stripExif` | boolean | Usuń dane EXIF (w tym GPS, jeśli `stripGps` nie jest ustawione osobno) |
+| `stripGps` | boolean | Usuń dane lokalizacji GPS |
+| `stripIcc` | boolean | Usuń profil kolorów ICC |
+| `stripXmp` | boolean | Usuń metadane XMP |
+
+### Regulacje koloru {#color-adjustments}
+
+Te operacje modyfikują właściwości koloru obrazu. Każda przyjmuje pojedynczą wartość liczbową.
+
+| Operacja | Parametr | Zakres | Opis |
+|---|---|---|---|
+| `brightness` | `value` | -100 do 100 | Reguluj jasność |
+| `contrast` | `value` | -100 do 100 | Reguluj kontrast |
+| `saturation` | `value` | -100 do 100 | Reguluj nasycenie koloru |
+
+### Filtry koloru {#color-filters}
+
+Te stosują stałą transformację koloru. Nie przyjmują parametrów.
+
+| Operacja | Opis |
+|---|---|
+| `grayscale` | Konwertuj do skali szarości |
+| `sepia` | Zastosuj tonację sepii |
+| `invert` | Odwróć wszystkie kolory |
+
+### Kanały koloru {#color-channels}
+
+Reguluj poszczególne kanały koloru RGB. Wartości są mnożnikami, gdzie 100 = bez zmian.
+
+| Parametr | Typ | Opis |
+|---|---|---|
+| `red` | number | Mnożnik kanału czerwonego (0 do 200, 100 = bez zmian) |
+| `green` | number | Mnożnik kanału zielonego (0 do 200, 100 = bez zmian) |
+| `blue` | number | Mnożnik kanału niebieskiego (0 do 200, 100 = bez zmian) |
+
+### sharpen {#sharpen}
+
+Proste wyostrzanie sterowane pojedynczą wartością.
+
+| Parametr | Typ | Opis |
+|---|---|---|
+| `value` | number | Intensywność wyostrzania (0 do 100). Mapowana na sigmę gaussowską 0.5-10. |
+
+### sharpen-advanced {#sharpen-advanced}
+
+Zaawansowane wyostrzanie z trzema wybieralnymi metodami i opcjonalnym przebiegiem wstępnej redukcji szumu.
+
+| Parametr | Typ | Opis |
+|---|---|---|
+| `method` | string | `adaptive`, `unsharp-mask` lub `high-pass` |
+| `sigma` | number | Promień rozmycia gaussowskiego, 0.5-10 (adaptacyjny) |
+| `m1` | number | Wyostrzanie obszarów płaskich, 0-10 (adaptacyjne) |
+| `m2` | number | Wyostrzanie obszarów teksturowanych, 0-20 (adaptacyjne) |
+| `x1` | number | Próg płaski/postrzępiony, 0-10 (adaptacyjny) |
+| `y2` | number | Maks. rozjaśnienie (ograniczenie aureoli), 0-50 (adaptacyjne) |
+| `y3` | number | Maks. przyciemnienie (ograniczenie aureoli), 0-50 (adaptacyjne) |
+| `amount` | number | Procent intensywności, 0-500 (unsharp-mask) |
+| `radius` | number | Promień rozmycia, 0.1-5.0 (unsharp-mask) |
+| `threshold` | number | Minimalna jasność krawędzi, 0-255 (unsharp-mask) |
+| `strength` | number | Siła mieszania, 0-100 (high-pass) |
+| `kernelSize` | number | `3` lub `5` dla jądra 3x3 / 5x5 (high-pass) |
+| `denoise` | string | Wstępny przebieg redukcji szumu: `off`, `light`, `medium` lub `strong` |
+
+Parametry są specyficzne dla metody. Podawaj tylko te istotne dla wybranej metody.
+
+### color-blindness {#color-blindness}
+
+Symuluj zaburzenie widzenia barw za pomocą macierzy rekombinacji koloru 3x3.
+
+| Parametr | Typ | Opis |
+|---|---|---|
+| `type` | string | Jeden z: `protanopia`, `deuteranopia`, `tritanopia`, `protanomaly`, `deuteranomaly`, `tritanomaly`, `achromatopsia`, `blueConeMonochromacy` |
+
+### edit-metadata {#edit-metadata}
+
+Zapisz lub usuń poszczególne pola metadanych EXIF/IPTC bez usuwania całego bloku.
+
+| Parametr | Typ | Opis |
+|---|---|---|
+| `artist` | string | Tag EXIF Artist |
+| `copyright` | string | Tag EXIF Copyright |
+| `imageDescription` | string | Tag EXIF ImageDescription |
+| `software` | string | Tag EXIF Software |
+| `dateTime` | string | Tag EXIF DateTime |
+| `dateTimeOriginal` | string | Tag EXIF DateTimeOriginal |
+| `clearGps` | boolean | Usuń wszystkie tagi GPS |
+| `fieldsToRemove` | string[] | Lista nazw pól EXIF do usunięcia |
+
+Wszystkie parametry są opcjonalne. Pola wymienione w `fieldsToRemove` są usuwane z istniejącego bloku EXIF. Pola ustawione za pomocą nazwanych parametrów są zapisywane (lub nadpisywane). Klucze binarne/niebezpieczne, takie jak MakerNote, są po cichu ignorowane.
+
+## Wykrywanie formatu {#format-detection}
+
+Silnik wykrywa formaty wejściowe automatycznie na podstawie nagłówków plików, a nie tylko rozszerzeń plików. Oznacza to, że plik `.jpg`, który w rzeczywistości jest plikiem PNG, zostanie obsłużony poprawnie. Wykrywanie wykorzystuje podejście wielowarstwowe: najpierw magiczne bajty, a następnie rozszerzenie pliku jako rozwiązanie awaryjne.
+
+SnapOtter obsługuje **ponad 55 formatów wejściowych** i **13 formatów wyjściowych**, w tym 23 formaty RAW aparatów od ponad 20 marek, formaty profesjonalne (PSD, EPS, OpenEXR, HDR), nowoczesne kodeki (JPEG XL, AVIF, HEIC, QOI, JPEG 2000) oraz formaty naukowe/growe (FITS, DDS). Dekodowanie jest obsługiwane natywnie przez Sharp tam, gdzie to możliwe, z automatycznym rozwiązaniem awaryjnym w postaci ImageMagick, LibRaw i wyspecjalizowanych dekoderów CLI.
+
+Zobacz stronę [Obsługiwane formaty](/pl/guide/supported-formats), aby uzyskać pełną listę.
+
+## Ekstrakcja metadanych {#metadata-extraction}
+
+Narzędzie `info` zwraca metadane obrazu. Zobacz [Informacje o obrazie](/pl/tools/image/info), aby uzyskać pełny wykaz pól.
+
+```json
+{
+  "filename": "photo.jpg",
+  "fileSize": 2450000,
+  "width": 4032,
+  "height": 3024,
+  "format": "jpeg",
+  "channels": 3,
+  "hasAlpha": false,
+  "colorSpace": "srgb",
+  "density": 72,
+  "isProgressive": false,
+  "hasExif": true,
+  "hasIcc": true,
+  "hasXmp": false,
+  "bitDepth": "8",
+  "pages": 1,
+  "histogram": [
+    { "channel": "red", "min": 0, "max": 255, "mean": 128.45, "stdev": 52.31 },
+    { "channel": "green", "min": 2, "max": 253, "mean": 115.22, "stdev": 48.76 },
+    { "channel": "blue", "min": 0, "max": 250, "mean": 102.89, "stdev": 55.14 }
+  ]
+}
+```
@@ -0,0 +1,702 @@
+---
+description: "Kompletna dokumentacja API REST. Punkty końcowe narzędzi, przetwarzanie wsadowe, potoki, biblioteka plików, uwierzytelnianie, zespoły i operacje administracyjne."
+i18n_source_hash: 8646977f7cc9
+i18n_provenance: machine
+i18n_output_hash: 4b25a4ffd694
+---
+
+# Dokumentacja API REST {#rest-api-reference}
+
+Interaktywna dokumentacja API z przykładami żądań i odpowiedzi jest dostępna pod adresem [http://localhost:1349/api/docs](http://localhost:1349/api/docs).
+
+Specyfikacje odczytywalne maszynowo:
+- `/api/v1/openapi.yaml` - specyfikacja OpenAPI 3.1
+- `/llms.txt` - podsumowanie przyjazne dla LLM
+- `/llms-full.txt` - kompletna dokumentacja przyjazna dla LLM
+
+## Uwierzytelnianie {#authentication}
+
+Wszystkie punkty końcowe wymagają uwierzytelnienia, chyba że `AUTH_ENABLED=false`.
+
+### Token sesji {#session-token}
+
+```bash
+# Login
+curl -X POST http://localhost:1349/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin"}'
+# Returns: {"token":"<session-token>"}
+
+# Use token
+curl http://localhost:1349/api/v1/tools/image/resize \
+  -H "Authorization: Bearer <session-token>"
+```
+
+Sesje wygasają po 7 dniach (konfigurowalne za pomocą `SESSION_DURATION_HOURS`).
+
+### Klucze API {#api-keys}
+
+```bash
+# Create a key (returns key once - store it)
+curl -X POST http://localhost:1349/api/v1/api-keys \
+  -H "Authorization: Bearer <session-token>" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"my-script"}'
+# Returns: {"key":"si_<96 hex chars>","id":"...","name":"my-script"}
+
+# Use the key
+curl http://localhost:1349/api/v1/tools/image/resize \
+  -H "Authorization: Bearer si_<your-key>"
+```
+
+Klucze są poprzedzone przedrostkiem `si_` i przechowywane jako skróty scrypt - surowy klucz jest pokazywany raz i nigdy więcej nie można go odzyskać.
+
+### Punkty końcowe uwierzytelniania {#auth-endpoints}
+
+| Metoda | Ścieżka | Dostęp | Opis |
+|--------|------|--------|-------------|
+| `POST` | `/api/auth/login` | Publiczny | Logowanie, uzyskanie tokena sesji |
+| `POST` | `/api/auth/logout` | Uwierzytelniony | Zniszczenie bieżącej sesji |
+| `GET` | `/api/auth/session` | Uwierzytelniony | Weryfikacja bieżącej sesji |
+| `POST` | `/api/auth/change-password` | Uwierzytelniony | Zmiana własnego hasła (unieważnia wszystkie inne sesje + klucze API) |
+| `GET` | `/api/auth/users` | Administrator | Lista wszystkich użytkowników |
+| `POST` | `/api/auth/register` | Administrator | Utworzenie nowego użytkownika |
+| `PUT` | `/api/auth/users/:id` | Administrator | Aktualizacja roli lub zespołu użytkownika |
+| `POST` | `/api/auth/users/:id/reset-password` | Administrator | Zresetowanie hasła użytkownika |
+| `DELETE` | `/api/auth/users/:id` | Administrator | Usunięcie użytkownika |
+| `GET` | `/api/v1/config/auth` | Publiczny | Sprawdzenie, czy uwierzytelnianie jest włączone (`{ authEnabled: bool }`) |
+| `POST` | `/api/auth/mfa/enroll` | Uwierzytelniony | Rozpoczęcie rejestracji TOTP MFA. Wymaga funkcji enterprise `mfa` |
+| `POST` | `/api/auth/mfa/verify` | Uwierzytelniony | Potwierdzenie rejestracji MFA kodem TOTP |
+| `POST` | `/api/auth/mfa/complete` | Publiczny | Zakończenie oczekującego wyzwania logowania MFA |
+| `POST` | `/api/auth/mfa/disable` | Uwierzytelniony | Wyłączenie MFA dla bieżącego użytkownika |
+| `POST` | `/api/auth/users/:id/mfa/reset` | Administrator (`users:manage`) | Zresetowanie MFA dla użytkownika |
+| `GET` | `/api/auth/oidc/login` | Publiczny | Rozpoczęcie logowania OIDC, gdy OIDC jest włączony |
+| `GET` | `/api/auth/oidc/callback` | Publiczny | Wywołanie zwrotne autoryzacji OIDC |
+| `GET` | `/api/auth/saml/metadata` | Publiczny | Metadane XML SAML SP, gdy SAML jest włączony |
+| `GET` | `/api/auth/saml/login` | Publiczny | Rozpoczęcie logowania SAML |
+| `POST` | `/api/auth/saml/callback` | Publiczny | Usługa konsumenta asercji SAML |
+
+Gdy MFA jest włączone dla użytkownika, `POST /api/auth/login` zwraca `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` zamiast tokena sesji. Wyślij ten `mfaToken` wraz z kodem TOTP lub kodem odzyskiwania do `/api/auth/mfa/complete`.
+
+### Uprawnienia {#permissions}
+
+| Uprawnienie | Administrator | Użytkownik |
+|-----------|:-----:|:----:|
+| Korzystanie z narzędzi | ✓ | ✓ |
+| Własne pliki/potoki/klucze API | ✓ | ✓ |
+| Podgląd plików/potoków/kluczy wszystkich użytkowników | ✓ | - |
+| Zapis ustawień | ✓ | - |
+| Zarządzanie użytkownikami i zespołami | ✓ | - |
+| Zarządzanie marką | ✓ | - |
+
+## Kontrola stanu {#health-check}
+
+| Metoda | Ścieżka | Dostęp | Opis |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/health` | Publiczny | Podstawowa kontrola stanu. Zwraca `{"status":"healthy","version":"..."}` z kodem 200 lub `{"status":"unhealthy"}` z kodem 503, jeśli baza danych jest nieosiągalna. |
+| `GET` | `/api/v1/readyz` | Publiczny | Sonda gotowości. Sprawdza PostgreSQL, Redis, miejsce na dysku oraz S3, gdy jest skonfigurowane. Zwraca 503, gdy instancja nie powinna odbierać ruchu. |
+| `GET` | `/api/v1/admin/health` | Administrator (`system:health`) | Szczegółowa diagnostyka obejmująca czas działania, tryb przechowywania, stan bazy danych, stan kolejki i dostępność GPU. |
+
+## Korzystanie z narzędzi {#using-tools}
+
+Każde narzędzie działa według tego samego wzorca:
+
+```bash
+# Single file
+curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId> \
+  -H "Authorization: Bearer <token>" \
+  -F "file=@input.jpg" \
+  -F 'settings={"width":800,"height":600}'
+
+# Batch (returns ZIP)
+curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId>/batch \
+  -H "Authorization: Bearer <token>" \
+  -F "files=@a.jpg" \
+  -F "files=@b.jpg" \
+  -F 'settings={...}'
+```
+
+`<section>` jest jednym z `image`, `video`, `audio`, `pdf` lub `files`.
+
+- Przesyłany plik ma pole `multipart/form-data`.
+- `settings` to ciąg JSON z opcjami specyficznymi dla narzędzia.
+- `clientJobId` to opcjonalne pole formularza służące do korelacji postępu dostarczanej przez wywołującego.
+- `fileId` to opcjonalne pole formularza odwołujące się do istniejącego elementu biblioteki plików. Gdy jest obecne, przetworzony wynik jest zapisywany jako nowa wersja, a odpowiedź zawiera `savedFileId`.
+- **Szybkie narzędzia** zwykle zwracają JSON z kodem 200: `{"jobId":"...","downloadUrl":"/api/v1/download/<jobId>/<filename>","originalSize":1234,"processedSize":567}`. Pobierz przetworzony plik z `downloadUrl`.
+- **Każde narzędzie w kolejce** może zwrócić JSON z kodem 202, jeśli działa długo lub przekracza okno synchronicznego oczekiwania: `{"jobId":"...","async":true}`. Połącz się z SSE, aby śledzić postęp, a następnie pobierz plik po zakończeniu (zobacz [Śledzenie postępu](#progress-tracking)).
+- **Trasy wsadowe** zwracają archiwum ZIP przesyłane bezpośrednio strumieniowo (z nagłówkiem `X-Job-Id`) dla narzędzi zarejestrowanych w ogólnym rejestrze wsadowym.
+
+## Dokumentacja narzędzi {#tools-reference}
+
+### Ustawienia wstępne konwersji {#conversion-presets}
+
+Wspólny katalog zawiera 83 dedykowane punkty końcowe ustawień wstępnych konwersji, takie jak `jpg-to-png`, `mov-to-mp4`, `m4a-to-mp3`, `pdf-to-jpg` i `excel-to-csv`. Ustawienia wstępne to pełnoprawne trasy narzędzi:
+
+`POST /api/v1/tools/<section>/<presetId>`
+
+Każde ustawienie wstępne blokuje format wyjściowy i deleguje do narzędzia bazowego, takiego jak `convert`, `convert-video`, `extract-audio`, `convert-audio`, `image-to-pdf`, `pdf-to-image`, `svg-to-raster` lub `convert-spreadsheet`. Zobacz [Ustawienia wstępne konwersji](/pl/tools/conversion-presets), aby uzyskać kompletną tabelę tras i opcjonalne ustawienia.
+
+### Podstawy {#essentials}
+
+| ID narzędzia | Nazwa | Kluczowe ustawienia |
+|---------|------|-------------|
+| `resize` | Zmiana rozmiaru | `width`, `height`, `fit` (cover/contain/fill/inside/outside), `percentage`, `withoutEnlargement`, plus 23 ustawienia wstępne mediów społecznościowych |
+| `crop` | Kadrowanie | `left`, `top`, `width`, `height`, `unit` (px/percent) |
+| `rotate` | Obrót i odbicie | `angle`, `horizontal` (bool), `vertical` (bool) |
+| `convert` | Konwersja | `format` (jpg/png/webp/avif/tiff/gif/heic/heif), `quality` |
+| `compress` | Kompresja | `mode` (quality/targetSize), `quality` (1–100), `targetSizeKb` |
+
+### Optymalizacja {#optimization}
+
+| ID narzędzia | Nazwa | Kluczowe ustawienia |
+|---------|------|-------------|
+| `optimize-for-web` | Optymalizacja pod kątem internetu | `format` (webp/jpeg/avif/png), `quality`, `maxWidth`, `maxHeight`, `progressive`, `stripMetadata` |
+| `strip-metadata` | Usuwanie metadanych | - |
+| `edit-metadata` | Edycja metadanych | `title`, `description`, `author`, `copyright`, `keywords`, `gps` (lat/lon), `dateTime` |
+| `bulk-rename` | Zmiana nazw zbiorczo | `pattern` (obsługuje `{n}`, `{date}`, `{original}`), `startIndex`, `padding` |
+| `image-to-pdf` | Obraz do PDF | `pageSize` (A4/Letter/...), `orientation`, `margin`, `targetSize` ({value, unit}) |
+| `favicon` | Generator favicon | `padding`, `backgroundColor`, `borderRadius` - generuje wszystkie standardowe rozmiary |
+
+### Korekty {#adjustments}
+
+| ID narzędzia | Nazwa | Kluczowe ustawienia |
+|---------|------|-------------|
+| `adjust-colors` | Korekta kolorów | `brightness`, `contrast`, `exposure`, `saturation`, `temperature`, `tint`, `hue`, `sharpness`, `red`, `green`, `blue`, `effect` (none/grayscale/sepia/invert) |
+| `sharpening` | Wyostrzanie | `method` (adaptive/unsharp-mask/high-pass), `sigma`, `m1`, `m2`, `x1`, `y2`, `y3`, `amount`, `radius`, `threshold`, `strength`, `kernelSize` (3/5), `denoise` (off/light/medium/strong) |
+| `replace-color` | Zamiana koloru | `sourceColor`, `targetColor` (zamiennik), `makeTransparent`, `tolerance` |
+| `color-blindness` | Symulacja daltonizmu | `simulationType` (protanopia/deuteranopia/tritanopia/protanomaly/deuteranomaly/tritanomaly/achromatopsia/blueConeMonochromacy, domyślnie "deuteranomaly") |
+| `duotone` | Duotone | `shadow` (hex), `highlight` (hex), `intensity` (0-100) |
+| `pixelate` | Pikselizacja | `blockSize` (2-128), `region` ({left, top, width, height} dla częściowej pikselizacji) |
+| `vignette` | Winieta | `strength` (0.1-1), `color` (hex), `radius`, `softness`, `roundness`, `centerX`, `centerY` |
+
+### Narzędzia AI {#ai-tools}
+
+Wszystkie narzędzia AI działają na Twoim sprzęcie: domyślnie na CPU lub na NVIDIA CUDA, gdy dostępny jest obsługiwany procesor graficzny NVIDIA. Akceleracja iGPU firm Intel/AMD przez VA-API, Quick Sync lub OpenCL nie jest obecnie obsługiwana dla wnioskowania AI. Nie wymaga połączenia z internetem.
+
+| ID narzędzia | Nazwa | Model AI | Kluczowe ustawienia |
+|---------|------|---------|-------------|
+| `remove-background` | Usuwanie tła | rembg (BiRefNet / U2-Net) | `model`, `backgroundType` (transparent/color/gradient/blur/image), `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurEnabled`, `blurIntensity`, `shadowEnabled`, `shadowOpacity` |
+| `upscale` | Powiększanie obrazu | RealESRGAN | `scale` (2/4), `model`, `faceEnhance`, `denoise`, `format`, `quality` |
+| `erase-object` | Wymazywanie obiektów | LaMa (ONNX) | Maska wysyłana jako druga część pliku (nazwa pola `mask`), `format`, `quality` |
+| `ocr` | OCR / Ekstrakcja tekstu | PaddleOCR / Tesseract | `quality` (fast/balanced/best), `language`, `enhance` |
+| `blur-faces` | Rozmycie twarzy / PII | MediaPipe | `blurRadius`, `sensitivity` |
+| `smart-crop` | Inteligentne kadrowanie | MediaPipe + Sharp | `mode` (subject/face/trim), `strategy` (attention/entropy), `width`, `height`, `padding`, `facePreset` (closeup/head-shoulders/upper-body/half-body), `sensitivity`, `threshold`, `padToSquare`, `padColor`, `targetSize`, `quality` |
+| `image-enhancement` | Poprawa obrazu | Oparte na analizie | `mode` (auto/exposure/contrast/color/sharpness), `strength` |
+| `enhance-faces` | Poprawa twarzy | GFPGAN / CodeFormer | `model` (gfpgan/codeformer), `strength`, `sensitivity`, `centerFace` |
+| `colorize` | Koloryzacja AI | DDColor | `intensity`, `model` |
+| `noise-removal` | Usuwanie szumów | Wielopoziomowe odszumianie | `tier` (quick/balanced/quality/maximum), `strength`, `detailPreservation`, `colorNoise`, `format`, `quality` |
+| `red-eye-removal` | Usuwanie efektu czerwonych oczu | Punkty charakterystyczne twarzy + analiza kolorów | `sensitivity`, `strength` |
+| `restore-photo` | Rekonstrukcja zdjęć | Wieloetapowy potok | `mode` (auto/light/heavy), `scratchRemoval`, `faceEnhancement`, `fidelity`, `denoise`, `denoiseStrength`, `colorize` |
+| `passport-photo` | Zdjęcie paszportowe | Punkty charakterystyczne MediaPipe | Dwufazowy przepływ. Analiza używa multipart `file`; generowanie używa JSON z `countryCode`, `bgColor`, `printLayout` (none/4x6/a4), punktami charakterystycznymi, wymiarami obrazu |
+| `content-aware-resize` | Zmiana rozmiaru z zachowaniem treści | Wycinanie szwów (caire) | `width`, `height`, `protectFaces`, `blurRadius`, `sobelThreshold`, `square` |
+| `transparency-fixer` | Naprawa przezroczystości PNG | BiRefNet HR-matting | `defringe` (0-100), `outputFormat` (png/webp) |
+| `background-replace` | Zamiana tła | rembg (BiRefNet) | `backgroundType` (color/gradient), `color` (hex), `gradientColor1`, `gradientColor2`, `gradientAngle`, `feather` (0-20), `format` (png/webp) |
+| `blur-background` | Rozmycie tła | rembg (BiRefNet) | `intensity` (1-100), `feather` (0-20), `format` (png/webp) |
+| `ai-canvas-expand` | Rozszerzanie płótna AI | LaMa (outpainting) | `extendTop`, `extendRight`, `extendBottom`, `extendLeft` (px), `tier` (fast/balanced/high), `format`, `quality` |
+
+### Znak wodny i nakładka {#watermark-overlay}
+
+| ID narzędzia | Nazwa | Kluczowe ustawienia |
+|---------|------|-------------|
+| `watermark-text` | Tekstowy znak wodny | `text`, `font`, `fontSize`, `color`, `opacity`, `position`, `rotation`, `tile` |
+| `watermark-image` | Graficzny znak wodny | `opacity`, `position`, `scale` - drugi plik jest znakiem wodnym |
+| `text-overlay` | Nakładka tekstowa | `text`, `font`, `fontSize`, `color`, `x`, `y`, `background`, `padding`, `borderRadius` |
+| `compose` | Kompozycja obrazu | `x`, `y`, `opacity`, `blend` - drugi plik jest nakładany na wierzch |
+| `meme-generator` | Generator memów | `templateId`, `textLayout` (top-bottom/top-only/bottom-only/center/side-by-side), `textBoxes` ([{id, text}]), `fontFamily` (anton/arial-black/comic-sans/montserrat/bebas-neue/permanent-marker/roboto), `fontSize`, `textColor`, `strokeColor`, `textAlign`, `allCaps`. Obsługuje tryb szablonu (treść JSON z `templateId`) lub tryb obrazu niestandardowego (multipart z plikiem). |
+
+### Narzędzia pomocnicze {#utilities}
+
+| ID narzędzia | Nazwa | Kluczowe ustawienia |
+|---------|------|-------------|
+| `info` | Informacje o obrazie | - (zwraca szerokość, wysokość, format, rozmiar, kanały, hasAlpha, DPI, EXIF) |
+| `compare` | Porównanie obrazów | `mode` (side-by-side/overlay/diff), `diffThreshold` - drugi plik jest celem porównania |
+| `find-duplicates` | Wyszukiwanie duplikatów | `threshold` (odległość skrótu percepcyjnego, domyślnie 8) - wieloplikowe |
+| `color-palette` | Paleta kolorów | `count` (liczba dominujących kolorów), `format` (hex/rgb) |
+| `qr-generate` | Generator kodów QR | `data`, `size`, `margin`, `colorDark`, `colorLight`, `errorCorrectionLevel`, `dotStyle`, `cornerStyle`, `logo` (opcjonalny plik) |
+| `barcode-read` | Czytnik kodów kreskowych | - (automatyczne wykrywanie QR, EAN, Code128, DataMatrix itd.) |
+| `image-to-base64` | Obraz do Base64 | `format` (data-uri/plain), `mimeType` |
+| `html-to-image` | HTML do obrazu | `url`, `format` (png/jpg/webp), `quality`, `fullPage`, `devicePreset` (desktop/tablet/mobile/custom), `viewportWidth`, `viewportHeight` |
+| `histogram` | Histogram | `scale` (linear/log) - zwraca wykres histogramu RGB + statystyki dla poszczególnych kanałów |
+| `lqip-placeholder` | Symbol zastępczy LQIP | `width` (4-64), `blur`, `strategy` (blur/pixelate/solid), `format` (webp/png/jpeg), `quality` |
+| `barcode-generate` | Generator kodów kreskowych | `text`, `type` (code128/ean13/upca/code39/itf14/datamatrix), `scale` (1-8), `includeText` (bool). Treść JSON, bez przesyłania pliku. |
+
+### Układ i kompozycja {#layout-composition}
+
+| ID narzędzia | Nazwa | Kluczowe ustawienia |
+|---------|------|-------------|
+| `collage` | Kolaż / Siatka | `template` (25+ układów), `gap`, `backgroundColor`, `borderRadius` - wieloplikowe |
+| `stitch` | Zszywanie / Łączenie | `direction` (horizontal/vertical/grid), `gap`, `backgroundColor`, `alignment` - wieloplikowe |
+| `split` | Dzielenie obrazu | `mode` (grid/rows/cols), `rows`, `cols`, `tileWidth`, `tileHeight` |
+| `border` | Obramowanie i ramka | `width`, `color`, `style` (solid/gradient/pattern), `borderRadius`, `padding`, `shadow` |
+| `beautify` | Upiększanie zrzutu ekranu | `backgroundType` (solid/linear-gradient/radial-gradient/image/transparent), `gradientStops`, `padding`, `borderRadius`, `shadowPreset`, `frame` (none/macos-light/macos-dark/windows-light/windows-dark/browser-light/browser-dark/iphone/macbook/ipad/...), `socialPreset` (none/twitter/linkedin/instagram-square/instagram-story/facebook/producthunt), `watermarkText`, `outputFormat` |
+| `circle-crop` | Kadrowanie okrągłe | `zoom` (1-5), `offsetX`, `offsetY`, `borderWidth`, `borderColor`, `background` (transparent/hex), `outputSize` |
+| `image-pad` | Dopełnianie obrazu | `target` (16:9/9:16/1:1/4:3/3:4/custom), `ratioW`, `ratioH`, `background` (color/transparent/blur), `color` (hex), `padding` (0-50%) |
+| `sprite-sheet` | Arkusz duszków | `columns` (1-16), `padding`, `background` (hex), `format` (png/webp/jpeg), `quality` - wieloplikowe (2-64 obrazy) |
+
+### Format i konwersja {#format-conversion}
+
+| ID narzędzia | Nazwa | Kluczowe ustawienia |
+|---------|------|-------------|
+| `svg-to-raster` | SVG do rastra | `format` (png/jpeg/webp/avif/tiff/gif/heif), `width`, `height`, `scale`, `dpi`, `background` |
+| `vectorize` | Obraz do SVG | `colorMode` (bw/color), `threshold`, `colorPrecision`, `filterSpeckle`, `pathMode` (none/polygon/spline) |
+| `gif-tools` | Narzędzia GIF | `action` (resize/optimize/reverse/speed/extract-frames/rotate/add-text), parametry specyficzne dla akcji |
+| `gif-webp` | Konwerter GIF/WebP | `quality` (1-100), `lossless` (bool), `resizePercent` (10-100) |
+
+### Narzędzia wideo {#video-tools}
+
+| ID narzędzia | Nazwa | Kluczowe ustawienia |
+|---------|------|-------------|
+| `convert-video` | Konwersja wideo | `format` (mp4/mov/webm/avi/mkv), `quality` (high/balanced/small) |
+| `compress-video` | Kompresja wideo | `quality` (light/balanced/strong), `resolution` (original/1080p/720p/480p) |
+| `trim-video` | Przycinanie wideo | `startS`, `endS`, `precise` (bool, cięcie z dokładnością do klatki) |
+| `mute-video` | Wyciszanie wideo | - |
+| `video-to-gif` | Wideo do GIF | `fps` (1-30), `width`, `startS`, `durationS` (maks. 60 s) |
+| `resize-video` | Zmiana rozmiaru wideo | `width`, `height`, `preset` (custom/2160p/1440p/1080p/720p/480p/360p) |
+| `crop-video` | Kadrowanie wideo | `width`, `height`, `x`, `y` |
+| `rotate-video` | Obrót wideo | `transform` (cw90/ccw90/180/hflip/vflip) |
+| `change-fps` | Zmiana FPS | `fps` (1-120) |
+| `video-color` | Kolor wideo | `brightness`, `contrast`, `saturation`, `gamma` |
+| `video-speed` | Prędkość wideo | `factor` (0.25-4), `keepPitch` (bool) |
+| `reverse-video` | Odwracanie wideo | - (maks. 5 minut) |
+| `video-loudnorm` | Normalizacja dźwięku | - (EBU R128) |
+| `aspect-pad` | Dopełnianie proporcji | `target` (16:9/9:16/1:1/4:3/3:4), `color` (hex) |
+| `blur-pad` | Dopełnianie rozmyciem | `target` (16:9/9:16/1:1/4:3/3:4), `blur` (2-50) |
+| `watermark-video` | Znak wodny na wideo | `text`, `position`, `fontSize`, `opacity`, `color` |
+| `stabilize-video` | Stabilizacja wideo | `smoothing` (5-60, w klatkach) |
+| `gif-to-video` | GIF do wideo | `format` (mp4/webm/mov) |
+| `video-to-webp` | Wideo do WebP | `fps`, `width`, `quality`, `loop` (bool) |
+| `video-to-frames` | Wideo do klatek | `mode` (all/nth/timestamps), `n`, `timestamps`, `format` (png/jpg) |
+| `merge-videos` | Łączenie wideo | - (wieloplikowe, znormalizowane do rozdzielczości pierwszego wideo) |
+| `replace-audio` | Zamiana dźwięku | - (plik wideo + audio, dwa pliki) |
+| `burn-subtitles` | Wypalanie napisów | `fontSize` (8-72) - plik wideo + napisy |
+| `embed-subtitles` | Osadzanie napisów | `language` (kod ISO 639-2/B) - plik wideo + napisy |
+| `extract-subtitles` | Wyodrębnianie napisów | - (na wyjściu SRT) |
+| `images-to-video` | Obrazy do wideo | `secondsPerImage` (0.5-10), `resolution` (1080p/720p/square), `fps` - wieloplikowe |
+| `video-metadata` | Czyszczenie metadanych wideo | - |
+| `auto-subtitles` | Automatyczne napisy (AI) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `format` (srt/vtt) |
+| `extract-audio` | Wyodrębnianie dźwięku | `format` (mp3/wav/m4a/ogg) |
+
+### Narzędzia audio {#audio-tools}
+
+| ID narzędzia | Nazwa | Kluczowe ustawienia |
+|---------|------|-------------|
+| `convert-audio` | Konwersja dźwięku | `format` (mp3/wav/ogg/flac/m4a), `bitrateKbps` (32-320) |
+| `trim-audio` | Przycinanie dźwięku | `startS`, `endS` |
+| `volume-adjust` | Regulacja głośności | `gainDb` (-30 do 30) |
+| `normalize-audio` | Normalizacja dźwięku | - (EBU R128, -16 LUFS) |
+| `fade-audio` | Wyciszanie/wzmacnianie dźwięku | `fadeInS` (0-30), `fadeOutS` (0-30) |
+| `reverse-audio` | Odwracanie dźwięku | - |
+| `audio-speed` | Prędkość dźwięku | `factor` (0.25-4) |
+| `pitch-shift` | Przesunięcie tonacji | `semitones` (-12 do 12) |
+| `audio-channels` | Kanały dźwięku | `mode` (stereo-to-mono/mono-to-stereo/swap) |
+| `silence-removal` | Usuwanie ciszy | `thresholdDb` (-80 do -20), `minSilenceS` (0.1-5) |
+| `noise-reduction` | Redukcja szumów | `strength` (light/medium/strong) |
+| `merge-audio` | Łączenie dźwięku | `format` (mp3/wav/flac/m4a) - wieloplikowe |
+| `split-audio` | Dzielenie dźwięku | `mode` (time/parts/silence), `segmentS`, `parts`, `thresholdDb`, `minSilenceS` |
+| `ringtone-maker` | Twórca dzwonków | `startS`, `durationS` (1-30) |
+| `waveform-image` | Obraz przebiegu | `width`, `height`, `color` (hex) |
+| `audio-metadata` | Metadane dźwięku | `strip` (bool), `title`, `artist`, `album` |
+| `transcribe-audio` | Transkrypcja dźwięku (AI) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `outputFormat` (txt/srt/vtt) |
+
+### Narzędzia do dokumentów {#document-tools}
+
+| ID narzędzia | Nazwa | Kluczowe ustawienia |
+|---------|------|-------------|
+| `merge-pdf` | Łączenie plików PDF | - (wieloplikowe, do 20 plików PDF) |
+| `split-pdf` | Dzielenie PDF | `mode` (range/every), `range`, `everyN` (1-500) |
+| `compress-pdf` | Kompresja PDF | `mode` (quality/targetSize), `quality` (1-100), `targetSizeKb` |
+| `rotate-pdf` | Obrót PDF | `angle` (90/180/270), `range` (zakres stron) |
+| `extract-pages` | Wyodrębnianie stron | `range` (składnia qpdf, np. "1-5,8,10-z") |
+| `remove-pages` | Usuwanie stron | `pages` (zakres qpdf do usunięcia) |
+| `organize-pdf` | Organizacja PDF | `order` (kolejność stron qpdf, np. "3,1,2,5-z") |
+| `protect-pdf` | Ochrona PDF | `userPassword`, `ownerPassword` (AES-256) |
+| `unlock-pdf` | Odblokowanie PDF | `password` |
+| `repair-pdf` | Naprawa PDF | - |
+| `linearize-pdf` | Optymalizacja PDF pod kątem internetu | - (linearyzacja dla szybkiego przeglądania w sieci) |
+| `grayscale-pdf` | PDF w skali szarości | - |
+| `pdfa-convert` | Konwersja do PDF/A | - (archiwalny PDF/A-2) |
+| `crop-pdf` | Kadrowanie PDF | `margin` (0-2000 punktów) |
+| `nup-pdf` | N-up PDF | `perSheet` (2/3/4/8/9/12/16) |
+| `booklet-pdf` | Broszura PDF | `perSheet` (2/4/6/8) |
+| `watermark-pdf` | Znak wodny PDF | `text`, `position`, `fontSize`, `opacity`, `rotation` |
+| `pdf-page-numbers` | Numery stron PDF | `position` (bl/bc/br/tl/tc/tr), `fontSize` |
+| `flatten-pdf` | Spłaszczanie PDF | - (utrwala formularze i adnotacje) |
+| `redact-pdf` | Redakcja PDF | `terms` (string[]), `caseSensitive` (bool) |
+| `sign-pdf` | Podpisywanie PDF | Niestandardowa trasa multipart z plikiem PDF `file`, plikami podpisu `sig0`, `sig1` oraz tablicą JSON `placements` |
+| `pdf-to-text` | PDF do tekstu | - |
+| `pdf-to-word` | PDF do Word | - |
+| `pdf-metadata` | Metadane PDF | `title`, `author`, `subject`, `keywords` |
+| `convert-document` | Konwersja dokumentu | `format` (docx/odt/rtf/txt) |
+| `convert-presentation` | Konwersja prezentacji | `format` (pptx/odp) |
+| `convert-spreadsheet` | Konwersja arkusza kalkulacyjnego | `format` (xlsx/ods/csv) |
+| `excel-to-pdf` | Excel do PDF | - |
+| `word-to-pdf` | Word do PDF | - |
+| `powerpoint-to-pdf` | PowerPoint do PDF | - |
+| `html-to-pdf` | HTML do PDF | - (zdalne zasoby wyłączone) |
+| `markdown-to-docx` | Markdown do Word | - |
+| `markdown-to-html` | Markdown do HTML | - |
+| `markdown-to-pdf` | Markdown do PDF | - (zdalne zasoby wyłączone) |
+| `epub-convert` | Konwersja EPUB | `format` (pdf/docx/html/md) |
+| `to-epub` | Konwersja do EPUB | - (akceptuje .docx, .md, .html, .txt) |
+| `ocr-pdf` | OCR PDF (AI) | `quality` (fast/balanced/best), `language` (auto/en/de/fr/es/zh/ja/ko), `pages` |
+| `pdf-to-image` | PDF do obrazu | `pages` (all/range), `format`, `dpi`, `quality` |
+| `pdf-to-jpg` | PDF do JPG | `pages`, `dpi`, `quality`, `colorMode` |
+| `pdf-to-png` | PDF do PNG | `pages`, `dpi`, `quality`, `colorMode` |
+| `pdf-to-tiff` | PDF do TIFF | `pages`, `dpi`, `quality`, `colorMode` |
+
+### Narzędzia do plików {#file-tools}
+
+| ID narzędzia | Nazwa | Kluczowe ustawienia |
+|---------|------|-------------|
+| `chart-maker` | Twórca wykresów | `kind` (bar/line/pie), `title`, `width`, `height` |
+| `csv-excel` | CSV do Excel | `sheet` (numer arkusza dla wejścia XLSX) - dwukierunkowe |
+| `csv-json` | CSV do JSON | `pretty` (bool) - dwukierunkowe |
+| `json-xml` | JSON do XML | `pretty` (bool) - dwukierunkowe |
+| `split-csv` | Dzielenie CSV | `rowsPerFile` (1-1000000), `keepHeader` (bool) |
+| `merge-csvs` | Łączenie plików CSV | - (wieloplikowe, pasujące kolumny) |
+| `yaml-json` | YAML / JSON | - (dwukierunkowe) |
+| `xml-to-csv` | XML do CSV | - (automatyczne wyszukiwanie powtarzających się elementów) |
+| `excel-to-csv` | Excel do CSV | dedykowane ustawienie wstępne konwersji oparte na `convert-spreadsheet` |
+| `create-zip` | Utwórz ZIP | - (wieloplikowe, 2-50 plików) |
+| `extract-zip` | Wypakuj ZIP | - (ochrona przed bombą) |
+
+### HTML do obrazu {#html-to-image}
+
+Przechwyć stronę internetową jako obraz. W przeciwieństwie do innych narzędzi ten punkt końcowy przyjmuje `application/json` zamiast danych formularza multipart (bez potrzeby przesyłania pliku).
+
+**Punkt końcowy:** `POST /api/v1/tools/image/html-to-image`
+
+**Content-Type:** `application/json`
+
+| Parametr | Typ | Domyślnie | Opis |
+|-----------|------|---------|-------------|
+| `url` | string | (wymagane) | URL do przechwycenia (tylko http/https) |
+| `format` | string | `"png"` | Format wyjściowy: `jpg`, `png`, `webp` |
+| `quality` | number | `90` | Jakość 1-100 (tylko JPG/WebP) |
+| `fullPage` | boolean | `false` | Przechwyć całą przewijaną stronę |
+| `devicePreset` | string | `"desktop"` | `desktop`, `tablet`, `mobile`, `custom` |
+| `viewportWidth` | number | `1280` | Niestandardowa szerokość okna widoku 320-3840 |
+| `viewportHeight` | number | `720` | Niestandardowa wysokość okna widoku 320-2160 |
+
+**Przykład:**
+
+```bash
+curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://snapotter.com", "format": "png", "devicePreset": "desktop"}'
+```
+
+**Odpowiedź:**
+
+```json
+{
+  "jobId": "uuid",
+  "downloadUrl": "/api/v1/download/{jobId}/screenshot.png",
+  "originalSize": 0,
+  "processedSize": 54321
+}
+```
+
+### Podtrasy narzędzi {#tool-sub-routes}
+
+Niektóre narzędzia udostępniają dodatkowe punkty końcowe poza standardowym `POST /api/v1/tools/<section>/<toolId>`:
+
+| Metoda | Ścieżka | Opis |
+|--------|------|-------------|
+| `GET` | `/api/v1/tools/popular` | Zwraca popularne identyfikatory narzędzi, wracając do wyselekcjonowanej listy domyślnej, gdy dane o użyciu są skąpe |
+| `POST` | `/api/v1/tools/image/remove-background/effects` | Zastosuj efekty tła (color/gradient/blur/shadow) bez ponownego uruchamiania AI. Używa maski z pamięci podręcznej z początkowego usunięcia. |
+| `POST` | `/api/v1/tools/image/edit-metadata/inspect` | Odczytaj istniejące metadane EXIF/IPTC/XMP z obrazu |
+| `POST` | `/api/v1/tools/image/strip-metadata/inspect` | Sprawdź pola metadanych przed usunięciem |
+| `POST` | `/api/v1/tools/image/passport-photo/analyze` | Faza 1: Wykrywanie twarzy AI + usuwanie tła. Zwraca punkty charakterystyczne twarzy i dane z pamięci podręcznej. |
+| `POST` | `/api/v1/tools/image/passport-photo/generate` | Faza 2: Kadrowanie, zmiana rozmiaru i kafelkowanie przy użyciu analizy z pamięci podręcznej. Bez ponownego uruchamiania AI. |
+| `POST` | `/api/v1/tools/image/gif-tools/info` | Pobierz metadane GIF (liczba klatek, wymiary, czas trwania) |
+| `POST` | `/api/v1/tools/pdf/pdf-to-image/info` | Pobierz metadane PDF (liczba stron, wymiary) |
+| `POST` | `/api/v1/tools/pdf/pdf-to-image/preview` | Wygeneruj podgląd konkretnej strony PDF |
+| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/info` | Pobierz metadane PDF dla dedykowanego ustawienia wstępnego JPG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/preview` | Wygeneruj podgląd strony PDF z ustawieniem wstępnym JPG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-png/info` | Pobierz metadane PDF dla dedykowanego ustawienia wstępnego PNG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-png/preview` | Wygeneruj podgląd strony PDF z ustawieniem wstępnym PNG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/info` | Pobierz metadane PDF dla dedykowanego ustawienia wstępnego TIFF |
+| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/preview` | Wygeneruj podgląd strony PDF z ustawieniem wstępnym TIFF |
+| `POST` | `/api/v1/tools/image/svg-to-raster/batch` | Konwertuj wsadowo wiele plików SVG do rastra |
+| `POST` | `/api/v1/tools/image/image-enhancement/analyze` | Przeanalizuj jakość obrazu i zwróć rekomendacje poprawy |
+| `POST` | `/api/v1/tools/image/optimize-for-web/preview` | Lekki podgląd do dostrajania parametrów na żywo. Zwraca zoptymalizowany obraz z nagłówkami rozmiaru. |
+
+## Przetwarzanie wsadowe {#batch-processing}
+
+Zastosuj ogólne narzędzie obsługujące tryb wsadowy do wielu plików jednocześnie. Zwraca archiwum ZIP. Niestandardowe trasy wieloplikowe lub wieloetapowe, takie jak podpisywanie PDF, OCR PDF oraz trasy ustawień wstępnych PDF-do-obrazu, używają własnego kontraktu punktu końcowego zamiast ogólnej trasy `/batch`.
+
+```bash
+curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \
+  -H "Authorization: Bearer <token>" \
+  -F "files=@a.jpg" \
+  -F "files=@b.jpg" \
+  -F "files=@c.jpg" \
+  -F 'settings={"quality":80}'
+```
+
+Współbieżnością steruje `CONCURRENT_JOBS` (domyślnie: automatycznie wykrywana na podstawie rdzeni CPU). `MAX_BATCH_SIZE` ogranicza liczbę plików w partii (domyślnie: 100; ustaw 0 dla braku limitu).
+
+## Potoki {#pipelines}
+
+### Wykonaj potok {#execute-a-pipeline}
+
+```bash
+# Single file
+curl -X POST http://localhost:1349/api/v1/pipeline/execute \
+  -H "Authorization: Bearer <token>" \
+  -F "file=@input.jpg" \
+  -F 'pipeline={"steps":[
+    {"toolId":"resize","settings":{"width":1200}},
+    {"toolId":"compress","settings":{"quality":80}},
+    {"toolId":"watermark-text","settings":{"text":"© 2025"}}
+  ]}'
+
+# Batch (multiple files → ZIP)
+curl -X POST http://localhost:1349/api/v1/pipeline/batch \
+  -H "Authorization: Bearer <token>" \
+  -F "files=@a.jpg" \
+  -F "files=@b.jpg" \
+  -F 'pipeline={"steps":[{"toolId":"resize","settings":{"width":800}}]}'
+```
+
+Wyjście każdego kroku jest wejściem następnego kroku. Potoki domyślnie dopuszczają 20 kroków, co jest konfigurowalne za pomocą `MAX_PIPELINE_STEPS`. Ustaw `MAX_PIPELINE_STEPS=0`, aby usunąć limit.
+
+### Zapisywanie potoków i zarządzanie nimi {#save-and-manage-pipelines}
+
+| Metoda | Ścieżka | Opis |
+|--------|------|-------------|
+| `POST` | `/api/v1/pipeline/save` | Zapisz nazwany potok (`name`, `description`, `steps[]`) |
+| `GET` | `/api/v1/pipeline/list` | Lista zapisanych potoków (administratorzy widzą wszystkie; użytkownicy widzą własne) |
+| `DELETE` | `/api/v1/pipeline/:id` | Usuń (właściciel lub administrator) |
+| `GET` | `/api/v1/pipeline/tools` | Lista identyfikatorów narzędzi ważnych dla kroków potoku |
+
+## Śledzenie postępu {#progress-tracking}
+
+Długotrwałe zadania, narzędzia w kolejce, zadania wsadowe i potoki emitują postęp w czasie rzeczywistym za pomocą Server-Sent Events. Strumień postępu jest publiczny i identyfikowany przez identyfikator zadania, więc klienci nie muszą wysyłać nagłówka Authorization, aby go odczytać.
+
+```bash
+# Connect to the SSE stream (jobId is in the JSON response body from the tool endpoint)
+curl -N http://localhost:1349/api/v1/jobs/<jobId>/progress
+```
+
+Format zdarzenia:
+```
+data: {"jobId":"...","type":"single","phase":"processing","stage":"Upscaling","percent":42}
+data: {"jobId":"...","type":"single","phase":"complete","percent":100,"result":{"downloadUrl":"/api/v1/download/..."}}
+data: {"jobId":"...","type":"batch","status":"processing","completedFiles":2,"totalFiles":5,"failedFiles":0,"errors":[]}
+```
+
+Możesz zażądać anulowania zadania w kolejce lub uruchomionego za pomocą `POST /api/v1/jobs/:jobId/cancel`. Odpowiedzią jest `{"canceled":true|false}`.
+
+## Biblioteka plików {#file-library}
+
+Trwałe przechowywanie plików z historią wersji.
+
+| Metoda | Ścieżka | Opis |
+|--------|------|-------------|
+| `POST` | `/api/v1/upload` | Prześlij pliki do obszaru roboczego (tymczasowe przetwarzanie) |
+| `POST` | `/api/v1/files/upload` | Prześlij pliki do trwałej biblioteki plików |
+| `POST` | `/api/v1/files/save-result` | Zapisz wynik przetwarzania narzędzia jako nową wersję pliku |
+| `GET` | `/api/v1/files` | Lista zapisanych plików (stronicowana, z wyszukiwaniem) |
+| `GET` | `/api/v1/files/:id` | Pobierz metadane pliku + łańcuch wersji |
+| `GET` | `/api/v1/files/:id/download` | Pobierz plik |
+| `GET` | `/api/v1/files/:id/thumbnail` | Pobierz miniaturę JPEG 300px |
+| `DELETE` | `/api/v1/files` | Zbiorczo usuń pliki i ich łańcuchy wersji (treść: `{ ids: [...] }`) |
+| `POST` | `/api/v1/fetch-urls` | Pobierz zdalne adresy URL do obszaru roboczego dla importów opartych na URL |
+| `POST` | `/api/v1/preview` | Wygeneruj podgląd WebP zgodny z przeglądarką (dla formatów HEIC/HEIF/RAW) |
+| `GET` | `/api/v1/files/:id/preview` | Przesyłaj strumieniowo podgląd zgodny z przeglądarką z pamięci podręcznej lub wygenerowany dla zapisanego pliku PDF, dokumentu biurowego, wideo lub audio |
+| `POST` | `/api/v1/preview/generate` | Wygeneruj na żądanie podgląd MP4 lub MP3 dla przesłanego pliku multimedialnego bez uprzedniego zapisywania go |
+| `GET` | `/api/v1/download/:jobId/:filename` | Pobierz przetworzony plik z obszaru roboczego |
+
+Aby automatycznie zapisać wynik narzędzia w bibliotece, dołącz `fileId` jako pole formularza multipart odwołujące się do istniejącego pliku w bibliotece. Przetworzony wynik zostanie zapisany jako nowa wersja.
+
+## Zarządzanie kluczami API {#api-key-management}
+
+| Metoda | Ścieżka | Dostęp | Opis |
+|--------|------|--------|-------------|
+| `POST` | `/api/v1/api-keys` | Uwierzytelniony | Wygeneruj nowy klucz - pokazywany raz |
+| `GET` | `/api/v1/api-keys` | Uwierzytelniony | Lista kluczy (nazwa, id, lastUsedAt - bez surowego klucza) |
+| `DELETE` | `/api/v1/api-keys/:id` | Uwierzytelniony | Usuń klucz |
+
+## Zespoły {#teams}
+
+| Metoda | Ścieżka | Dostęp | Opis |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/teams` | Administrator (`teams:manage`) | Lista zespołów |
+| `POST` | `/api/v1/teams` | Administrator (`teams:manage`) | Utwórz zespół |
+| `PUT` | `/api/v1/teams/:id` | Administrator (`teams:manage`) | Zmień nazwę zespołu |
+| `DELETE` | `/api/v1/teams/:id` | Administrator (`teams:manage`) | Usuń zespół (nie można usunąć domyślnego zespołu ani zespołów z członkami) |
+
+## Ustawienia {#settings}
+
+Konfiguracja klucz-wartość w czasie działania (odczyt przez każdego uwierzytelnionego użytkownika, zapis tylko przez administratora).
+
+| Metoda | Ścieżka | Opis |
+|--------|------|-------------|
+| `GET` | `/api/v1/settings` | Pobierz wszystkie ustawienia |
+| `PUT` | `/api/v1/settings` | Zbiorczo zaktualizuj ustawienia (treść JSON z parami klucz-wartość) |
+| `GET` | `/api/v1/settings/:key` | Pobierz konkretne ustawienie według klucza |
+
+Znane klucze: `disabledTools` (tablica JSON identyfikatorów narzędzi), `enableExperimentalTools` (ciąg bool), `loginAttemptLimit` (liczba).
+
+## Preferencje {#preferences}
+
+Preferencje poszczególnych użytkowników są oddzielone od ustawień instancji. Każdy uwierzytelniony użytkownik może odczytać i zaktualizować własną mapę preferencji.
+
+| Metoda | Ścieżka | Opis |
+|--------|------|-------------|
+| `GET` | `/api/v1/preferences` | Pobierz preferencje bieżącego użytkownika jako `{ "preferences": { ... } }` |
+| `PUT` | `/api/v1/preferences` | Zapisz lub zaktualizuj jeden lub więcej kluczy preferencji dla bieżącego użytkownika |
+
+## Role {#roles}
+
+Zarządzanie niestandardowymi rolami z granularnymi uprawnieniami.
+
+| Metoda | Ścieżka | Dostęp | Opis |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/roles` | Administrator (`audit:read`) | Lista wszystkich ról z liczbą użytkowników |
+| `POST` | `/api/v1/roles` | Administrator (`security:manage`) | Utwórz niestandardową rolę (`name`, `description`, `permissions`) |
+| `PUT` | `/api/v1/roles/:id` | Administrator (`security:manage`) | Zaktualizuj niestandardową rolę (nie można modyfikować wbudowanych ról) |
+| `DELETE` | `/api/v1/roles/:id` | Administrator (`security:manage`) | Usuń niestandardową rolę (nie można usuwać wbudowanych ról; dotknięci użytkownicy wracają do roli `user`) |
+
+Dostępne uprawnienia (17): `tools:use`, `files:own`, `files:all`, `apikeys:own`, `apikeys:all`, `pipelines:own`, `pipelines:all`, `settings:read`, `settings:write`, `users:manage`, `teams:manage`, `features:manage`, `system:health`, `audit:read`, `compliance:manage`, `webhooks:manage`, `security:manage`.
+
+## Dziennik audytu {#audit-log}
+
+Punkt końcowy tylko dla administratora do przeglądania działań istotnych z punktu widzenia bezpieczeństwa.
+
+| Metoda | Ścieżka | Dostęp | Opis |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/audit-log` | Administrator (`audit:read`) | Stronicowany dziennik audytu z opcjonalnymi filtrami |
+
+Parametry zapytania:
+
+| Parametr | Opis |
+|-----------|-------------|
+| `page` | Numer strony (domyślnie: 1) |
+| `limit` | Wpisy na stronę (domyślnie: 50, maks.: 100) |
+| `action` | Filtruj według typu akcji (np. `ROLE_CREATED`, `ROLE_DELETED`) |
+| `ip` | Filtruj według źródłowego adresu IP |
+| `from` | Filtruj wpisy po tej dacie ISO 8601 |
+| `to` | Filtruj wpisy przed tą datą ISO 8601 |
+
+## Analityka {#analytics}
+
+| Metoda | Ścieżka | Dostęp | Opis |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/config/analytics` | Publiczny | Pobierz efektywną konfigurację analityki (klucz PostHog, DSN Sentry, częstotliwość próbkowania). Klucze, DSN i identyfikator instancji są puste, gdy analityka jest wyłączona, zarówno z powodu ustawienia w czasie kompilacji, jak i ustawienia instancji `analyticsEnabled`. |
+| `POST` | `/api/v1/feedback` | Uwierzytelniony | Prześlij wyraźną opinię użytkownika do skonfigurowanego projektu PostHog jako `feedback_submitted`. Trasa respektuje bramkę analityki, ogranicza liczbę zgłoszeń, usuwa pola kontaktowe, chyba że `contactOk` ma wartość true, i nigdy nie akceptuje zawartości plików, nazw plików, ścieżek przesyłania ani surowego, prywatnego tekstu błędu. Gdy analityka jest wyłączona, zwraca `{ "ok": true, "accepted": false }`. |
+| `PUT` | `/api/v1/settings` | Administrator (`settings:write`) | Ustaw rezygnację obejmującą całą instancję. Wyślij treść JSON `{ "analyticsEnabled": "false" }`, aby wyłączyć analitykę dla wszystkich, lub `"true"`, aby ją ponownie włączyć. |
+
+## Funkcje / Pakiety AI {#features-ai-bundles}
+
+Zarządzaj pakietami funkcji AI (instaluj/odinstalowuj pakiety modeli AI w środowisku Docker). Preferuj punkt końcowy instalacji na poziomie narzędzia podczas włączania narzędzia z niestandardowej automatyzacji: niektóre narzędzia AI potrzebują więcej niż jednego współdzielonego pakietu, a ten punkt końcowy pomija już zainstalowane pakiety, kolejkując tylko brakujące.
+
+| Metoda | Ścieżka | Dostęp | Opis |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/features` | Uwierzytelniony | Lista wszystkich pakietów funkcji i ich status instalacji |
+| `POST` | `/api/v1/admin/features/:bundleId/install` | Administrator (`features:manage`) | Zainstaluj pakiet funkcji (asynchronicznie, zwraca `jobId` do śledzenia postępu) |
+| `POST` | `/api/v1/admin/tools/:toolId/features/install` | Administrator (`features:manage`) | Zainstaluj każdy pakiet wymagany przez narzędzie; zwraca status queued/skipped dla poszczególnych pakietów |
+| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Administrator (`features:manage`) | Odinstaluj pakiet funkcji i usuń pliki modeli |
+| `GET` | `/api/v1/admin/features/disk-usage` | Administrator (`features:manage`) | Pobierz całkowite zużycie dysku przez modele AI |
+| `POST` | `/api/v1/admin/features/import` | Administrator (`features:manage`) | Zaimportuj archiwum pakietu AI w trybie offline |
+
+## Operacje administracyjne {#admin-operations}
+
+Operacyjne punkty końcowe do obserwowalności, wsparcia, raportowania użycia i statusu kopii zapasowej.
+
+| Metoda | Ścieżka | Dostęp | Opis |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/admin/log-level` | Administrator (`settings:write`) | Odczytaj bieżący poziom logowania w czasie działania |
+| `POST` | `/api/v1/admin/log-level` | Administrator (`settings:write`) | Zmień poziom logowania w czasie działania (`fatal`, `error`, `warn`, `info`, `debug`, `trace` lub `silent`) |
+| `GET` | `/api/v1/metrics` | Administrator (`system:health`) | Metryki Prometheus w formacie tekstowym |
+| `GET` | `/api/v1/admin/support-bundle` | Administrator (`system:health`) | Pobierz zredagowany pakiet diagnostyczny wsparcia ZIP |
+| `GET` | `/api/v1/admin/usage` | Administrator (`audit:read`) | Dane pulpitu użycia, z opcjonalnym parametrem zapytania `days` |
+| `GET` | `/api/v1/admin/backup-status` | Administrator (`system:health`) | Odczytaj metadane ostatniej kopii zapasowej i status aktualności |
+| `POST` | `/api/v1/admin/backup-status` | Administrator (`system:health`) | Zarejestruj ukończoną kopię zapasową (`type`, opcjonalnie `sizeBytes`, opcjonalnie `notes`) |
+
+## API Enterprise {#enterprise-apis}
+
+Te trasy są bramkowane licencją przez powiązaną z nimi funkcję enterprise. Nadal wymagają wymienionego uprawnienia SnapOtter.
+
+| Metoda | Ścieżka | Dostęp | Opis |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/enterprise/audit/export` | Administrator (`audit:read`) | Eksportuj wpisy audytu jako JSON lub CSV z filtrami |
+| `GET` | `/api/v1/enterprise/config/export` | Administrator (`system:health`) | Eksportuj zredagowaną konfigurację instancji, niestandardowe role i zespoły |
+| `POST` | `/api/v1/enterprise/config/import` | Administrator (`system:health`) | Zaimportuj konfigurację, z opcjonalnym przebiegiem próbnym |
+| `GET` | `/api/v1/enterprise/ip-allowlist` | Administrator (`security:manage`) | Odczytaj skonfigurowaną listę dozwolonych CIDR |
+| `PUT` | `/api/v1/enterprise/ip-allowlist` | Administrator (`security:manage`) | Zaktualizuj listę dozwolonych CIDR z ochroną przed zablokowaniem samego siebie |
+| `GET` | `/api/v1/enterprise/legal-hold` | Administrator (`compliance:manage`) | Lista blokad prawnych użytkowników i zespołów |
+| `PUT` | `/api/v1/enterprise/legal-hold` | Administrator (`compliance:manage`) | Zastosuj lub zwolnij blokadę prawną dla użytkownika lub zespołu |
+| `POST` | `/api/v1/enterprise/scim/token` | Administrator (`users:manage`) | Wygeneruj token bearer SCIM, zwracany raz |
+| `DELETE` | `/api/v1/enterprise/scim/token` | Administrator (`users:manage`) | Unieważnij bieżący token bearer SCIM |
+| `GET` | `/api/v1/enterprise/siem/config` | Administrator (`webhooks:manage`) | Odczytaj konfigurację przekazywania SIEM |
+| `PUT` | `/api/v1/enterprise/siem/config` | Administrator (`webhooks:manage`) | Zaktualizuj konfigurację przekazywania SIEM |
+| `GET` | `/api/v1/enterprise/webhooks` | Administrator (`webhooks:manage`) | Lista miejsc docelowych webhooków |
+| `POST` | `/api/v1/enterprise/webhooks` | Administrator (`webhooks:manage`) | Utwórz miejsce docelowe webhooka |
+| `PUT` | `/api/v1/enterprise/webhooks/:index` | Administrator (`webhooks:manage`) | Zaktualizuj miejsce docelowe webhooka |
+| `DELETE` | `/api/v1/enterprise/webhooks/:index` | Administrator (`webhooks:manage`) | Usuń miejsce docelowe webhooka |
+| `POST` | `/api/v1/enterprise/webhooks/:index/test` | Administrator (`webhooks:manage`) | Wyślij testowy ładunek webhooka |
+| `POST` | `/api/v1/enterprise/users/:id/export` | Administrator (`compliance:manage`) | Rozpocznij zadanie eksportu użytkownika RODO |
+| `GET` | `/api/v1/enterprise/users/:id/export/:jobId` | Administrator (`compliance:manage`) | Odczytaj status eksportu RODO i adres URL pobierania |
+| `DELETE` | `/api/v1/enterprise/users/:id/purge` | Administrator (`compliance:manage`) | Trwale usuń dane użytkownika po potwierdzeniu |
+| `DELETE` | `/api/v1/enterprise/teams/:id/purge` | Administrator (`compliance:manage`) | Trwale usuń dane zespołu po potwierdzeniu |
+| `GET` | `/api/v1/admin/version` | Administrator (`system:health`) | Odczytaj metadane wersji aplikacji, kompilacji, Node i schematu |
+| `GET` | `/api/v1/admin/migrations/pending` | Administrator (`system:health`) | Porównaj spakowane migracje z zastosowanymi migracjami |
+| `GET` | `/api/v1/admin/upgrade-check` | Administrator (`system:health`) | Uruchom kontrole gotowości do aktualizacji |
+
+### SCIM 2.0 {#scim-2-0}
+
+Punkty końcowe wykrywania SCIM są publiczne. Punkty końcowe użytkowników i grup wymagają tokena bearer SCIM wygenerowanego powyżej.
+
+| Metoda | Ścieżka | Dostęp | Opis |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/scim/v2/ServiceProviderConfig` | Publiczny | Możliwości serwera SCIM |
+| `GET` | `/api/v1/scim/v2/Schemas` | Publiczny | Wykrywanie schematu SCIM |
+| `GET` | `/api/v1/scim/v2/ResourceTypes` | Publiczny | Wykrywanie typu zasobu SCIM |
+| `GET` | `/api/v1/scim/v2/Users` | Token SCIM | Lista użytkowników, z opcjonalnym filtrem SCIM |
+| `POST` | `/api/v1/scim/v2/Users` | Token SCIM | Utwórz użytkownika |
+| `GET` | `/api/v1/scim/v2/Users/:id` | Token SCIM | Pobierz użytkownika |
+| `PUT` | `/api/v1/scim/v2/Users/:id` | Token SCIM | Zastąp użytkownika |
+| `DELETE` | `/api/v1/scim/v2/Users/:id` | Token SCIM | Miękka dezaktywacja użytkownika |
+| `GET` | `/api/v1/scim/v2/Groups` | Token SCIM | Lista zespołów jako grup SCIM |
+| `POST` | `/api/v1/scim/v2/Groups` | Token SCIM | Utwórz zespół |
+| `GET` | `/api/v1/scim/v2/Groups/:id` | Token SCIM | Pobierz zespół |
+| `PUT` | `/api/v1/scim/v2/Groups/:id` | Token SCIM | Zastąp zespół i członkostwo w grupie |
+| `DELETE` | `/api/v1/scim/v2/Groups/:id` | Token SCIM | Usuń zespół |
+
+## Szablony memów {#meme-templates}
+
+Wspierające API dla narzędzia generatora memów.
+
+| Metoda | Ścieżka | Dostęp | Opis |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/meme-templates` | Uwierzytelniony | Lista wszystkich dostępnych szablonów memów z pozycjami pól tekstowych |
+| `GET` | `/api/v1/meme-templates/full/:filename` | Uwierzytelniony | Udostępnij obraz szablonu w pełnym rozmiarze |
+| `GET` | `/api/v1/meme-templates/thumbs/:filename` | Uwierzytelniony | Udostępnij miniaturę szablonu |
+| `GET` | `/api/v1/meme-templates/fonts/:filename` | Uwierzytelniony | Udostępnij plik czcionki używany do renderowania tekstu memu |
+
+## Odpowiedzi z błędami {#error-responses}
+
+Wszystkie błędy zwracają JSON:
+
+```json
+{
+  "error": "Human-readable message",
+  "code": "MACHINE_READABLE_CODE"
+}
+```
+
+| Status | Znaczenie |
+|--------|---------|
+| 400 | Nieprawidłowe żądanie / walidacja nie powiodła się |
+| 401 | Brak uwierzytelnienia |
+| 403 | Niewystarczające uprawnienia |
+| 404 | Nie znaleziono zasobu |
+| 413 | Plik zbyt duży (zobacz `MAX_UPLOAD_SIZE_MB`) |
+| 422 | Przetwarzanie nie powiodło się po walidacji |
+| 429 | Ograniczenie liczby żądań (zobacz `RATE_LIMIT_PER_MIN`) |
+| 501 | Wymagany pakiet funkcji AI nie jest zainstalowany (`FEATURE_NOT_INSTALLED`) |
+| 500 | Wewnętrzny błąd serwera |