SnapOtter/apps/docs/it/api/ai.md

description, i18n_output_hash, i18n_source_hash, i18n_provenance

description	i18n_output_hash	i18n_source_hash	i18n_provenance
Riferimento del motore AI con tutti gli strumenti ML locali. Rimozione dello sfondo, upscaling, OCR, rilevamento dei volti, restauro fotografico e altro ancora.	7053b963a72f	aa9a56cdddc7	human

Riferimento del motore AI

Il pacchetto @snapotter/ai coordina gli strumenti nativi e i runtime Python per le operazioni ML locali. La maggior parte degli strumenti ML utilizzano un Python sidecar persistente per avviamenti a caldo rapidi. OCR è intenzionalmente separato: fast richiama il binario nativo Tesseract, mentre balanced e best utilizzano una JSONL dispatcher persistente dedicata fissata alla generazione RapidOCR immutabile attiva sotto /data/ai/v3. Ogni richiesta contiene un generation lease. Durante un aggiornamento, SnapOtter esegue un smoke test sul candidato prima dell'attivazione, passa atomicamente al nuovo dispatcher, quindi scarica la vecchia generazione prima di garbage collection.

NVIDIA CUDA viene rilevato automaticamente e utilizzato dai runtime che lo supportano. OCR utilizza CPU su ogni host, inclusi i sistemi con GPU NVIDIA, evitando CUDA e l'accoppiamento dei driver per questo strumento.

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.

::: info Compatibilità OCR per il coreano OCR veloce supporta auto, en, de, es, fr, zh e ja, ma non il coreano (ko). Il coreano richiede il pacchetto OCR accurato e balanced o best. Il pacchetto funziona nei container Linux amd64 e arm64 ufficiali, inclusi gli host NVIDIA, dove l’OCR resta sulla CPU. I sistemi non supportati ricevono un errore di compatibilità esplicito e non passano mai silenziosamente a fast. Il coreano con fast o con l’alias legacy tesseract viene rifiutato prima dell’accodamento con FEATURE_INCOMPATIBLE e fast-korean-unsupported. :::

Architettura

Node.js Tool Route
      |
      v
 @snapotter/ai bridge.ts
      | (stdin/stdout JSON + stderr progress events)
      v
 +-- Native Tesseract + Ghostscript (fast image/PDF OCR)
 |
 +-- Isolated OCR runtime (persistent JSONL dispatcher)
 |     `-- RapidOCR + ONNX Runtime CPU + pinned PP-OCR models
 |
 `-- Python dispatcher (persistent process, "ai" profile)
      |
      |-- remove_bg.py        (rembg / BiRefNet)
      |-- upscale.py          (RealESRGAN)
      |-- inpaint.py          (LaMa ONNX)
      |-- outpaint.py         (LaMa canvas expansion)
      |-- 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à

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.

La maggior parte degli strumenti di intelligenza artificiale richiedono uno o più pacchetti di funzionalità prima di poter essere eseguiti. L'interfaccia utente di amministrazione li installa tramite lo strumento tramite POST /api/v1/admin/tools/:toolId/features/install, che risolve l'elenco completo dei bundle, salta i bundle già installati e mette in coda solo i download mancanti. Ad esempio, abilitando Passport Photo su una nuova istanza si accodano background-removal e face-detection; abilitandolo dopo la rimozione dello sfondo è già installata solo la coda face-detection. OCR è l'eccezione perché fast non necessita di alcun pacchetto; installa il suo runtime accurato opzionale tramite l'interfaccia utente o POST /api/v1/admin/features/ocr/install.

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	~208-234 MiB scaricato / ~409-488 MiB installato	Modelli RapidOCR 3.9.1, ONNX Runtime 1.20.1 e PP-OCR bloccati opzionali	ocr, ocr-pdf (solo balanced e best)
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 sono installati tutti i bundle richiesti, ad eccezione di OCR: il livello fast integrato rimane disponibile senza il pacchetto OCR opzionale. Le installazioni parziali sono valide e vengono gestite in modo incrementale: i bundle installati vengono riutilizzati, i bundle mancanti vengono visualizzati come download e le installazioni in coda vengono eseguite una alla volta in modo che l'ambiente Python condiviso non venga modificato contemporaneamente.

Installazione runtime OCR accurata

