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: "Riferimento del motore AI con tutti gli strumenti ML locali. Rimozione dello sfondo, upscaling, OCR, rilevamento dei volti, restauro fotografico e altro ancora."
+i18n_source_hash: 14728c1dcd05
+i18n_provenance: machine
+i18n_output_hash: 306a1e2df486
+---
+
+# Riferimento del motore AI {#ai-engine-reference}
+
+Il pacchetto `@snapotter/ai` fa da ponte tra Node.js e un **sidecar Python persistente** per tutte le operazioni ML. Il processo dispatcher resta attivo tra una richiesta e l'altra per garantire prestazioni rapide con avvio a caldo. NVIDIA CUDA viene rilevata automaticamente all'avvio e usata quando disponibile; in caso contrario gli strumenti AI vengono eseguiti su CPU.
+
+Oggi l'accelerazione tramite iGPU Intel/AMD con VA-API, Quick Sync o OpenCL non è supportata per l'inferenza AI. Mappare `/dev/dri` in un container non accelera questi strumenti del sidecar Python a meno che non sia disponibile una GPU NVIDIA compatibile con CUDA.
+
+19 strumenti AI del sidecar Python distribuiti su quattro modalità (immagine, audio, video, documento), più 2 strumenti con funzionalità AI opzionali. Tutti i modelli vengono eseguiti in locale, senza bisogno di connessione a internet dopo il download iniziale del modello.
+
+## Architettura {#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)
+```
+
+Un profilo dispatcher "docs" separato sostituisce l'allowlist AI con script per l'elaborazione dei documenti (`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`) e salta gli import ML pesanti.
+
+**Timeout:** 300 s di default; OCR e rimozione dello sfondo con BiRefNet ottengono 600 s.
+
+## Bundle di funzionalità {#feature-bundles}
+
+I modelli AI sono raggruppati per stack di dipendenze condivise, non con un archivio per ogni strumento. Un bundle di funzionalità può abilitare più strumenti quando questi usano la stessa famiglia di modelli, gli stessi wheel Python o le stesse librerie native. Questo mantiene più piccola l'immagine Docker di rilascio ed evita di conservare copie duplicate degli stessi modelli di matting dello sfondo, rilevamento dei volti, OCR, restauro e riconoscimento vocale.
+
+L'immagine Docker include l'applicazione più il runtime comune. Gli archivi di modelli di grandi dimensioni vengono scaricati su richiesta nel volume persistente `/data/ai`, poi riutilizzati da ogni strumento che ne ha bisogno. Se un bundle è già installato perché un altro strumento ne aveva bisogno, abilitare un nuovo strumento dipendente non scarica di nuovo quel bundle.
+
+Ogni strumento AI richiede uno o più bundle di funzionalità prima di poter essere eseguito. La UI di amministrazione installa per strumento tramite `POST /api/v1/admin/tools/:toolId/features/install`, che risolve l'elenco completo dei bundle, salta quelli già installati e mette in coda solo i download mancanti. Ad esempio, abilitare Passport Photo su un'istanza nuova mette in coda `background-removal` e `face-detection`; abilitarlo dopo che Background Removal è già installato mette in coda solo `face-detection`.
+
+| Bundle | Dimensione | Gruppo di dipendenze condivise | Strumenti che lo usano |
+|--------|------|-------------------------|-------------------|
+| `background-removal` | 4-5 GB | rembg / matting dello sfondo BiRefNet | remove-background, passport-photo, transparency-fixer, background-replace, blur-background |
+| `face-detection` | 200-300 MB | rilevamento dei volti e landmark MediaPipe | blur-faces, red-eye-removal, smart-crop |
+| `object-eraser-colorize` | 1-2 GB | inpainting/outpainting LaMa e DDColor | erase-object, colorize, ai-canvas-expand |
+| `upscale-enhance` | 5-6 GB | RealESRGAN, GFPGAN / CodeFormer, denoising | upscale, enhance-faces, noise-removal |
+| `photo-restoration` | 4-5 GB | pipeline di riparazione dei graffi e restauro | restore-photo |
+| `ocr` | 5-6 GB | stack OCR PaddleOCR / Tesseract | ocr, ocr-pdf |
+| `transcription` | ~600 MB | modelli speech-to-text faster-whisper | transcribe-audio, auto-subtitles |
+
+Strumenti con dipendenze tra più bundle:
+
+| Strumento | Bundle richiesti | Perché |
+|------|------------------|-----|
+| `passport-photo` | `background-removal`, `face-detection` | Rimuove lo sfondo, poi usa i landmark del volto per inquadrare il ritaglio secondo le regole delle foto per passaporto e documenti di identità. |
+| `enhance-faces` | `upscale-enhance`, `face-detection` | Rileva i volti prima di eseguire il miglioramento GFPGAN o CodeFormer sulle regioni facciali selezionate. |
+
+Uno strumento è disponibile solo quando tutti i bundle richiesti sono installati. Le installazioni parziali sono valide e vengono gestite in modo incrementale: i bundle installati vengono riutilizzati, quelli mancanti vengono mostrati come download e le installazioni in coda vengono eseguite una alla volta, così l'ambiente Python condiviso non viene modificato in modo concorrente.
+
+---
+
+## Rimozione dello sfondo {#background-removal}
+
+**Route dello strumento:** `remove-background`  
+**Modello:** rembg con BiRefNet (predefinito) o varianti U2-Net
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `model` | string | - | Variante del modello (override opzionale) |
+| `backgroundType` | string | `"transparent"` | Uno tra: `transparent`, `color`, `gradient`, `blur`, `image` |
+| `backgroundColor` | string | - | Colore esadecimale per lo sfondo pieno |
+| `gradientColor1` | string | - | Primo colore del gradiente |
+| `gradientColor2` | string | - | Secondo colore del gradiente |
+| `gradientAngle` | number | - | Angolo del gradiente in gradi |
+| `blurEnabled` | boolean | - | Abilita l'effetto sfocatura dello sfondo |
+| `blurIntensity` | number (0-100) | - | Intensità della sfocatura |
+| `shadowEnabled` | boolean | - | Abilita l'ombra proiettata sul soggetto |
+| `shadowOpacity` | number (0-100) | - | Opacità dell'ombra |
+| `outputFormat` | string | - | Formato di output: `png`, `webp` o `avif` |
+| `edgeRefine` | integer (0-3) | - | Livello di rifinitura dei bordi |
+| `decontaminate` | boolean | - | Rimuove le sbavature di colore dai bordi |
+
+## Sostituzione dello sfondo {#background-replace}
+
+**Route dello strumento:** `background-replace`  
+**Modello:** rembg / BiRefNet (condiviso con remove-background)
+
+Rimuove lo sfondo e lo sostituisce con un colore pieno o un gradiente.
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `backgroundType` | `"color"` \| `"gradient"` | `"color"` | Modalità sfondo |
+| `color` | string | `"#ffffff"` | Colore esadecimale dello sfondo (quando `backgroundType` è `color`) |
+| `gradientColor1` | string | - | Primo colore esadecimale del gradiente |
+| `gradientColor2` | string | - | Secondo colore esadecimale del gradiente |
+| `gradientAngle` | integer (0-360) | `180` | Angolo del gradiente in gradi |
+| `feather` | integer (0-20) | `0` | Raggio di sfumatura dei bordi |
+| `format` | `"png"` \| `"webp"` | `"png"` | Formato di output |
+
+## Sfocatura dello sfondo {#blur-background}
+
+**Route dello strumento:** `blur-background`  
+**Modello:** rembg / BiRefNet (condiviso con remove-background)
+
+Sfoca lo sfondo mantenendo nitido il soggetto.
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `intensity` | integer (1-100) | `50` | Intensità della sfocatura |
+| `feather` | integer (0-20) | `0` | Raggio di sfumatura dei bordi |
+| `format` | `"png"` \| `"webp"` | `"png"` | Formato di output |
+
+## Upscaling delle immagini {#image-upscaling}
+
+**Route dello strumento:** `upscale`  
+**Modello:** RealESRGAN (con fallback Lanczos quando non disponibile)
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `scale` | number | `2` | Fattore di upscaling |
+| `model` | string | `"auto"` | Variante del modello |
+| `faceEnhance` | boolean | `false` | Applica un passaggio di miglioramento dei volti GFPGAN |
+| `denoise` | number | `0` | Intensità del denoising |
+| `format` | string | `"auto"` | Override del formato di output |
+| `quality` | number | `95` | Qualità di output (1-100) |
+
+## OCR / Estrazione del testo {#ocr-text-extraction}
+
+**Route dello strumento:** `ocr`  
+**Modelli:** Tesseract (veloce), PaddleOCR PP-OCRv5 (bilanciato), PaddleOCR-VL 1.5 (migliore)
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Livello di elaborazione |
+| `language` | string | `"auto"` | Lingua: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
+| `enhance` | boolean | `true` | Pre-elabora l'immagine per migliorare la precisione dell'OCR |
+| `engine` | string | - | Deprecato. Mappa `tesseract` su `fast`, `paddleocr` su `balanced` |
+
+Restituisce risultati strutturati con riquadri di delimitazione, punteggi di confidenza e blocchi di testo estratti.
+
+## OCR di PDF {#pdf-ocr}
+
+**Route dello strumento:** `ocr-pdf`  
+**Modelli:** Stesso sistema a livelli dell'OCR delle immagini
+
+Estrae il testo dai documenti PDF scansionati usando l'OCR basato su AI, pagina per pagina.
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Livello di elaborazione |
+| `language` | string | `"auto"` | Lingua: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
+| `pages` | string | `"all"` | Selezione delle pagine: `"all"`, `"1-3"`, `"1,3,5"` |
+
+## Sfocatura di volti / PII {#face-pii-blur}
+
+**Route dello strumento:** `blur-faces`  
+**Modello:** rilevamento dei volti MediaPipe
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `blurRadius` | number (1-100) | `30` | Raggio della sfocatura gaussiana |
+| `sensitivity` | number (0-1) | `0.5` | Soglia di confidenza del rilevamento |
+
+## Miglioramento dei volti {#face-enhancement}
+
+**Route dello strumento:** `enhance-faces`  
+**Modelli:** GFPGAN, CodeFormer
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `model` | `"auto"` \| `"gfpgan"` \| `"codeformer"` | `"auto"` | Modello di miglioramento |
+| `strength` | number (0-1) | `0.8` | Intensità del miglioramento |
+| `sensitivity` | number (0-1) | `0.5` | Soglia di rilevamento dei volti |
+| `onlyCenterFace` | boolean | `false` | Migliora solo il volto più centrale |
+
+## Colorizzazione AI {#ai-colorization}
+
+**Route dello strumento:** `colorize`  
+**Modello:** DDColor (con fallback DNN OpenCV)
+
+Converte in pieno colore le foto in bianco e nero o in scala di grigi.
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `intensity` | number (0-1) | `1.0` | Intensità della saturazione del colore |
+| `model` | `"auto"` \| `"ddcolor"` \| `"opencv"` | `"auto"` | Variante del modello |
+
+## Rimozione del rumore {#noise-removal}
+
+**Route dello strumento:** `noise-removal`  
+**Modello:** SCUNet (pipeline di denoising a livelli)
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `tier` | `"quick"` \| `"balanced"` \| `"quality"` \| `"maximum"` | `"balanced"` | Livello di elaborazione |
+| `strength` | number (0-100) | `50` | Intensità del denoising |
+| `detailPreservation` | number (0-100) | `50` | Quanto dettaglio preservare; valori più alti mantengono più texture |
+| `colorNoise` | number (0-100) | `30` | Intensità della riduzione del rumore cromatico |
+| `format` | string | `"original"` | Formato di output: `original`, `png`, `jpeg`, `webp`, `avif`, `jxl` |
+| `quality` | number (1-100) | `90` | Qualità di codifica dell'output |
+
+## Rimozione degli occhi rossi {#red-eye-removal}
+
+**Route dello strumento:** `red-eye-removal`
+
+Rileva i landmark del volto, individua le regioni degli occhi e corregge la sovrasaturazione del canale rosso.
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `sensitivity` | number (0-100) | `50` | Soglia di rilevamento dei pixel rossi |
+| `strength` | number (0-100) | `70` | Intensità della correzione |
+| `format` | string | - | Override del formato di output (opzionale) |
+| `quality` | number (1-100) | `90` | Qualità di output |
+
+## Restauro fotografico {#photo-restoration}
+
+**Route dello strumento:** `restore-photo`
+
+Pipeline multi-step per foto vecchie o danneggiate: rilevamento e riparazione di graffi/strappi, miglioramento dei volti, denoising e colorizzazione opzionale.
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `scratchRemoval` | boolean | `true` | Rileva e ripara graffi e strappi |
+| `faceEnhancement` | boolean | `true` | Applica un passaggio di miglioramento dei volti |
+| `fidelity` | number (0-1) | `0.7` | Intensità del miglioramento dei volti (più alto = più conservativo) |
+| `denoise` | boolean | `true` | Applica un passaggio di denoising |
+| `denoiseStrength` | number (0-100) | `25` | Intensità del denoising |
+| `colorize` | boolean | `false` | Colorizza dopo il restauro |
+| `colorizeStrength` | number (0-100) | `85` | Intensità della colorizzazione |
+
+## Foto per passaporto {#passport-photo}
+
+**Route dello strumento:** `passport-photo`  
+**Modelli:** landmark del volto MediaPipe + rimozione dello sfondo BiRefNet
+
+Flusso di lavoro in due fasi: analisi (rilevamento del volto + rimozione dello sfondo) poi generazione (ritaglio, ridimensionamento, disposizione a griglia). Supporta oltre 37 paesi in 6 regioni.
+
+### Fase 1: Analisi {#phase-1-analyze}
+
+`POST /api/v1/tools/image/passport-photo/analyze`
+
+Accetta un file immagine (multipart). Restituisce i dati dei landmark del volto, un'anteprima base64 e le dimensioni dell'immagine.
+
+### Fase 2: Generazione {#phase-2-generate}
+
+`POST /api/v1/tools/image/passport-photo/generate`
+
+Accetta un corpo JSON con i risultati della Fase 1 più le impostazioni di generazione:
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `jobId` | string | (obbligatorio) | ID del job dalla Fase 1 |
+| `filename` | string | (obbligatorio) | Nome file originale dalla Fase 1 |
+| `countryCode` | string | (obbligatorio) | Codice paese ISO (es. `US`, `GB`, `IN`) |
+| `documentType` | string | `"passport"` | Tipo di documento |
+| `bgColor` | string | `"#FFFFFF"` | Colore esadecimale dello sfondo |
+| `printLayout` | string | `"none"` | Layout di stampa: `none`, `4x6`, `a4`, `letter` |
+| `maxFileSizeKb` | number | `0` | Dimensione massima del file in KB (0 = nessun limite) |
+| `dpi` | number (72-1200) | `300` | DPI di output |
+| `customWidthMm` | number | - | Larghezza personalizzata in mm (sovrascrive le specifiche del paese) |
+| `customHeightMm` | number | - | Altezza personalizzata in mm (sovrascrive le specifiche del paese) |
+| `zoom` | number (0.5-3) | `1` | Fattore di zoom |
+| `adjustX` | number | `0` | Regolazione della posizione orizzontale |
+| `adjustY` | number | `0` | Regolazione della posizione verticale |
+| `landmarks` | object | (obbligatorio) | Landmark dalla Fase 1 |
+| `imageWidth` | number | (obbligatorio) | Larghezza dell'immagine dalla Fase 1 |
+| `imageHeight` | number | (obbligatorio) | Altezza dell'immagine dalla Fase 1 |
+
+## Cancellazione di oggetti (Inpainting) {#object-erasing-inpainting}
+
+**Route dello strumento:** `erase-object`  
+**Modello:** LaMa tramite ONNX Runtime
+
+La maschera viene inviata come **seconda parte del file** (fieldname `mask`), non come base64. I pixel bianchi nella maschera indicano le aree da cancellare. Le impostazioni `format` e `quality` vengono inviate come campi form di primo livello.
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `file` | file | (obbligatorio) | Immagine sorgente (multipart) |
+| `mask` | file | (obbligatorio) | Immagine della maschera (multipart, fieldname `mask`, bianco = cancella) |
+| `format` | string | `"auto"` | Formato di output: `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl` |
+| `quality` | integer (1-100) | `95` | Qualità di output |
+
+Accelerato con CUDA quando è disponibile una GPU NVIDIA.
+
+## Espansione AI della tela {#ai-canvas-expand}
+
+**Route dello strumento:** `ai-canvas-expand`  
+**Modello:** outpainting basato su LaMa
+
+Espande la tela di un'immagine in qualsiasi direzione e riempie le nuove aree con contenuti generati dall'AI che corrispondono all'immagine esistente.
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `extendTop` | integer | `0` | Pixel da estendere in alto |
+| `extendRight` | integer | `0` | Pixel da estendere a destra |
+| `extendBottom` | integer | `0` | Pixel da estendere in basso |
+| `extendLeft` | integer | `0` | Pixel da estendere a sinistra |
+| `tier` | `"fast"` \| `"balanced"` \| `"high"` | `"balanced"` | Livello di qualità |
+| `format` | string | `"auto"` | Formato di output: `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl` |
+| `quality` | integer (1-100) | `95` | Qualità di output |
+
+Almeno una direzione di estensione deve essere maggiore di 0.
+
+## Ritaglio intelligente {#smart-crop}
+
+**Route dello strumento:** `smart-crop`  
+**Modello:** rilevamento dei volti MediaPipe (solo modalità volto)
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `mode` | string | `"subject"` | Strategia di ritaglio: `subject`, `face`, `trim` |
+| `strategy` | `"attention"` \| `"entropy"` | `"attention"` | Strategia per la modalità soggetto |
+| `width` | integer | - | Larghezza di output |
+| `height` | integer | - | Altezza di output |
+| `padding` | integer (0-50) | `0` | Percentuale di margine attorno al soggetto |
+| `facePreset` | string | `"head-shoulders"` | Inquadratura predefinita quando `mode=face` |
+| `sensitivity` | number (0-1) | `0.5` | Soglia di rilevamento dei volti |
+| `threshold` | integer (0-255) | `30` | Soglia di rilevamento dello sfondo (modalità di rifilatura) |
+| `padToSquare` | boolean | `false` | Riempi il risultato rifilato fino a formare un quadrato |
+| `padColor` | string | `"#ffffff"` | Colore di sfondo per il riempimento quadrato |
+| `targetSize` | integer | - | Dimensione target per l'output con riempimento (pixel) |
+| `quality` | integer (1-100) | - | Qualità di output |
+
+I valori legacy di `mode` `attention` e `content` sono accettati e mappati rispettivamente su `subject` e `trim`.
+
+**Preset per i volti:**
+
+| Preset | Ideale per |
+|--------|---------|
+| `closeup` | Ritratti in primo piano |
+| `head-shoulders` | Foto profilo |
+| `upper-body` | LinkedIn / formale |
+| `half-body` | Busto completo |
+
+## Trascrizione dell'audio {#transcribe-audio}
+
+**Route dello strumento:** `transcribe-audio`  
+**Modello:** faster-whisper
+
+Converte il parlato in testo. Supporta i formati di output testo semplice, SRT e VTT.
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `language` | string | `"auto"` | Lingua: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
+| `outputFormat` | `"txt"` \| `"srt"` \| `"vtt"` | `"txt"` | Formato di output |
+
+## Sottotitoli automatici {#auto-subtitles}
+
+**Route dello strumento:** `auto-subtitles`  
+**Modello:** faster-whisper (estrae l'audio dal video, poi lo trascrive)
+
+Genera file di sottotitoli dalla traccia audio di un video.
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `language` | string | `"auto"` | Lingua: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
+| `format` | `"srt"` \| `"vtt"` | `"srt"` | Formato dei sottotitoli di output |
+
+## Correttore di trasparenza PNG {#png-transparency-fixer}
+
+**Route dello strumento:** `transparency-fixer`  
+**Modello:** matting HR BiRefNet (risoluzione 2048x2048)
+
+Corregge i PNG "a falsa trasparenza" in cui lo sfondo è stato rimosso ma ha lasciato bordi frastagliati, aloni o artefatti semi-trasparenti. Usa il modello di matting ad alta risoluzione di BiRefNet per produrre un canale alfa pulito, poi applica un'elaborazione di defringe configurabile per rimuovere la contaminazione cromatica lungo i bordi.
+
+**Catena di fallback OOM:** Se il matting HR BiRefNet supera la memoria disponibile, lo strumento ricade automaticamente su `birefnet-general`, poi su `u2net`.
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `defringe` | number (0-100) | `30` | Intensità del defringe dei bordi per rimuovere la contaminazione cromatica |
+| `outputFormat` | `"png"` \| `"webp"` | `"png"` | Formato dell'immagine di output |
+| `removeWatermark` | boolean | `false` | Applica la pre-elaborazione di rimozione della filigrana (filtro mediano) |
+
+```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"}'
+```
+
+---
+
+## Strumenti con funzionalità AI opzionali {#tools-with-optional-ai-capabilities}
+
+I seguenti strumenti non sono strumenti del sidecar Python ma usano funzionalità AI quando determinate opzioni sono abilitate.
+
+### Miglioramento delle immagini {#image-enhancement}
+
+**Route dello strumento:** `image-enhancement`  
+**Motore:** basato su analisi (istogramma e statistiche di Sharp)
+
+Analizza l'immagine e applica correzioni automatiche per esposizione, contrasto, bilanciamento del bianco, saturazione, nitidezza e rumore. Supporta modalità specifiche per scena.
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `mode` | `"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"` | `"auto"` | Modalità scena per la messa a punto delle correzioni |
+| `intensity` | number (0-100) | `50` | Intensità complessiva della correzione |
+| `corrections.exposure` | boolean | `true` | Applica la correzione dell'esposizione |
+| `corrections.contrast` | boolean | `true` | Applica la correzione del contrasto |
+| `corrections.whiteBalance` | boolean | `true` | Applica la correzione del bilanciamento del bianco |
+| `corrections.saturation` | boolean | `true` | Applica la correzione della saturazione |
+| `corrections.sharpness` | boolean | `true` | Applica la correzione della nitidezza |
+| `corrections.denoise` | boolean | `true` | Applica il denoising |
+| `deepEnhance` | boolean | `false` | Abilita la rimozione AI del rumore tramite SCUNet (richiede il bundle `upscale-enhance`) |
+
+Un endpoint di analisi aggiuntivo è disponibile su `POST /api/v1/tools/image/image-enhancement/analyze` che restituisce le correzioni rilevate senza applicarle.
+
+### Ridimensionamento content-aware (Seam Carving) {#content-aware-resize-seam-carving}
+
+**Route dello strumento:** `content-aware-resize`  
+**Motore:** binario Go `caire` (non Python, nessun beneficio dalla GPU)
+
+Ridimensiona in modo intelligente le immagini rimuovendo le cuciture a bassa energia, preservando i contenuti importanti.
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `width` | number | - | Larghezza target |
+| `height` | number | - | Altezza target |
+| `protectFaces` | boolean | `false` | Protegge le regioni facciali rilevate (richiede il bundle `face-detection`) |
+| `blurRadius` | number (0-20) | `4` | Pre-sfocatura per il calcolo dell'energia |
+| `sobelThreshold` | number (1-20) | `2` | Soglia di sensibilità dei bordi |
+| `square` | boolean | `false` | Forza l'output quadrato |
@@ -0,0 +1,211 @@
+---
+description: "Riferimento delle operazioni del motore delle immagini. Tutte le operazioni di elaborazione delle immagini basate su Sharp e i loro parametri."
+i18n_source_hash: 42febdf85fa8
+i18n_provenance: human
+i18n_output_hash: 864b5292c45c
+---
+
+# Motore delle immagini {#image-engine}
+
+Il pacchetto `@snapotter/image-engine` gestisce tutte le operazioni sulle immagini non basate sull'AI. Fa da wrapper a [Sharp](https://sharp.pixelplumbing.com/) e viene eseguito interamente in-process senza dipendenze esterne.
+
+## Operazioni {#operations}
+
+### resize {#resize}
+
+Scala un'immagine a dimensioni specifiche o in percentuale.
+
+| Parametro | Tipo | Descrizione |
+|---|---|---|
+| `width` | number | Larghezza target in pixel |
+| `height` | number | Altezza target in pixel |
+| `fit` | string | `cover`, `contain`, `fill`, `inside` o `outside` |
+| `withoutEnlargement` | boolean | Se true, non ingrandisce le immagini più piccole |
+| `percentage` | number | Scala in percentuale invece che con dimensioni assolute |
+
+Puoi impostare `width`, `height` o entrambi. Se ne imposti solo uno, l'altro viene calcolato per mantenere le proporzioni.
+
+### crop {#crop}
+
+Ritaglia una regione rettangolare dall'immagine.
+
+| Parametro | Tipo | Descrizione |
+|---|---|---|
+| `left` | number | Scostamento X dal bordo sinistro |
+| `top` | number | Scostamento Y dal bordo superiore |
+| `width` | number | Larghezza dell'area di ritaglio |
+| `height` | number | Altezza dell'area di ritaglio |
+| `unit` | string | `px` (predefinito) o `percent` |
+
+### rotate {#rotate}
+
+Ruota l'immagine di un dato angolo.
+
+| Parametro | Tipo | Descrizione |
+|---|---|---|
+| `angle` | number | Angolo di rotazione in gradi (0-360) |
+| `background` | string | Colore di riempimento per l'area esposta (predefinito: `#000000`). Si applica solo agli angoli diversi da 90 gradi. |
+
+### flip {#flip}
+
+Specchia l'immagine orizzontalmente, verticalmente o entrambi. Almeno uno deve essere true.
+
+| Parametro | Tipo | Descrizione |
+|---|---|---|
+| `horizontal` | boolean | Specchia da sinistra a destra |
+| `vertical` | boolean | Specchia dall'alto in basso |
+
+### convert {#convert}
+
+Cambia il formato dell'immagine.
+
+| Parametro | Tipo | Descrizione |
+|---|---|---|
+| `format` | string | Formato target: `jpg`, `png`, `webp`, `avif`, `tiff`, `gif`, `jxl`, `heic`, `heif`, `bmp`, `ico`, `jp2`, `qoi` |
+| `quality` | number | Qualità di compressione (1-100, si applica ai formati con perdita) |
+
+I primi sette formati (da `jpg` a `jxl`) vengono codificati da Sharp in-process. I formati rimanenti usano encoder esterni a livello di API: `heic`/`heif` tramite heif-enc, `bmp`/`ico` tramite ImageMagick, `jp2` tramite opj_compress e `qoi` tramite un codec TypeScript inline.
+
+### compress {#compress}
+
+Riduce la dimensione del file mantenendo lo stesso formato.
+
+| Parametro | Tipo | Descrizione |
+|---|---|---|
+| `quality` | number | Qualità target (1-100) |
+| `targetSizeBytes` | number | Dimensione target opzionale del file in byte |
+| `format` | string | Override opzionale del formato |
+
+### strip-metadata {#strip-metadata}
+
+Rimuove i metadati EXIF, IPTC, XMP e ICC dall'immagine. Senza parametri (o `stripAll: true`), rimuove tutto. Passa singoli flag per una rimozione selettiva.
+
+| Parametro | Tipo | Descrizione |
+|---|---|---|
+| `stripAll` | boolean | Rimuove tutti i metadati (predefinito quando nessun flag è impostato) |
+| `stripExif` | boolean | Rimuove i dati EXIF (incluso il GPS se `stripGps` non è impostato separatamente) |
+| `stripGps` | boolean | Rimuove i dati di posizione GPS |
+| `stripIcc` | boolean | Rimuove il profilo colore ICC |
+| `stripXmp` | boolean | Rimuove i metadati XMP |
+
+### Regolazioni del colore {#color-adjustments}
+
+Queste operazioni modificano le proprietà cromatiche di un'immagine. Ognuna accetta un singolo valore numerico.
+
+| Operazione | Parametro | Intervallo | Descrizione |
+|---|---|---|---|
+| `brightness` | `value` | da -100 a 100 | Regola la luminosità |
+| `contrast` | `value` | da -100 a 100 | Regola il contrasto |
+| `saturation` | `value` | da -100 a 100 | Regola la saturazione del colore |
+
+### Filtri del colore {#color-filters}
+
+Questi applicano una trasformazione cromatica fissa. Non accettano parametri.
+
+| Operazione | Descrizione |
+|---|---|
+| `grayscale` | Converte in scala di grigi |
+| `sepia` | Applica una tonalità seppia |
+| `invert` | Inverte tutti i colori |
+
+### Canali del colore {#color-channels}
+
+Regola i singoli canali di colore RGB. I valori sono moltiplicatori dove 100 = nessuna modifica.
+
+| Parametro | Tipo | Descrizione |
+|---|---|---|
+| `red` | number | Moltiplicatore del canale rosso (da 0 a 200, 100 = invariato) |
+| `green` | number | Moltiplicatore del canale verde (da 0 a 200, 100 = invariato) |
+| `blue` | number | Moltiplicatore del canale blu (da 0 a 200, 100 = invariato) |
+
+### sharpen {#sharpen}
+
+Nitidezza semplice controllata da un singolo valore.
+
+| Parametro | Tipo | Descrizione |
+|---|---|---|
+| `value` | number | Intensità della nitidezza (da 0 a 100). Mappata su un sigma gaussiano di 0,5-10. |
+
+### sharpen-advanced {#sharpen-advanced}
+
+Nitidezza avanzata con tre metodi selezionabili e un pre-passaggio opzionale di riduzione del rumore.
+
+| Parametro | Tipo | Descrizione |
+|---|---|---|
+| `method` | string | `adaptive`, `unsharp-mask` o `high-pass` |
+| `sigma` | number | Raggio della sfocatura gaussiana, 0,5-10 (adattivo) |
+| `m1` | number | Nitidezza delle aree piatte, 0-10 (adattivo) |
+| `m2` | number | Nitidezza delle aree con texture, 0-20 (adattivo) |
+| `x1` | number | Soglia piatto/frastagliato, 0-10 (adattivo) |
+| `y2` | number | Schiaritura massima (clamp degli aloni), 0-50 (adattivo) |
+| `y3` | number | Scurimento massimo (clamp degli aloni), 0-50 (adattivo) |
+| `amount` | number | Percentuale di intensità, 0-500 (unsharp-mask) |
+| `radius` | number | Raggio della sfocatura, 0,1-5,0 (unsharp-mask) |
+| `threshold` | number | Luminosità minima dei bordi, 0-255 (unsharp-mask) |
+| `strength` | number | Intensità della fusione, 0-100 (high-pass) |
+| `kernelSize` | number | `3` o `5` per kernel 3x3 / 5x5 (high-pass) |
+| `denoise` | string | Pre-passaggio di riduzione del rumore: `off`, `light`, `medium` o `strong` |
+
+I parametri sono specifici per il metodo. Fornisci solo quelli pertinenti al metodo scelto.
+
+### color-blindness {#color-blindness}
+
+Simula un deficit della visione dei colori usando una matrice di ricombinazione cromatica 3x3.
+
+| Parametro | Tipo | Descrizione |
+|---|---|---|
+| `type` | string | Uno tra: `protanopia`, `deuteranopia`, `tritanopia`, `protanomaly`, `deuteranomaly`, `tritanomaly`, `achromatopsia`, `blueConeMonochromacy` |
+
+### edit-metadata {#edit-metadata}
+
+Scrive o rimuove singoli campi di metadati EXIF/IPTC senza rimuovere l'intero blocco.
+
+| Parametro | Tipo | Descrizione |
+|---|---|---|
+| `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 | Rimuove tutti i tag GPS |
+| `fieldsToRemove` | string[] | Elenco dei nomi dei campi EXIF da eliminare |
+
+Tutti i parametri sono opzionali. I campi elencati in `fieldsToRemove` vengono eliminati dal blocco EXIF esistente. I campi impostati tramite i parametri nominati vengono scritti (o sovrascritti). Le chiavi binarie/non sicure come MakerNote vengono ignorate silenziosamente.
+
+## Rilevamento del formato {#format-detection}
+
+Il motore rileva automaticamente i formati di input dalle intestazioni dei file, non solo dalle estensioni. Questo significa che un file `.jpg` che in realtà è un PNG verrà gestito correttamente. Il rilevamento usa un approccio multi-livello: prima i magic byte, poi l'estensione del file come fallback.
+
+SnapOtter supporta **oltre 55 formati di input** e **13 formati di output**, inclusi 23 formati RAW da fotocamera di oltre 20 marchi, formati professionali (PSD, EPS, OpenEXR, HDR), codec moderni (JPEG XL, AVIF, HEIC, QOI, JPEG 2000) e formati scientifici/di gioco (FITS, DDS). La decodifica è gestita nativamente da Sharp dove possibile, con fallback automatico a ImageMagick, LibRaw e decoder CLI specializzati.
+
+Vedi la pagina [Formati supportati](/it/guide/supported-formats) per l'elenco completo.
+
+## Estrazione dei metadati {#metadata-extraction}
+
+Lo strumento `info` restituisce i metadati dell'immagine. Vedi [Informazioni sull'immagine](/it/tools/image/info) per il riferimento completo dei campi.
+
+```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: "Riferimento completo dell'API REST. Endpoint degli strumenti, elaborazione batch, pipeline, libreria file, autenticazione, team e operazioni di amministrazione."
+i18n_source_hash: 8646977f7cc9
+i18n_provenance: machine
+i18n_output_hash: 1fa1fec30f47
+---
+
+# Riferimento dell'API REST {#rest-api-reference}
+
+La documentazione interattiva dell'API con esempi di richiesta/risposta è disponibile su [http://localhost:1349/api/docs](http://localhost:1349/api/docs).
+
+Specifiche leggibili dalla macchina:
+- `/api/v1/openapi.yaml` - specifica OpenAPI 3.1
+- `/llms.txt` - riepilogo adatto agli LLM
+- `/llms-full.txt` - documentazione completa adatta agli LLM
+
+## Autenticazione {#authentication}
+
+Tutti gli endpoint richiedono l'autenticazione a meno che `AUTH_ENABLED=false`.
+
+### Token di sessione {#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>"
+```
+
+Le sessioni scadono dopo 7 giorni (configurabile tramite `SESSION_DURATION_HOURS`).
+
+### Chiavi 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>"
+```
+
+Le chiavi hanno il prefisso `si_` e sono memorizzate come hash scrypt: la chiave grezza viene mostrata una sola volta e non è più recuperabile.
+
+### Endpoint di autenticazione {#auth-endpoints}
+
+| Metodo | Percorso | Accesso | Descrizione |
+|--------|------|--------|-------------|
+| `POST` | `/api/auth/login` | Pubblico | Accesso, ottieni il token di sessione |
+| `POST` | `/api/auth/logout` | Auth | Distruggi la sessione corrente |
+| `GET` | `/api/auth/session` | Auth | Convalida la sessione corrente |
+| `POST` | `/api/auth/change-password` | Auth | Cambia la propria password (invalida tutte le altre sessioni + chiavi API) |
+| `GET` | `/api/auth/users` | Admin | Elenca tutti gli utenti |
+| `POST` | `/api/auth/register` | Admin | Crea un nuovo utente |
+| `PUT` | `/api/auth/users/:id` | Admin | Aggiorna il ruolo o il team dell'utente |
+| `POST` | `/api/auth/users/:id/reset-password` | Admin | Reimposta la password dell'utente |
+| `DELETE` | `/api/auth/users/:id` | Admin | Elimina un utente |
+| `GET` | `/api/v1/config/auth` | Pubblico | Verifica se l'autenticazione è abilitata (`{ authEnabled: bool }`) |
+| `POST` | `/api/auth/mfa/enroll` | Auth | Avvia l'iscrizione all'MFA TOTP. Richiede la funzionalità enterprise `mfa` |
+| `POST` | `/api/auth/mfa/verify` | Auth | Conferma l'iscrizione all'MFA con un codice TOTP |
+| `POST` | `/api/auth/mfa/complete` | Pubblico | Completa una richiesta di accesso MFA in sospeso |
+| `POST` | `/api/auth/mfa/disable` | Auth | Disabilita l'MFA per l'utente corrente |
+| `POST` | `/api/auth/users/:id/mfa/reset` | Admin (`users:manage`) | Reimposta l'MFA per un utente |
+| `GET` | `/api/auth/oidc/login` | Pubblico | Avvia l'accesso OIDC quando OIDC è abilitato |
+| `GET` | `/api/auth/oidc/callback` | Pubblico | Callback di autorizzazione OIDC |
+| `GET` | `/api/auth/saml/metadata` | Pubblico | XML dei metadati SAML SP quando SAML è abilitato |
+| `GET` | `/api/auth/saml/login` | Pubblico | Avvia l'accesso SAML |
+| `POST` | `/api/auth/saml/callback` | Pubblico | Servizio consumer delle asserzioni SAML |
+
+Quando l'MFA è abilitato per un utente, `POST /api/auth/login` restituisce `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` invece di un token di sessione. Invia quel `mfaToken` più un codice TOTP o di recupero a `/api/auth/mfa/complete`.
+
+### Permessi {#permissions}
+
+| Permesso | Admin | Utente |
+|-----------|:-----:|:----:|
+| Usare gli strumenti | ✓ | ✓ |
+| File/pipeline/chiavi API propri | ✓ | ✓ |
+| Vedere file/pipeline/chiavi di tutti gli utenti | ✓ | - |
+| Scrivere le impostazioni | ✓ | - |
+| Gestire utenti e team | ✓ | - |
+| Gestire il branding | ✓ | - |
+
+## Controllo dello stato {#health-check}
+
+| Metodo | Percorso | Accesso | Descrizione |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/health` | Pubblico | Controllo di base dello stato. Restituisce `{"status":"healthy","version":"..."}` con 200, oppure `{"status":"unhealthy"}` con 503 se il database non è raggiungibile. |
+| `GET` | `/api/v1/readyz` | Pubblico | Sonda di prontezza. Verifica PostgreSQL, Redis, lo spazio su disco e S3 quando configurato. Restituisce 503 quando l'istanza non dovrebbe ricevere traffico. |
+| `GET` | `/api/v1/admin/health` | Admin (`system:health`) | Diagnostica dettagliata che include uptime, modalità di archiviazione, stato del database, stato della coda e disponibilità della GPU. |
+
+## Utilizzo degli strumenti {#using-tools}
+
+Ogni strumento segue lo stesso schema:
+
+```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>` è uno tra `image`, `video`, `audio`, `pdf` o `files`.
+
+- Il caricamento è `multipart/form-data`.
+- `settings` è una stringa JSON con opzioni specifiche dello strumento.
+- `clientJobId` è un campo del modulo facoltativo per la correlazione dell'avanzamento fornita dal chiamante.
+- `fileId` è un campo del modulo facoltativo che fa riferimento a un elemento esistente della libreria file. Quando presente, l'output elaborato viene salvato come nuova versione e la risposta include `savedFileId`.
+- **Strumenti veloci** in genere restituiscono JSON 200: `{"jobId":"...","downloadUrl":"/api/v1/download/<jobId>/<filename>","originalSize":1234,"processedSize":567}`. Recupera il file elaborato da `downloadUrl`.
+- **Qualsiasi strumento in coda** può restituire JSON 202 se è di lunga durata o supera la finestra di attesa sincrona: `{"jobId":"...","async":true}`. Connettiti a SSE per l'avanzamento, quindi scarica al completamento (vedi [Tracciamento dell'avanzamento](#progress-tracking)).
+- Le route **batch** restituiscono un archivio ZIP trasmesso direttamente in streaming (con l'header `X-Job-Id`) per gli strumenti registrati nel registro batch generico.
+
+## Riferimento degli strumenti {#tools-reference}
+
+### Preset di conversione {#conversion-presets}
+
+Il catalogo condiviso include 83 endpoint dedicati ai preset di conversione, come `jpg-to-png`, `mov-to-mp4`, `m4a-to-mp3`, `pdf-to-jpg` e `excel-to-csv`. I preset sono route degli strumenti di prima classe:
+
+`POST /api/v1/tools/<section>/<presetId>`
+
+Ogni preset blocca il formato di output e delega a uno strumento di base come `convert`, `convert-video`, `extract-audio`, `convert-audio`, `image-to-pdf`, `pdf-to-image`, `svg-to-raster` o `convert-spreadsheet`. Vedi [Preset di conversione](/it/tools/conversion-presets) per la tabella completa delle route e le impostazioni facoltative.
+
+### Elementi essenziali {#essentials}
+
+| ID strumento | Nome | Impostazioni principali |
+|---------|------|-------------|
+| `resize` | Ridimensiona | `width`, `height`, `fit` (cover/contain/fill/inside/outside), `percentage`, `withoutEnlargement`, più 23 preset per i social media |
+| `crop` | Ritaglia | `left`, `top`, `width`, `height`, `unit` (px/percent) |
+| `rotate` | Ruota e capovolgi | `angle`, `horizontal` (bool), `vertical` (bool) |
+| `convert` | Converti | `format` (jpg/png/webp/avif/tiff/gif/heic/heif), `quality` |
+| `compress` | Comprimi | `mode` (quality/targetSize), `quality` (1–100), `targetSizeKb` |
+
+### Ottimizzazione {#optimization}
+
+| ID strumento | Nome | Impostazioni principali |
+|---------|------|-------------|
+| `optimize-for-web` | Ottimizza per il web | `format` (webp/jpeg/avif/png), `quality`, `maxWidth`, `maxHeight`, `progressive`, `stripMetadata` |
+| `strip-metadata` | Rimuovi metadati | - |
+| `edit-metadata` | Modifica metadati | `title`, `description`, `author`, `copyright`, `keywords`, `gps` (lat/lon), `dateTime` |
+| `bulk-rename` | Rinomina in blocco | `pattern` (supporta `{n}`, `{date}`, `{original}`), `startIndex`, `padding` |
+| `image-to-pdf` | Immagine in PDF | `pageSize` (A4/Letter/...), `orientation`, `margin`, `targetSize` ({value, unit}) |
+| `favicon` | Generatore di favicon | `padding`, `backgroundColor`, `borderRadius` - genera tutte le dimensioni standard |
+
+### Regolazioni {#adjustments}
+
+| ID strumento | Nome | Impostazioni principali |
+|---------|------|-------------|
+| `adjust-colors` | Regola i colori | `brightness`, `contrast`, `exposure`, `saturation`, `temperature`, `tint`, `hue`, `sharpness`, `red`, `green`, `blue`, `effect` (none/grayscale/sepia/invert) |
+| `sharpening` | Nitidezza | `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` | Sostituisci colore | `sourceColor`, `targetColor` (sostituzione), `makeTransparent`, `tolerance` |
+| `color-blindness` | Simulazione del daltonismo | `simulationType` (protanopia/deuteranopia/tritanopia/protanomaly/deuteranomaly/tritanomaly/achromatopsia/blueConeMonochromacy, predefinito "deuteranomaly") |
+| `duotone` | Duotone | `shadow` (hex), `highlight` (hex), `intensity` (0-100) |
+| `pixelate` | Pixelizza | `blockSize` (2-128), `region` ({left, top, width, height} per la pixelizzazione parziale) |
+| `vignette` | Vignettatura | `strength` (0.1-1), `color` (hex), `radius`, `softness`, `roundness`, `centerX`, `centerY` |
+
+### Strumenti AI {#ai-tools}
+
+Tutti gli strumenti AI vengono eseguiti sul tuo hardware: CPU per impostazione predefinita, oppure NVIDIA CUDA quando è disponibile una GPU NVIDIA supportata. L'accelerazione tramite iGPU Intel/AMD attraverso VA-API, Quick Sync o OpenCL non è attualmente supportata per l'inferenza AI. Nessuna connessione a internet richiesta.
+
+| ID strumento | Nome | Modello AI | Impostazioni principali |
+|---------|------|---------|-------------|
+| `remove-background` | Rimuovi sfondo | rembg (BiRefNet / U2-Net) | `model`, `backgroundType` (transparent/color/gradient/blur/image), `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurEnabled`, `blurIntensity`, `shadowEnabled`, `shadowOpacity` |
+| `upscale` | Upscaling immagini | RealESRGAN | `scale` (2/4), `model`, `faceEnhance`, `denoise`, `format`, `quality` |
+| `erase-object` | Gomma per oggetti | LaMa (ONNX) | Maschera inviata come secondo file part (fieldname `mask`), `format`, `quality` |
+| `ocr` | OCR / Estrazione del testo | PaddleOCR / Tesseract | `quality` (fast/balanced/best), `language`, `enhance` |
+| `blur-faces` | Sfocatura volti / PII | MediaPipe | `blurRadius`, `sensitivity` |
+| `smart-crop` | Ritaglio intelligente | 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` | Miglioramento immagini | Basato sull'analisi | `mode` (auto/exposure/contrast/color/sharpness), `strength` |
+| `enhance-faces` | Miglioramento volti | GFPGAN / CodeFormer | `model` (gfpgan/codeformer), `strength`, `sensitivity`, `centerFace` |
+| `colorize` | Colorizzazione AI | DDColor | `intensity`, `model` |
+| `noise-removal` | Rimozione del rumore | Riduzione del rumore a livelli | `tier` (quick/balanced/quality/maximum), `strength`, `detailPreservation`, `colorNoise`, `format`, `quality` |
+| `red-eye-removal` | Rimozione occhi rossi | Punti di riferimento del volto + analisi del colore | `sensitivity`, `strength` |
+| `restore-photo` | Restauro foto | Pipeline multi-fase | `mode` (auto/light/heavy), `scratchRemoval`, `faceEnhancement`, `fidelity`, `denoise`, `denoiseStrength`, `colorize` |
+| `passport-photo` | Foto tessera | Punti di riferimento MediaPipe | Flusso in due fasi. L'analisi usa multipart `file`; la generazione usa JSON con `countryCode`, `bgColor`, `printLayout` (none/4x6/a4), punti di riferimento, dimensioni dell'immagine |
+| `content-aware-resize` | Ridimensionamento sensibile al contenuto | Seam carving (caire) | `width`, `height`, `protectFaces`, `blurRadius`, `sobelThreshold`, `square` |
+| `transparency-fixer` | Correttore di trasparenza PNG | BiRefNet HR-matting | `defringe` (0-100), `outputFormat` (png/webp) |
+| `background-replace` | Sostituzione sfondo | rembg (BiRefNet) | `backgroundType` (color/gradient), `color` (hex), `gradientColor1`, `gradientColor2`, `gradientAngle`, `feather` (0-20), `format` (png/webp) |
+| `blur-background` | Sfoca sfondo | rembg (BiRefNet) | `intensity` (1-100), `feather` (0-20), `format` (png/webp) |
+| `ai-canvas-expand` | Espansione tela AI | LaMa (outpainting) | `extendTop`, `extendRight`, `extendBottom`, `extendLeft` (px), `tier` (fast/balanced/high), `format`, `quality` |
+
+### Filigrana e sovrapposizione {#watermark-overlay}
+
+| ID strumento | Nome | Impostazioni principali |
+|---------|------|-------------|
+| `watermark-text` | Filigrana di testo | `text`, `font`, `fontSize`, `color`, `opacity`, `position`, `rotation`, `tile` |
+| `watermark-image` | Filigrana di immagine | `opacity`, `position`, `scale` - il secondo file è la filigrana |
+| `text-overlay` | Sovrapposizione di testo | `text`, `font`, `fontSize`, `color`, `x`, `y`, `background`, `padding`, `borderRadius` |
+| `compose` | Composizione di immagini | `x`, `y`, `opacity`, `blend` - il secondo file viene sovrapposto |
+| `meme-generator` | Generatore di meme | `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`. Supporta la modalità template (corpo JSON con `templateId`) o la modalità immagine personalizzata (multipart con file). |
+
+### Utilità {#utilities}
+
+| ID strumento | Nome | Impostazioni principali |
+|---------|------|-------------|
+| `info` | Info immagine | - (restituisce width, height, format, size, channels, hasAlpha, DPI, EXIF) |
+| `compare` | Confronta immagini | `mode` (side-by-side/overlay/diff), `diffThreshold` - il secondo file è la destinazione del confronto |
+| `find-duplicates` | Trova duplicati | `threshold` (distanza dell'hash percettivo, predefinito 8) - multi-file |
+| `color-palette` | Palette di colori | `count` (numero di colori dominanti), `format` (hex/rgb) |
+| `qr-generate` | Generatore di codici QR | `data`, `size`, `margin`, `colorDark`, `colorLight`, `errorCorrectionLevel`, `dotStyle`, `cornerStyle`, `logo` (file facoltativo) |
+| `barcode-read` | Lettore di codici a barre | - (rileva automaticamente QR, EAN, Code128, DataMatrix, ecc.) |
+| `image-to-base64` | Immagine in Base64 | `format` (data-uri/plain), `mimeType` |
+| `html-to-image` | HTML in immagine | `url`, `format` (png/jpg/webp), `quality`, `fullPage`, `devicePreset` (desktop/tablet/mobile/custom), `viewportWidth`, `viewportHeight` |
+| `histogram` | Istogramma | `scale` (linear/log) - restituisce il grafico dell'istogramma RGB + statistiche per canale |
+| `lqip-placeholder` | Segnaposto LQIP | `width` (4-64), `blur`, `strategy` (blur/pixelate/solid), `format` (webp/png/jpeg), `quality` |
+| `barcode-generate` | Generatore di codici a barre | `text`, `type` (code128/ean13/upca/code39/itf14/datamatrix), `scale` (1-8), `includeText` (bool). Corpo JSON, nessun caricamento di file. |
+
+### Layout e composizione {#layout-composition}
+
+| ID strumento | Nome | Impostazioni principali |
+|---------|------|-------------|
+| `collage` | Collage / Griglia | `template` (25+ layout), `gap`, `backgroundColor`, `borderRadius` - multi-file |
+| `stitch` | Unisci / Combina | `direction` (horizontal/vertical/grid), `gap`, `backgroundColor`, `alignment` - multi-file |
+| `split` | Divisione immagini | `mode` (grid/rows/cols), `rows`, `cols`, `tileWidth`, `tileHeight` |
+| `border` | Bordo e cornice | `width`, `color`, `style` (solid/gradient/pattern), `borderRadius`, `padding`, `shadow` |
+| `beautify` | Abbellisci screenshot | `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` | Ritaglio circolare | `zoom` (1-5), `offsetX`, `offsetY`, `borderWidth`, `borderColor`, `background` (transparent/hex), `outputSize` |
+| `image-pad` | Spaziatura immagine | `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` | Foglio sprite | `columns` (1-16), `padding`, `background` (hex), `format` (png/webp/jpeg), `quality` - multi-file (2-64 immagini) |
+
+### Formato e conversione {#format-conversion}
+
+| ID strumento | Nome | Impostazioni principali |
+|---------|------|-------------|
+| `svg-to-raster` | SVG in raster | `format` (png/jpeg/webp/avif/tiff/gif/heif), `width`, `height`, `scale`, `dpi`, `background` |
+| `vectorize` | Immagine in SVG | `colorMode` (bw/color), `threshold`, `colorPrecision`, `filterSpeckle`, `pathMode` (none/polygon/spline) |
+| `gif-tools` | Strumenti GIF | `action` (resize/optimize/reverse/speed/extract-frames/rotate/add-text), parametri specifici dell'azione |
+| `gif-webp` | Convertitore GIF/WebP | `quality` (1-100), `lossless` (bool), `resizePercent` (10-100) |
+
+### Strumenti video {#video-tools}
+
+| ID strumento | Nome | Impostazioni principali |
+|---------|------|-------------|
+| `convert-video` | Converti video | `format` (mp4/mov/webm/avi/mkv), `quality` (high/balanced/small) |
+| `compress-video` | Comprimi video | `quality` (light/balanced/strong), `resolution` (original/1080p/720p/480p) |
+| `trim-video` | Taglia video | `startS`, `endS`, `precise` (bool, taglio preciso al frame) |
+| `mute-video` | Silenzia video | - |
+| `video-to-gif` | Video in GIF | `fps` (1-30), `width`, `startS`, `durationS` (max 60s) |
+| `resize-video` | Ridimensiona video | `width`, `height`, `preset` (custom/2160p/1440p/1080p/720p/480p/360p) |
+| `crop-video` | Ritaglia video | `width`, `height`, `x`, `y` |
+| `rotate-video` | Ruota video | `transform` (cw90/ccw90/180/hflip/vflip) |
+| `change-fps` | Cambia FPS | `fps` (1-120) |
+| `video-color` | Colore video | `brightness`, `contrast`, `saturation`, `gamma` |
+| `video-speed` | Velocità video | `factor` (0.25-4), `keepPitch` (bool) |
+| `reverse-video` | Inverti video | - (max 5 minuti) |
+| `video-loudnorm` | Normalizza audio | - (EBU R128) |
+| `aspect-pad` | Spaziatura proporzioni | `target` (16:9/9:16/1:1/4:3/3:4), `color` (hex) |
+| `blur-pad` | Spaziatura sfocata | `target` (16:9/9:16/1:1/4:3/3:4), `blur` (2-50) |
+| `watermark-video` | Filigrana video | `text`, `position`, `fontSize`, `opacity`, `color` |
+| `stabilize-video` | Stabilizza video | `smoothing` (5-60, in frame) |
+| `gif-to-video` | GIF in video | `format` (mp4/webm/mov) |
+| `video-to-webp` | Video in WebP | `fps`, `width`, `quality`, `loop` (bool) |
+| `video-to-frames` | Video in frame | `mode` (all/nth/timestamps), `n`, `timestamps`, `format` (png/jpg) |
+| `merge-videos` | Unisci video | - (multi-file, normalizzato alla risoluzione del primo video) |
+| `replace-audio` | Sostituisci audio | - (file video + audio, due file) |
+| `burn-subtitles` | Incorpora sottotitoli | `fontSize` (8-72) - file video + sottotitoli |
+| `embed-subtitles` | Integra sottotitoli | `language` (codice ISO 639-2/B) - file video + sottotitoli |
+| `extract-subtitles` | Estrai sottotitoli | - (produce SRT) |
+| `images-to-video` | Immagini in video | `secondsPerImage` (0.5-10), `resolution` (1080p/720p/square), `fps` - multi-file |
+| `video-metadata` | Pulisci metadati video | - |
+| `auto-subtitles` | Sottotitoli automatici (AI) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `format` (srt/vtt) |
+| `extract-audio` | Estrai audio | `format` (mp3/wav/m4a/ogg) |
+
+### Strumenti audio {#audio-tools}
+
+| ID strumento | Nome | Impostazioni principali |
+|---------|------|-------------|
+| `convert-audio` | Converti audio | `format` (mp3/wav/ogg/flac/m4a), `bitrateKbps` (32-320) |
+| `trim-audio` | Taglia audio | `startS`, `endS` |
+| `volume-adjust` | Regola volume | `gainDb` (-30 a 30) |
+| `normalize-audio` | Normalizza audio | - (EBU R128, -16 LUFS) |
+| `fade-audio` | Dissolvenza audio | `fadeInS` (0-30), `fadeOutS` (0-30) |
+| `reverse-audio` | Inverti audio | - |
+| `audio-speed` | Velocità audio | `factor` (0.25-4) |
+| `pitch-shift` | Cambio di tonalità | `semitones` (-12 a 12) |
+| `audio-channels` | Canali audio | `mode` (stereo-to-mono/mono-to-stereo/swap) |
+| `silence-removal` | Rimozione del silenzio | `thresholdDb` (-80 a -20), `minSilenceS` (0.1-5) |
+| `noise-reduction` | Riduzione del rumore | `strength` (light/medium/strong) |
+| `merge-audio` | Unisci audio | `format` (mp3/wav/flac/m4a) - multi-file |
+| `split-audio` | Dividi audio | `mode` (time/parts/silence), `segmentS`, `parts`, `thresholdDb`, `minSilenceS` |
+| `ringtone-maker` | Creatore di suonerie | `startS`, `durationS` (1-30) |
+| `waveform-image` | Immagine della forma d'onda | `width`, `height`, `color` (hex) |
+| `audio-metadata` | Metadati audio | `strip` (bool), `title`, `artist`, `album` |
+| `transcribe-audio` | Trascrivi audio (AI) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `outputFormat` (txt/srt/vtt) |
+
+### Strumenti per documenti {#document-tools}
+
+| ID strumento | Nome | Impostazioni principali |
+|---------|------|-------------|
+| `merge-pdf` | Unisci PDF | - (multi-file, fino a 20 PDF) |
+| `split-pdf` | Dividi PDF | `mode` (range/every), `range`, `everyN` (1-500) |
+| `compress-pdf` | Comprimi PDF | `mode` (quality/targetSize), `quality` (1-100), `targetSizeKb` |
+| `rotate-pdf` | Ruota PDF | `angle` (90/180/270), `range` (intervallo di pagine) |
+| `extract-pages` | Estrai pagine | `range` (sintassi qpdf, es. "1-5,8,10-z") |
+| `remove-pages` | Rimuovi pagine | `pages` (intervallo qpdf da rimuovere) |
+| `organize-pdf` | Organizza PDF | `order` (ordine delle pagine qpdf, es. "3,1,2,5-z") |
+| `protect-pdf` | Proteggi PDF | `userPassword`, `ownerPassword` (AES-256) |
+| `unlock-pdf` | Sblocca PDF | `password` |
+| `repair-pdf` | Ripara PDF | - |
+| `linearize-pdf` | Ottimizza PDF per il web | - (linearizza per una visualizzazione web veloce) |
+| `grayscale-pdf` | PDF in scala di grigi | - |
+| `pdfa-convert` | Converti in PDF/A | - (PDF/A-2 di archiviazione) |
+| `crop-pdf` | Ritaglia PDF | `margin` (0-2000 punti) |
+| `nup-pdf` | PDF N-up | `perSheet` (2/3/4/8/9/12/16) |
+| `booklet-pdf` | PDF opuscolo | `perSheet` (2/4/6/8) |
+| `watermark-pdf` | Filigrana PDF | `text`, `position`, `fontSize`, `opacity`, `rotation` |
+| `pdf-page-numbers` | Numeri di pagina PDF | `position` (bl/bc/br/tl/tc/tr), `fontSize` |
+| `flatten-pdf` | Appiattisci PDF | - (integra moduli e annotazioni) |
+| `redact-pdf` | Oscura PDF | `terms` (string[]), `caseSensitive` (bool) |
+| `sign-pdf` | Firma PDF | Route multipart personalizzata con PDF `file`, file di firma `sig0`, `sig1` e array JSON `placements` |
+| `pdf-to-text` | PDF in testo | - |
+| `pdf-to-word` | PDF in Word | - |
+| `pdf-metadata` | Metadati PDF | `title`, `author`, `subject`, `keywords` |
+| `convert-document` | Converti documento | `format` (docx/odt/rtf/txt) |
+| `convert-presentation` | Converti presentazione | `format` (pptx/odp) |
+| `convert-spreadsheet` | Converti foglio di calcolo | `format` (xlsx/ods/csv) |
+| `excel-to-pdf` | Excel in PDF | - |
+| `word-to-pdf` | Word in PDF | - |
+| `powerpoint-to-pdf` | PowerPoint in PDF | - |
+| `html-to-pdf` | HTML in PDF | - (risorse remote disabilitate) |
+| `markdown-to-docx` | Markdown in Word | - |
+| `markdown-to-html` | Markdown in HTML | - |
+| `markdown-to-pdf` | Markdown in PDF | - (risorse remote disabilitate) |
+| `epub-convert` | Converti EPUB | `format` (pdf/docx/html/md) |
+| `to-epub` | Converti in EPUB | - (accetta .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 in immagine | `pages` (all/range), `format`, `dpi`, `quality` |
+| `pdf-to-jpg` | PDF in JPG | `pages`, `dpi`, `quality`, `colorMode` |
+| `pdf-to-png` | PDF in PNG | `pages`, `dpi`, `quality`, `colorMode` |
+| `pdf-to-tiff` | PDF in TIFF | `pages`, `dpi`, `quality`, `colorMode` |
+
+### Strumenti per file {#file-tools}
+
+| ID strumento | Nome | Impostazioni principali |
+|---------|------|-------------|
+| `chart-maker` | Creatore di grafici | `kind` (bar/line/pie), `title`, `width`, `height` |
+| `csv-excel` | CSV in Excel | `sheet` (numero del foglio di lavoro per l'input XLSX) - bidirezionale |
+| `csv-json` | CSV in JSON | `pretty` (bool) - bidirezionale |
+| `json-xml` | JSON in XML | `pretty` (bool) - bidirezionale |
+| `split-csv` | Dividi CSV | `rowsPerFile` (1-1000000), `keepHeader` (bool) |
+| `merge-csvs` | Unisci CSV | - (multi-file, colonne corrispondenti) |
+| `yaml-json` | YAML / JSON | - (bidirezionale) |
+| `xml-to-csv` | XML in CSV | - (individua automaticamente gli elementi ripetuti) |
+| `excel-to-csv` | Excel in CSV | preset di conversione dedicato supportato da `convert-spreadsheet` |
+| `create-zip` | Crea ZIP | - (multi-file, 2-50 file) |
+| `extract-zip` | Estrai ZIP | - (protetto da zip bomb) |
+
+### HTML in immagine {#html-to-image}
+
+Cattura una pagina web come immagine. A differenza degli altri strumenti, questo endpoint accetta `application/json` invece dei dati del modulo multipart (nessun caricamento di file necessario).
+
+**Endpoint:** `POST /api/v1/tools/image/html-to-image`
+
+**Content-Type:** `application/json`
+
+| Parametro | Tipo | Predefinito | Descrizione |
+|-----------|------|---------|-------------|
+| `url` | string | (obbligatorio) | URL da catturare (solo http/https) |
+| `format` | string | `"png"` | Formato di output: `jpg`, `png`, `webp` |
+| `quality` | number | `90` | Qualità 1-100 (solo JPG/WebP) |
+| `fullPage` | boolean | `false` | Cattura l'intera pagina scorrevole |
+| `devicePreset` | string | `"desktop"` | `desktop`, `tablet`, `mobile`, `custom` |
+| `viewportWidth` | number | `1280` | Larghezza personalizzata del viewport 320-3840 |
+| `viewportHeight` | number | `720` | Altezza personalizzata del viewport 320-2160 |
+
+**Esempio:**
+
+```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"}'
+```
+
+**Risposta:**
+
+```json
+{
+  "jobId": "uuid",
+  "downloadUrl": "/api/v1/download/{jobId}/screenshot.png",
+  "originalSize": 0,
+  "processedSize": 54321
+}
+```
+
+### Sotto-route degli strumenti {#tool-sub-routes}
+
+Alcuni strumenti espongono endpoint aggiuntivi oltre alla `POST /api/v1/tools/<section>/<toolId>` standard:
+
+| Metodo | Percorso | Descrizione |
+|--------|------|-------------|
+| `GET` | `/api/v1/tools/popular` | Restituisce gli ID degli strumenti più popolari, ricorrendo a un elenco predefinito curato quando i dati di utilizzo sono scarsi |
+| `POST` | `/api/v1/tools/image/remove-background/effects` | Applica effetti di sfondo (color/gradient/blur/shadow) senza rieseguire l'AI. Usa la maschera memorizzata nella cache dalla rimozione iniziale. |
+| `POST` | `/api/v1/tools/image/edit-metadata/inspect` | Legge i metadati EXIF/IPTC/XMP esistenti da un'immagine |
+| `POST` | `/api/v1/tools/image/strip-metadata/inspect` | Ispeziona i campi dei metadati prima della rimozione |
+| `POST` | `/api/v1/tools/image/passport-photo/analyze` | Fase 1: rilevamento AI del volto + rimozione dello sfondo. Restituisce i punti di riferimento del volto e i dati memorizzati nella cache. |
+| `POST` | `/api/v1/tools/image/passport-photo/generate` | Fase 2: ritaglio, ridimensionamento e affiancamento usando l'analisi memorizzata nella cache. Nessuna riesecuzione dell'AI. |
+| `POST` | `/api/v1/tools/image/gif-tools/info` | Ottiene i metadati della GIF (numero di frame, dimensioni, durata) |
+| `POST` | `/api/v1/tools/pdf/pdf-to-image/info` | Ottiene i metadati del PDF (numero di pagine, dimensioni) |
+| `POST` | `/api/v1/tools/pdf/pdf-to-image/preview` | Genera un'anteprima di una pagina PDF specifica |
+| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/info` | Ottiene i metadati del PDF per il preset JPG dedicato |
+| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/preview` | Genera un'anteprima di una pagina PDF con preset JPG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-png/info` | Ottiene i metadati del PDF per il preset PNG dedicato |
+| `POST` | `/api/v1/tools/pdf/pdf-to-png/preview` | Genera un'anteprima di una pagina PDF con preset PNG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/info` | Ottiene i metadati del PDF per il preset TIFF dedicato |
+| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/preview` | Genera un'anteprima di una pagina PDF con preset TIFF |
+| `POST` | `/api/v1/tools/image/svg-to-raster/batch` | Converte in batch più SVG in raster |
+| `POST` | `/api/v1/tools/image/image-enhancement/analyze` | Analizza la qualità dell'immagine e restituisce raccomandazioni di miglioramento |
+| `POST` | `/api/v1/tools/image/optimize-for-web/preview` | Anteprima leggera per la regolazione dei parametri in tempo reale. Restituisce l'immagine ottimizzata con gli header delle dimensioni. |
+
+## Elaborazione batch {#batch-processing}
+
+Applica uno strumento generico abilitato al batch a più file contemporaneamente. Restituisce un archivio ZIP. Le route personalizzate multi-file o multi-fase, come la firma dei PDF, l'OCR dei PDF e le route dei preset da PDF a immagine, usano il proprio contratto di endpoint invece della route generica `/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}'
+```
+
+La concorrenza è controllata da `CONCURRENT_JOBS` (predefinito: rilevato automaticamente dai core della CPU). `MAX_BATCH_SIZE` limita il numero di file per batch (predefinito: 100; imposta 0 per illimitato).
+
+## Pipeline {#pipelines}
+
+### Esegui una pipeline {#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}}]}'
+```
+
+L'output di ogni fase è l'input della fase successiva. Le pipeline consentono 20 fasi per impostazione predefinita, configurabili tramite `MAX_PIPELINE_STEPS`. Imposta `MAX_PIPELINE_STEPS=0` per rimuovere il limite.
+
+### Salva e gestisci le pipeline {#save-and-manage-pipelines}
+
+| Metodo | Percorso | Descrizione |
+|--------|------|-------------|
+| `POST` | `/api/v1/pipeline/save` | Salva una pipeline con nome (`name`, `description`, `steps[]`) |
+| `GET` | `/api/v1/pipeline/list` | Elenca le pipeline salvate (gli amministratori vedono tutte; gli utenti vedono le proprie) |
+| `DELETE` | `/api/v1/pipeline/:id` | Elimina (proprietario o amministratore) |
+| `GET` | `/api/v1/pipeline/tools` | Elenca gli ID degli strumenti validi per le fasi della pipeline |
+
+## Tracciamento dell'avanzamento {#progress-tracking}
+
+I job di lunga durata, gli strumenti in coda, i job batch e le pipeline emettono l'avanzamento in tempo reale tramite Server-Sent Events. Lo stream di avanzamento è pubblico e indicizzato per ID del job, quindi i client non devono inviare un header Authorization per leggerlo.
+
+```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
+```
+
+Formato dell'evento:
+```
+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":[]}
+```
+
+Puoi richiedere l'annullamento di un job in coda o in esecuzione con `POST /api/v1/jobs/:jobId/cancel`. La risposta è `{"canceled":true|false}`.
+
+## Libreria file {#file-library}
+
+Archiviazione persistente dei file con cronologia delle versioni.
+
+| Metodo | Percorso | Descrizione |
+|--------|------|-------------|
+| `POST` | `/api/v1/upload` | Carica i file nello spazio di lavoro (elaborazione temporanea) |
+| `POST` | `/api/v1/files/upload` | Carica i file nella libreria file persistente |
+| `POST` | `/api/v1/files/save-result` | Salva il risultato dell'elaborazione di uno strumento come nuova versione del file |
+| `GET` | `/api/v1/files` | Elenca i file salvati (paginato, con ricerca) |
+| `GET` | `/api/v1/files/:id` | Ottiene i metadati del file + la catena delle versioni |
+| `GET` | `/api/v1/files/:id/download` | Scarica il file |
+| `GET` | `/api/v1/files/:id/thumbnail` | Ottiene una miniatura JPEG da 300px |
+| `DELETE` | `/api/v1/files` | Elimina in blocco i file e le loro catene di versioni (corpo: `{ ids: [...] }`) |
+| `POST` | `/api/v1/fetch-urls` | Recupera URL remoti nello spazio di lavoro per importazioni basate su URL |
+| `POST` | `/api/v1/preview` | Genera un'anteprima WebP compatibile con il browser (per i formati HEIC/HEIF/RAW) |
+| `GET` | `/api/v1/files/:id/preview` | Trasmette in streaming un'anteprima compatibile con il browser, memorizzata nella cache o generata, per un file PDF, documento office, video o audio salvato |
+| `POST` | `/api/v1/preview/generate` | Genera un'anteprima MP4 o MP3 su richiesta per un file multimediale caricato senza salvarlo prima |
+| `GET` | `/api/v1/download/:jobId/:filename` | Scarica un file elaborato da uno spazio di lavoro |
+
+Per salvare automaticamente il risultato di uno strumento nella libreria, includi `fileId` come campo del modulo multipart che fa riferimento a un file esistente della libreria. Il risultato elaborato verrà salvato come nuova versione.
+
+## Gestione delle chiavi API {#api-key-management}
+
+| Metodo | Percorso | Accesso | Descrizione |
+|--------|------|--------|-------------|
+| `POST` | `/api/v1/api-keys` | Auth | Genera una nuova chiave - mostrata una sola volta |
+| `GET` | `/api/v1/api-keys` | Auth | Elenca le chiavi (name, id, lastUsedAt - non la chiave grezza) |
+| `DELETE` | `/api/v1/api-keys/:id` | Auth | Elimina la chiave |
+
+## Team {#teams}
+
+| Metodo | Percorso | Accesso | Descrizione |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/teams` | Admin (`teams:manage`) | Elenca i team |
+| `POST` | `/api/v1/teams` | Admin (`teams:manage`) | Crea un team |
+| `PUT` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Rinomina un team |
+| `DELETE` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Elimina un team (non è possibile eliminare il team predefinito o i team con membri) |
+
+## Impostazioni {#settings}
+
+Configurazione runtime a coppie chiave-valore (letta da qualsiasi utente autenticato, scritta solo dagli amministratori).
+
+| Metodo | Percorso | Descrizione |
+|--------|------|-------------|
+| `GET` | `/api/v1/settings` | Ottiene tutte le impostazioni |
+| `PUT` | `/api/v1/settings` | Aggiorna in blocco le impostazioni (corpo JSON con coppie chiave-valore) |
+| `GET` | `/api/v1/settings/:key` | Ottiene un'impostazione specifica per chiave |
+
+Chiavi note: `disabledTools` (array JSON di ID degli strumenti), `enableExperimentalTools` (stringa bool), `loginAttemptLimit` (numero).
+
+## Preferenze {#preferences}
+
+Le preferenze per utente sono separate dalle impostazioni dell'istanza. Qualsiasi utente autenticato può leggere e aggiornare la propria mappa di preferenze.
+
+| Metodo | Percorso | Descrizione |
+|--------|------|-------------|
+| `GET` | `/api/v1/preferences` | Ottiene le preferenze dell'utente corrente come `{ "preferences": { ... } }` |
+| `PUT` | `/api/v1/preferences` | Inserisce o aggiorna una o più chiavi di preferenza per l'utente corrente |
+
+## Ruoli {#roles}
+
+Gestione dei ruoli personalizzati con permessi granulari.
+
+| Metodo | Percorso | Accesso | Descrizione |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/roles` | Admin (`audit:read`) | Elenca tutti i ruoli con il conteggio degli utenti |
+| `POST` | `/api/v1/roles` | Admin (`security:manage`) | Crea un ruolo personalizzato (`name`, `description`, `permissions`) |
+| `PUT` | `/api/v1/roles/:id` | Admin (`security:manage`) | Aggiorna un ruolo personalizzato (non è possibile modificare i ruoli integrati) |
+| `DELETE` | `/api/v1/roles/:id` | Admin (`security:manage`) | Elimina un ruolo personalizzato (non è possibile eliminare i ruoli integrati; gli utenti interessati tornano al ruolo `user`) |
+
+Permessi disponibili (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`.
+
+## Registro di controllo {#audit-log}
+
+Endpoint riservato agli amministratori per esaminare le azioni rilevanti per la sicurezza.
+
+| Metodo | Percorso | Accesso | Descrizione |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/audit-log` | Admin (`audit:read`) | Registro di controllo paginato con filtri facoltativi |
+
+Parametri della query:
+
+| Parametro | Descrizione |
+|-----------|-------------|
+| `page` | Numero di pagina (predefinito: 1) |
+| `limit` | Voci per pagina (predefinito: 50, max: 100) |
+| `action` | Filtra per tipo di azione (es. `ROLE_CREATED`, `ROLE_DELETED`) |
+| `ip` | Filtra per indirizzo IP di origine |
+| `from` | Filtra le voci dopo questa data ISO 8601 |
+| `to` | Filtra le voci prima di questa data ISO 8601 |
+
+## Analytics {#analytics}
+
+| Metodo | Percorso | Accesso | Descrizione |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/config/analytics` | Pubblico | Ottiene la configurazione analytics effettiva (chiave PostHog, DSN Sentry, sample rate). Le chiavi, il DSN e l'ID dell'istanza sono vuoti quando gli analytics sono disattivati, sia dal bake in fase di compilazione sia dall'impostazione dell'istanza `analyticsEnabled`. |
+| `POST` | `/api/v1/feedback` | Auth | Invia un feedback utente esplicito al progetto PostHog configurato come `feedback_submitted`. La route rispetta il gate degli analytics, limita la frequenza degli invii, rimuove i campi di contatto a meno che `contactOk` non sia true e non accetta mai contenuti di file, nomi di file, percorsi di caricamento o testo grezzo di errori privati. Quando gli analytics sono disabilitati, restituisce `{ "ok": true, "accepted": false }`. |
+| `PUT` | `/api/v1/settings` | Admin (`settings:write`) | Imposta l'opt-out a livello di istanza. Invia un corpo JSON `{ "analyticsEnabled": "false" }` per disattivare gli analytics per tutti, oppure `"true"` per riattivarli. |
+
+## Funzionalità / Bundle AI {#features-ai-bundles}
+
+Gestisci i bundle delle funzionalità AI (installa/disinstalla i pacchetti dei modelli AI nell'ambiente Docker). Preferisci l'endpoint di installazione a livello di strumento quando abiliti uno strumento da un'automazione personalizzata: alcuni strumenti AI necessitano di più di un bundle condiviso, e questo endpoint salta i bundle già installati mettendo in coda solo quelli mancanti.
+
+| Metodo | Percorso | Accesso | Descrizione |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/features` | Auth | Elenca tutti i bundle delle funzionalità e il loro stato di installazione |
+| `POST` | `/api/v1/admin/features/:bundleId/install` | Admin (`features:manage`) | Installa un bundle di funzionalità (asincrono, restituisce `jobId` per il tracciamento dell'avanzamento) |
+| `POST` | `/api/v1/admin/tools/:toolId/features/install` | Admin (`features:manage`) | Installa ogni bundle richiesto da uno strumento; restituisce lo stato per bundle in coda/saltato |
+| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Admin (`features:manage`) | Disinstalla un bundle di funzionalità e pulisce i file dei modelli |
+| `GET` | `/api/v1/admin/features/disk-usage` | Admin (`features:manage`) | Ottiene l'utilizzo totale del disco dei modelli AI |
+| `POST` | `/api/v1/admin/features/import` | Admin (`features:manage`) | Importa un archivio di bundle AI offline |
+
+## Operazioni di amministrazione {#admin-operations}
+
+Endpoint operativi per l'osservabilità, il supporto, la reportistica sull'utilizzo e lo stato dei backup.
+
+| Metodo | Percorso | Accesso | Descrizione |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/admin/log-level` | Admin (`settings:write`) | Legge il livello di log runtime corrente |
+| `POST` | `/api/v1/admin/log-level` | Admin (`settings:write`) | Cambia il livello di log runtime (`fatal`, `error`, `warn`, `info`, `debug`, `trace` o `silent`) |
+| `GET` | `/api/v1/metrics` | Admin (`system:health`) | Metriche Prometheus in formato testo |
+| `GET` | `/api/v1/admin/support-bundle` | Admin (`system:health`) | Scarica un bundle ZIP di supporto diagnostico oscurato |
+| `GET` | `/api/v1/admin/usage` | Admin (`audit:read`) | Dati della dashboard di utilizzo, con parametro della query `days` facoltativo |
+| `GET` | `/api/v1/admin/backup-status` | Admin (`system:health`) | Legge i metadati dell'ultimo backup e lo stato di freschezza |
+| `POST` | `/api/v1/admin/backup-status` | Admin (`system:health`) | Registra un backup completato (`type`, `sizeBytes` facoltativo, `notes` facoltativo) |
+
+## API Enterprise {#enterprise-apis}
+
+Queste route sono soggette a licenza in base alla loro funzionalità enterprise correlata. Richiedono comunque il permesso SnapOtter elencato.
+
+| Metodo | Percorso | Accesso | Descrizione |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/enterprise/audit/export` | Admin (`audit:read`) | Esporta le voci del registro di controllo come JSON o CSV con filtri |
+| `GET` | `/api/v1/enterprise/config/export` | Admin (`system:health`) | Esporta la configurazione dell'istanza oscurata, i ruoli personalizzati e i team |
+| `POST` | `/api/v1/enterprise/config/import` | Admin (`system:health`) | Importa la configurazione, con esecuzione a vuoto facoltativa |
+| `GET` | `/api/v1/enterprise/ip-allowlist` | Admin (`security:manage`) | Legge l'allowlist CIDR configurata |
+| `PUT` | `/api/v1/enterprise/ip-allowlist` | Admin (`security:manage`) | Aggiorna l'allowlist CIDR con prevenzione dell'autoesclusione |
+| `GET` | `/api/v1/enterprise/legal-hold` | Admin (`compliance:manage`) | Elenca i blocchi legali di utenti e team |
+| `PUT` | `/api/v1/enterprise/legal-hold` | Admin (`compliance:manage`) | Applica o rilascia un blocco legale su un utente o un team |
+| `POST` | `/api/v1/enterprise/scim/token` | Admin (`users:manage`) | Genera un token bearer SCIM, restituito una sola volta |
+| `DELETE` | `/api/v1/enterprise/scim/token` | Admin (`users:manage`) | Revoca il token bearer SCIM corrente |
+| `GET` | `/api/v1/enterprise/siem/config` | Admin (`webhooks:manage`) | Legge la configurazione dell'inoltro SIEM |
+| `PUT` | `/api/v1/enterprise/siem/config` | Admin (`webhooks:manage`) | Aggiorna la configurazione dell'inoltro SIEM |
+| `GET` | `/api/v1/enterprise/webhooks` | Admin (`webhooks:manage`) | Elenca le destinazioni dei webhook |
+| `POST` | `/api/v1/enterprise/webhooks` | Admin (`webhooks:manage`) | Crea una destinazione webhook |
+| `PUT` | `/api/v1/enterprise/webhooks/:index` | Admin (`webhooks:manage`) | Aggiorna una destinazione webhook |
+| `DELETE` | `/api/v1/enterprise/webhooks/:index` | Admin (`webhooks:manage`) | Elimina una destinazione webhook |
+| `POST` | `/api/v1/enterprise/webhooks/:index/test` | Admin (`webhooks:manage`) | Invia un payload webhook di prova |
+| `POST` | `/api/v1/enterprise/users/:id/export` | Admin (`compliance:manage`) | Avvia un job di esportazione utente GDPR |
+| `GET` | `/api/v1/enterprise/users/:id/export/:jobId` | Admin (`compliance:manage`) | Legge lo stato dell'esportazione GDPR e l'URL di download |
+| `DELETE` | `/api/v1/enterprise/users/:id/purge` | Admin (`compliance:manage`) | Elimina definitivamente i dati di un utente dopo conferma |
+| `DELETE` | `/api/v1/enterprise/teams/:id/purge` | Admin (`compliance:manage`) | Elimina definitivamente i dati di un team dopo conferma |
+| `GET` | `/api/v1/admin/version` | Admin (`system:health`) | Legge i metadati di versione dell'app, della build, di Node e dello schema |
+| `GET` | `/api/v1/admin/migrations/pending` | Admin (`system:health`) | Confronta le migrazioni impacchettate con quelle applicate |
+| `GET` | `/api/v1/admin/upgrade-check` | Admin (`system:health`) | Esegue i controlli di prontezza all'aggiornamento |
+
+### SCIM 2.0 {#scim-2-0}
+
+Gli endpoint di discovery SCIM sono pubblici. Gli endpoint di utenti e gruppi richiedono il token bearer SCIM generato sopra.
+
+| Metodo | Percorso | Accesso | Descrizione |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/scim/v2/ServiceProviderConfig` | Pubblico | Capacità del server SCIM |
+| `GET` | `/api/v1/scim/v2/Schemas` | Pubblico | Discovery dello schema SCIM |
+| `GET` | `/api/v1/scim/v2/ResourceTypes` | Pubblico | Discovery del tipo di risorsa SCIM |
+| `GET` | `/api/v1/scim/v2/Users` | Token SCIM | Elenca gli utenti, con filtro SCIM facoltativo |
+| `POST` | `/api/v1/scim/v2/Users` | Token SCIM | Crea un utente |
+| `GET` | `/api/v1/scim/v2/Users/:id` | Token SCIM | Ottiene un utente |
+| `PUT` | `/api/v1/scim/v2/Users/:id` | Token SCIM | Sostituisce un utente |
+| `DELETE` | `/api/v1/scim/v2/Users/:id` | Token SCIM | Disattiva in modo soft un utente |
+| `GET` | `/api/v1/scim/v2/Groups` | Token SCIM | Elenca i team come gruppi SCIM |
+| `POST` | `/api/v1/scim/v2/Groups` | Token SCIM | Crea un team |
+| `GET` | `/api/v1/scim/v2/Groups/:id` | Token SCIM | Ottiene un team |
+| `PUT` | `/api/v1/scim/v2/Groups/:id` | Token SCIM | Sostituisce un team e l'appartenenza al gruppo |
+| `DELETE` | `/api/v1/scim/v2/Groups/:id` | Token SCIM | Elimina un team |
+
+## Template dei meme {#meme-templates}
+
+API di supporto per lo strumento generatore di meme.
+
+| Metodo | Percorso | Accesso | Descrizione |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/meme-templates` | Auth | Elenca tutti i template di meme disponibili con le posizioni delle caselle di testo |
+| `GET` | `/api/v1/meme-templates/full/:filename` | Auth | Serve l'immagine del template a grandezza naturale |
+| `GET` | `/api/v1/meme-templates/thumbs/:filename` | Auth | Serve la miniatura del template |
+| `GET` | `/api/v1/meme-templates/fonts/:filename` | Auth | Serve il file del font usato per il rendering del testo del meme |
+
+## Risposte di errore {#error-responses}
+
+Tutti gli errori restituiscono JSON:
+
+```json
+{
+  "error": "Human-readable message",
+  "code": "MACHINE_READABLE_CODE"
+}
+```
+
+| Stato | Significato |
+|--------|---------|
+| 400 | Richiesta non valida / convalida fallita |
+| 401 | Non autenticato |
+| 403 | Permessi insufficienti |
+| 404 | Risorsa non trovata |
+| 413 | File troppo grande (vedi `MAX_UPLOAD_SIZE_MB`) |
+| 422 | Elaborazione fallita dopo la convalida |
+| 429 | Frequenza limitata (vedi `RATE_LIMIT_PER_MIN`) |
+| 501 | Il bundle della funzionalità AI richiesto non è installato (`FEATURE_NOT_INSTALLED`) |
+| 500 | Errore interno del server |