När MFA är aktiverat för en användare returnerar `POST /api/auth/login``{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` istället för en sessionstoken. Skicka den `mfaToken` plus en TOTP- eller återställningskod till `/api/auth/mfa/complete`.
### Behörigheter {#permissions}
| Behörighet | Admin | Användare |
|-----------|:-----:|:----:|
| Använda verktyg | ✓ | ✓ |
| Egna filer/pipelines/API-nycklar | ✓ | ✓ |
| Se alla användares filer/pipelines/nycklar | ✓ | - |
| Skriva inställningar | ✓ | - |
| Hantera användare och team | ✓ | - |
| Hantera varumärkesprofil | ✓ | - |
## Hälsokontroll {#health-check}
| Metod | Sökväg | Åtkomst | Beskrivning |
|--------|------|--------|-------------|
| `GET` | `/api/v1/health` | Publik | Grundläggande hälsokontroll. Returnerar `{"status":"healthy","version":"..."}` med 200, eller `{"status":"unhealthy"}` med 503 om databasen inte kan nås. |
| `GET` | `/api/v1/readyz` | Publik | Beredskapssond. Kontrollerar PostgreSQL, Redis, diskutrymme och S3 när det är konfigurerat. Returnerar 503 när instansen inte bör ta emot trafik. |
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>` är en av `image`, `video`, `audio`, `pdf` eller `files`.
- Uppladdning är `multipart/form-data`.
-`settings` är en JSON-sträng med verktygsspecifika alternativ.
-`clientJobId` är ett valfritt formulärfält för anropar-tillhandahållen förloppskorrelation.
-`fileId` är ett valfritt formulärfält som refererar till ett befintligt objekt i filbiblioteket. När det finns sparas den bearbetade utdatan som en ny version och svaret inkluderar `savedFileId`.
- **Snabba verktyg** returnerar vanligtvis 200 JSON: `{"jobId":"...","downloadUrl":"/api/v1/download/<jobId>/<filename>","originalSize":1234,"processedSize":567}`. Hämta den bearbetade filen från `downloadUrl`.
- **Alla köade verktyg** kan returnera 202 JSON om de är långvariga eller överskrider det synkrona väntefönstret: `{"jobId":"...","async":true}`. Anslut till SSE för förlopp, ladda sedan ner när det är klart (se [Förloppsspårning](#progress-tracking)).
- **Batch**-rutter returnerar ett ZIP-arkiv som strömmas direkt (med `X-Job-Id`-header) för verktyg som är registrerade i det generiska batchregistret.
Den delade katalogen innehåller 83 dedikerade slutpunkter för konverteringsförinställningar såsom `jpg-to-png`, `mov-to-mp4`, `m4a-to-mp3`, `pdf-to-jpg` och `excel-to-csv`. Förinställningar är förstklassiga verktygsrutter:
`POST /api/v1/tools/<section>/<presetId>`
Varje förinställning låser utdataformatet och delegerar till ett basverktyg såsom `convert`, `convert-video`, `extract-audio`, `convert-audio`, `image-to-pdf`, `pdf-to-image`, `svg-to-raster` eller `convert-spreadsheet`. Se [Konverteringsförinställningar](/sv/tools/conversion-presets) för den fullständiga rutttabellen och valfria inställningar.
### Grundläggande {#essentials}
| Verktygs-ID | Namn | Nyckelinställningar |
|---------|------|-------------|
| `resize` | Ändra storlek | `width`, `height`, `fit` (cover/contain/fill/inside/outside), `percentage`, `withoutEnlargement`, plus 23 förinställningar för sociala medier |
Alla AI-verktyg körs på din hårdvara: CPU som standard, eller NVIDIA CUDA när en stödd NVIDIA-GPU är tillgänglig. Intel/AMD iGPU-acceleration via VA-API, Quick Sync eller OpenCL stöds inte för AI-inferens idag. Ingen internetanslutning krävs.
| Verktygs-ID | Namn | AI-modell | Nyckelinställningar |
| `xml-to-csv` | XML till CSV | - (hittar automatiskt upprepade element) |
| `excel-to-csv` | Excel till CSV | dedikerad konverteringsförinställning som backas upp av `convert-spreadsheet` |
| `create-zip` | Skapa ZIP | - (flerfil, 2-50 filer) |
| `extract-zip` | Extrahera ZIP | - (bombskyddad) |
### HTML till bild {#html-to-image}
Fånga en webbsida som en bild. Till skillnad från andra verktyg accepterar denna slutpunkt `application/json` istället för multipart-formulärdata (ingen filuppladdning behövs).
Vissa verktyg exponerar ytterligare slutpunkter utöver den vanliga `POST /api/v1/tools/<section>/<toolId>`:
| Metod | Sökväg | Beskrivning |
|--------|------|-------------|
| `GET` | `/api/v1/tools/popular` | Returnera populära verktygs-ID:n, med återgång till en kurerad standardlista när användningsdata är gles |
| `POST` | `/api/v1/tools/image/remove-background/effects` | Applicera bakgrundseffekter (color/gradient/blur/shadow) utan att köra AI på nytt. Använder cachad mask från den ursprungliga borttagningen. |
| `POST` | `/api/v1/tools/image/edit-metadata/inspect` | Läs befintlig EXIF/IPTC/XMP-metadata från en bild |
| `POST` | `/api/v1/tools/image/strip-metadata/inspect` | Inspektera metadatafält innan borttagning |
Applicera ett generiskt batchaktiverat verktyg på flera filer samtidigt. Returnerar ett ZIP-arkiv. Anpassade flerfils- eller flerstegsrutter, såsom PDF-signering och PDF-till-bild-förinställningsrutter, använder sitt eget slutpunktskontrakt istället för den generiska `/batch`-rutten.
Verktyget `ocr-pdf` stöder den här generiska `/batch`-rutten.
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}'
```
Samtidighet styrs av `CONCURRENT_JOBS` (standard: automatiskt identifierad från CPU-kärnor). `MAX_BATCH_SIZE` begränsar antalet filer per batch (standard: 100; sätt 0 för obegränsat).
## Pipelines {#pipelines}
### Kör en pipeline {#execute-a-pipeline}
```bash
# Single file
curl -X POST http://localhost:1349/api/v1/pipeline/execute \
Varje stegs utdata är nästa stegs indata. Pipelines tillåter 20 steg som standard, konfigurerbart via `MAX_PIPELINE_STEPS`. Sätt `MAX_PIPELINE_STEPS=0` för att ta bort gränsen.
### Spara och hantera pipelines {#save-and-manage-pipelines}
| `GET` | `/api/v1/pipeline/list` | Lista sparade pipelines (admins ser alla; användare ser sina egna) |
| `DELETE` | `/api/v1/pipeline/:id` | Ta bort (ägare eller admin) |
| `GET` | `/api/v1/pipeline/tools` | Lista verktygs-ID:n som är giltiga för pipeline-steg |
## Förloppsspårning {#progress-tracking}
Långvariga jobb, köade verktyg, batchjobb och pipelines sänder realtidsförlopp via Server-Sent Events. Förloppsströmmen är publik och identifieras med jobb-ID, så klienter behöver inte skicka en Authorization-header för att läsa den.
```bash
# Connect to the SSE stream (jobId is in the JSON response body from the tool endpoint)
| `GET` | `/api/v1/files/:id/preview` | Strömma en cachad eller genererad webbläsarkompatibel förhandsvisning för en sparad PDF, ett Office-dokument, en video- eller ljudfil |
| `POST` | `/api/v1/preview/generate` | Generera en on-demand MP4- eller MP3-förhandsvisning för en uppladdad mediefil utan att spara den först |
| `GET` | `/api/v1/download/:jobId/:filename` | Ladda ner en bearbetad fil från en arbetsyta |
För att automatiskt spara ett verktygsresultat till biblioteket, inkludera `fileId` som ett multipart-formulärfält som refererar till en befintlig biblioteksfil. Det bearbetade resultatet sparas som en ny version.
## Hantering av API-nycklar {#api-key-management}
| Metod | Sökväg | Åtkomst | Beskrivning |
|--------|------|--------|-------------|
| `POST` | `/api/v1/api-keys` | Auth | Generera ny nyckel - visas en gång |
| `GET` | `/api/v1/api-keys` | Auth | Lista nycklar (name, id, lastUsedAt - inte den råa nyckeln) |
| `DELETE` | `/api/v1/api-keys/:id` | Auth | Ta bort nyckel |
## Team {#teams}
| Metod | Sökväg | Åtkomst | Beskrivning |
|--------|------|--------|-------------|
| `GET` | `/api/v1/teams` | Admin (`teams:manage`) | Lista team |
| `POST` | `/api/v1/teams` | Admin (`teams:manage`) | Skapa team |
| `PUT` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Byt namn på team |
| `DELETE` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Ta bort team (kan inte ta bort standardteamet eller team med medlemmar) |
## Inställningar {#settings}
Körtidskonfiguration i nyckel-värde-format (läses av alla autentiserade användare, skrivs endast av admin).
| Metod | Sökväg | Beskrivning |
|--------|------|-------------|
| `GET` | `/api/v1/settings` | Hämta alla inställningar |
| `GET` | `/api/v1/settings/:key` | Hämta en specifik inställning via nyckel |
Kända nycklar: `disabledTools` (JSON-array av verktygs-ID:n), `enableExperimentalTools` (bool-sträng), `loginAttemptLimit` (nummer).
## Inställningar (per användare) {#preferences}
Per-användarinställningar är separata från instansinställningar. Alla autentiserade användare kan läsa och uppdatera sin egen inställningskarta.
| Metod | Sökväg | Beskrivning |
|--------|------|-------------|
| `GET` | `/api/v1/preferences` | Hämta den aktuella användarens inställningar som `{ "preferences": { ... } }` |
| `PUT` | `/api/v1/preferences` | Infoga eller uppdatera en eller flera inställningsnycklar för den aktuella användaren |
## Roller {#roles}
Anpassad rollhantering med granulära behörigheter.
| Metod | Sökväg | Åtkomst | Beskrivning |
|--------|------|--------|-------------|
| `GET` | `/api/v1/roles` | Admin (`audit:read`) | Lista alla roller med antal användare |
| `POST` | `/api/v1/roles` | Admin (`security:manage`) | Skapa en anpassad roll (`name`, `description`, `permissions`) |
| `PUT` | `/api/v1/roles/:id` | Admin (`security:manage`) | Uppdatera en anpassad roll (kan inte ändra inbyggda roller) |
| `DELETE` | `/api/v1/roles/:id` | Admin (`security:manage`) | Ta bort en anpassad roll (kan inte ta bort inbyggda roller; berörda användare återgår till `user`-rollen) |
| `action` | Filtrera efter åtgärdstyp (t.ex. `ROLE_CREATED`, `ROLE_DELETED`) |
| `ip` | Filtrera efter käll-IP-adress |
| `from` | Filtrera poster efter detta ISO 8601-datum |
| `to` | Filtrera poster före detta ISO 8601-datum |
## Analys {#analytics}
| Metod | Sökväg | Åtkomst | Beskrivning |
|--------|------|--------|-------------|
| `GET` | `/api/v1/config/analytics` | Publik | Hämta den effektiva analyskonfigurationen (PostHog-nyckel, Sentry DSN, samplingsfrekvens). Nycklar, DSN och instans-ID är tomma när analys är avstängt, antingen från kompileringstidsbakningen eller instansens `analyticsEnabled`-inställning. |
| `POST` | `/api/v1/feedback` | Auth | Skicka explicit användarfeedback till det konfigurerade PostHog-projektet som `feedback_submitted`. Rutten respekterar analysgrindpunkten, begränsar antalet inskick, tar bort kontaktfält om inte `contactOk` är true, och accepterar aldrig filinnehåll, filnamn, uppladdningssökvägar eller rå privat feltext. När analys är inaktiverad returnerar den `{ "ok": true, "accepted": false }`. |
| `PUT` | `/api/v1/settings` | Admin (`settings:write`) | Ställ in den instansomfattande opt-outen. Skicka en JSON-kropp `{ "analyticsEnabled": "false" }` för att stänga av analys för alla, eller `"true"` för att slå på den igen. |
## Funktioner / AI-buntar {#features-ai-bundles}
Hantera AI-funktionsbuntar (installera/avinstallera AI-modellpaket i Docker-miljön). Föredra slutpunkten för installation på verktygsnivå när du aktiverar ett verktyg från anpassad automatisering: vissa AI-verktyg behöver mer än en delad bunt, och denna slutpunkt hoppar över redan installerade buntar och köar endast de saknade.
OCR är en valfri förbättring snarare än ett hårt beroende. Dess `fast` Tesseract-nivå fungerar utan ett paket; `POST /api/v1/admin/features/ocr/install` installerar det signerade RapidOCR-paketet för `balanced` och `best` på Linux amd64 eller arm64. Den exakta OCR-körtiden använder CPU på endast CPU- och NVIDIA-värdar och kräver minst 4 GiB effektivt minne (den konfigurerade behållarens cgroup-gräns, annars värdminne). SnapOtter rapporterar `requiredMemoryBytes`, `effectiveMemoryBytes` och en `insufficient-memory`-kompatibilitetsskäl och avvisar en inkompatibel installation före nedladdning. Detta minneskrav gäller inte för `fast`. Paketet är cirka 208-234 MiB att ladda ner och 409-488 MiB installerat, beroende på målet; det signerade indexet binder de exakta storlekarna som tillämpas under installationen.
| `GET` | `/api/v1/features` | Auth | Lista alla funktionsbuntar och deras installationsstatus |
| `POST` | `/api/v1/admin/features/:bundleId/install` | Admin (`features:manage`) | Installera en funktionsbunt (asynkron, returnerar `jobId` för förloppsspårning) |
| `POST` | `/api/v1/admin/tools/:toolId/features/install` | Admin (`features:manage`) | Installera varje bunt som ett verktyg kräver; returnerar köad/överhoppad status per bunt |
| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Admin (`features:manage`) | Avinstallera en funktionsbunt och rensa upp modellfiler |
| `GET` | `/api/v1/admin/features/disk-usage` | Admin (`features:manage`) | Hämta total diskanvändning för AI-modeller |
| `POST` | `/api/v1/admin/features/import` | Admin (`features:manage`) | Importera ett äldre AI-paket (`file`) eller en signerad offline OCR-version (`index` plus `archive`) |
En luftgap OCR-import måste innehålla releasens signerade `ocr-runtime-index.json` och det matchande plattformsarkivet. SnapOtter tillämpar samma Ed25519-signatur, artefakthash, kompatibilitet, extraktion och röktestkontroller som används av onlineinstallation:
```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"
```
Använd `linux-arm64-cpu-py311`-arkivet på arm64. En signerad artefakt för ett annat mål avvisas istället för att installeras.
