description:"Kompletna dokumentacja API REST. Punkty końcowe narzędzi, przetwarzanie wsadowe, potoki, biblioteka plików, uwierzytelnianie, zespoły i operacje administracyjne."
Interaktywna dokumentacja API z przykładami żądań i odpowiedzi jest dostępna pod adresem [http://localhost:1349/api/docs](http://localhost:1349/api/docs).
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.
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 |
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 |
| `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` |
| `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).
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/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. |
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 oraz trasy ustawień wstępnych PDF-do-obrazu, używają własnego kontraktu punktu końcowego zamiast ogólnej trasy `/batch`.
Narzędzie `ocr-pdf` obsługuje tę ogólną trasę `/batch`.
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 \
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[]`) |
| `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)
| `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) |
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.
| `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`) |
| `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.
OCR jest opcjonalnym ulepszeniem, a nie stałą zależnością. Poziom `fast` Tesseract działa bez pakietu; `POST /api/v1/admin/features/ocr/install` instaluje podpisany pakiet RapidOCR dla `balanced` i `best` na Linux amd64 lub arm64. Dokładne środowisko wykonawcze OCR wykorzystuje CPU na hostach wyposażonych wyłącznie w procesor i NVIDIA i wymaga co najmniej 4 GiB efektywnej pamięci (skonfigurowany limit kontenera cgroup, w przeciwnym razie pamięć hosta). SnapOtter zgłasza `requiredMemoryBytes`, `effectiveMemoryBytes` i przyczynę kompatybilności `insufficient-memory` i odrzuca niezgodną instalację przed pobraniem. To wymaganie dotyczące pamięci nie dotyczy `fast`. Pakiet zawiera około 208-234 MiB do pobrania i 409-488 MiB do zainstalowania, w zależności od celu; podpisany indeks wiąże dokładne rozmiary wymuszone podczas instalacji.
| `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 starszy pakiet AI (`file`) lub podpisaną wersję offline OCR (`index` plus `archive`) |
Import OCR z przerwami powietrznymi musi zawierać podpisany plik `ocr-runtime-index.json` wydania i pasujące archiwum platformy. SnapOtter stosuje tę samą sygnaturę Ed25519, hash artefaktów, kompatybilność, ekstrakcję i kontrole testów dymu, które są używane podczas instalacji online:
```bash
curl -X POST http://localhost:1349/api/v1/admin/features/import \
-H "Authorization: Bearer <admin-token>"\
-F "index=@ocr-runtime-index.json"\
-F "archive=@ocr-linux-amd64-cpu-py312.tar.gz"
```
Użyj archiwum `linux-arm64-cpu-py311` na arm64. Podpisany artefakt innego celu jest odrzucany, a nie instalowany.
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`) |
| `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 |