Il pacchetto OCR accurato è un runtime specifico della piattaforma per il contenitore ufficiale Linux amd64 o Linux arm64. La build amd64 utilizza Python 3.12; la build arm64 utilizza Python 3.11. Entrambe le build eseguono RapidOCR tramite CPUExecutionProvider di ONNX Runtime, quindi lo stesso pacchetto funziona solo su host CPU e NVIDIA Docker. Il runtime accurato richiede almeno 4 GiB di memoria effettiva: il limite cgroup del contenitore configurato, altrimenti memoria host. Un sistema al di sotto del minimo di compatibilità firmato viene rifiutato prima del download. Questo requisito non si applica al modello Fast OCR integrato. Le build Bare-metal vengono rifiutate perché i relativi libc e Python ABI non possono essere dedotti in modo sicuro; OCR veloce rimane disponibile quando l'host fornisce Tesseract e Ghostscript.

L'artefatto opzionale è di circa 208-234 MiB compresso e 409-488 MiB estratto, a seconda dell'architettura. L'indice firmato associa l'esatto conteggio dei byte compressi ed estratti imposti dal programma di installazione. Tesseract integrato aggiunge circa 25 MiB all'immagine ufficiale e non necessita di file in /data/ai.

L'installazione online recupera un indice di rilascio firmato e l'esatto artefatto indirizzato al contenuto per la piattaforma corrente. SnapOtter verifica la firma dell'indice Ed25519, la dimensione dell'artefatto, il digest SHA-256, i digest del modello, i percorsi, le modalità file e lo smoke test messo in scena prima di attivare atomicamente la nuova generazione. Un'installazione non riuscita lascia attiva la precedente generazione integra.

Per l'installazione con air gap, caricare sia l'archivio runtime ocr-runtime-index.json della versione che l'archivio runtime OCR corrispondente su POST /api/v1/admin/features/import utilizzando campi multiparte denominati index e archive. L'importazione offline applica gli stessi controlli di firma, hash, estrazione, compatibilità e test del fumo dell'installazione online; un archivio senza il suo indice firmato attendibile viene rifiutato.

---

Rimozione dello sfondo

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

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

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

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

Route dello strumento: ocr
Modelli: Tesseract (fast); RapidOCR con modelli piccoli PP-OCRv6 (balanced); PP-OCRv6 modelli medi con punteggio variante calibrato (best)

Parametro	Tipo	Predefinito	Descrizione
quality	"fast" | "balanced" | "best"	Dinamico	Quando quality e engine sono omessi, SnapOtter sceglie il livello migliore disponibile nell’ordine best, balanced, fast. Per il coreano non sceglie mai fast: usa best, poi balanced, oppure restituisce l’errore di installazione o compatibilità del runtime accurato.
language	string	"auto"	Lingua: auto, en, de, fr, es, zh, ja, ko
enhance	booleano	Dipendente dal livello	Migliora il contrasto locale. Fast lo applica direttamente; i livelli accurati mantengono la variante solo quando il punteggio calibrato migliora OCR. L'impostazione predefinita è Migliore
engine	corda	-	Alias ​​di compatibilità deprecato. Mappa tesseract su fast e il valore paddleocr legacy su balanced; non carica PaddlePaddle

Restituisce il testo estratto più i metadati di provenienza: motore, qualità richiesta ed effettiva, dispositivo, provider, stato di degrado, avvisi e versioni runtime/modello accurate, ove applicabile. Le richieste esplicite di qualità non ricadono mai su un altro livello. Se balanced o best non è disponibile, API restituisce FEATURE_NOT_INSTALLED o FEATURE_INCOMPATIBLE invece di eseguire fast in modalità silenziosa.

OCR di PDF

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"	Dinamico	Quando quality e engine sono omessi, SnapOtter sceglie il livello migliore disponibile nell’ordine best, balanced, fast. Per il coreano non sceglie mai fast: usa best, poi balanced, oppure restituisce l’errore di installazione o compatibilità del runtime accurato.
language	string	"auto"	Lingua: auto, en, de, fr, es, zh, ja, ko
pages	string	"all"	Selezione delle pagine: "all", "1-3", "1,3,5"
enhance	booleano	Dipendente dal livello	Migliora il contrasto locale. Fast lo applica direttamente; i livelli accurati mantengono la variante solo quando il punteggio calibrato migliora OCR. L'impostazione predefinita è Migliore
engine	corda	-	Alias ​​di compatibilità deprecato. Mappa tesseract su fast e il valore paddleocr legacy su balanced; non carica PaddlePaddle

La stessa regola di non downgrade si applica a PDF OCR. Le pagine PDF vengono rasterizzate prima del riconoscimento e una richiesta può selezionare un massimo di 50 pagine.

Sfocatura di volti / PII

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

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

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

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

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

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

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

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

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)

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

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

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

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

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

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)

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

I seguenti strumenti non sono strumenti del sidecar Python ma usano funzionalità AI quando determinate opzioni sono abilitate.

Miglioramento delle immagini

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)

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