External/SnapOtter
1
0
Fork 0
mirror of https://github.com/snapotter-hq/SnapOtter.git synced 2026-08-03 07:46:42 +02:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
SnapOtter
2026-07-11 13:52:47 +08:00
committed by GitHub
parent 00b651c9f8
commit 4963ab3bbd
3620 changed files with 306134 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/fr/api/ai.md
+438
View File
@@ -0,0 +1,438 @@
---
description: "Référence du moteur d'IA avec tous les outils de ML locaux. Suppression d'arrière-plan, agrandissement, OCR, détection de visages, restauration de photos, et plus encore."
i18n_source_hash: 14728c1dcd05
i18n_provenance: machine
i18n_output_hash: b331443c08b8
---
# Référence du moteur d'IA {#ai-engine-reference}
Le paquet `@snapotter/ai` relie Node.js à un **sidecar Python persistant** pour toutes les opérations de ML. Le processus de répartition reste actif entre les requêtes pour des performances rapides à démarrage à chaud. NVIDIA CUDA est détecté automatiquement au démarrage et utilisé lorsqu'il est disponible ; sinon, les outils d'IA s'exécutent sur le CPU.
L'accélération par iGPU Intel/AMD via VA-API, Quick Sync ou OpenCL n'est pas prise en charge pour l'inférence d'IA aujourd'hui. Le mappage de `/dev/dri` dans un conteneur n'accélère pas ces outils du sidecar Python à moins qu'un GPU NVIDIA compatible CUDA ne soit disponible.
19 outils d'IA du sidecar Python répartis sur quatre modalités (image, audio, vidéo, document), plus 2 outils avec des capacités d'IA optionnelles. Tous les modèles s'exécutent localement : aucune connexion Internet requise après le téléchargement initial des modèles.
## Architecture {#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 profil de répartiteur « docs » distinct remplace la liste d'autorisation d'IA par des scripts de traitement de documents (`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`) et ignore les lourdes importations de ML.
**Délais d'expiration :** 300 s par défaut ; l'OCR et la suppression d'arrière-plan BiRefNet disposent de 600 s.
## Groupes de fonctionnalités {#feature-bundles}
Les modèles d'IA sont regroupés par pile de dépendances partagée, et non par une archive par outil. Un groupe de fonctionnalités peut activer plusieurs outils lorsqu'ils utilisent la même famille de modèles, les mêmes wheels Python ou les mêmes bibliothèques natives. Cela permet de réduire la taille de l'image Docker publiée et d'éviter de stocker des copies en double des mêmes modèles de détourage d'arrière-plan, de détection de visages, d'OCR, de restauration et de reconnaissance vocale.
L'image Docker contient l'application ainsi que l'environnement d'exécution commun. Les grandes archives de modèles sont téléchargées à la demande dans le volume persistant `/data/ai`, puis réutilisées par chaque outil qui en a besoin. Si un groupe est déjà installé parce qu'un autre outil en avait besoin, l'activation d'un nouvel outil dépendant ne télécharge pas ce groupe à nouveau.
Chaque outil d'IA nécessite un ou plusieurs groupes de fonctionnalités avant de pouvoir s'exécuter. L'interface d'administration installe par outil via `POST /api/v1/admin/tools/:toolId/features/install`, qui résout la liste complète des groupes, ignore les groupes déjà installés et met en file d'attente uniquement les téléchargements manquants. Par exemple, l'activation de Photo d'identité sur une instance neuve met en file d'attente `background-removal` et `face-detection` ; son activation après que la Suppression d'arrière-plan est déjà installée ne met en file d'attente que `face-detection`.
| Groupe | Taille | Groupe de dépendances partagé | Outils qui l'utilisent |
|--------|------|-------------------------|-------------------|
| `background-removal` | 4-5 Go | détourage d'arrière-plan rembg / BiRefNet | remove-background, passport-photo, transparency-fixer, background-replace, blur-background |
| `face-detection` | 200-300 Mo | détection de visages et points de repère MediaPipe | blur-faces, red-eye-removal, smart-crop |
| `object-eraser-colorize` | 1-2 Go | remplissage/extension par LaMa et DDColor | erase-object, colorize, ai-canvas-expand |
| `upscale-enhance` | 5-6 Go | RealESRGAN, GFPGAN / CodeFormer, débruitage | upscale, enhance-faces, noise-removal |
| `photo-restoration` | 4-5 Go | pipeline de réparation des rayures et de restauration | restore-photo |
| `ocr` | 5-6 Go | pile OCR PaddleOCR / Tesseract | ocr, ocr-pdf |
| `transcription` | ~600 Mo | modèles de reconnaissance vocale faster-whisper | transcribe-audio, auto-subtitles |
Outils avec des dépendances multi-groupes :
| Outil | Groupes requis | Pourquoi |
|------|------------------|-----|
| `passport-photo` | `background-removal`, `face-detection` | Supprime l'arrière-plan, puis utilise les points de repère du visage pour cadrer le recadrage selon les règles des photos de passeport et de pièce d'identité. |
| `enhance-faces` | `upscale-enhance`, `face-detection` | Détecte les visages avant d'exécuter l'amélioration GFPGAN ou CodeFormer sur les régions de visage sélectionnées. |
Un outil n'est disponible que lorsque tous ses groupes requis sont installés. Les installations partielles sont valides et sont gérées de manière incrémentale : les groupes installés sont réutilisés, les groupes manquants sont affichés en tant que téléchargements, et les installations en file d'attente s'exécutent une à la fois afin que l'environnement Python partagé ne soit pas modifié simultanément.
---
## Suppression d'arrière-plan {#background-removal}
**Route de l'outil :** `remove-background`
**Modèle :** rembg avec BiRefNet (par défaut) ou variantes U2-Net
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `model` | string | - | Variante du modèle (remplacement optionnel) |
| `backgroundType` | string | `"transparent"` | L'un de : `transparent`, `color`, `gradient`, `blur`, `image` |
| `backgroundColor` | string | - | Couleur hexadécimale pour un arrière-plan uni |
| `gradientColor1` | string | - | Première couleur du dégradé |
| `gradientColor2` | string | - | Deuxième couleur du dégradé |
| `gradientAngle` | number | - | Angle du dégradé en degrés |
| `blurEnabled` | boolean | - | Activer l'effet de flou d'arrière-plan |
| `blurIntensity` | number (0-100) | - | Intensité du flou |
| `shadowEnabled` | boolean | - | Activer l'ombre portée sur le sujet |
| `shadowOpacity` | number (0-100) | - | Opacité de l'ombre |
| `outputFormat` | string | - | Format de sortie : `png`, `webp`, ou `avif` |
| `edgeRefine` | integer (0-3) | - | Niveau d'affinement des bords |
| `decontaminate` | boolean | - | Supprimer le débordement de couleur sur les bords |
## Remplacement d'arrière-plan {#background-replace}
**Route de l'outil :** `background-replace`
**Modèle :** rembg / BiRefNet (partagé avec remove-background)
Supprime l'arrière-plan et le remplace par une couleur unie ou un dégradé.
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `backgroundType` | `"color"` \| `"gradient"` | `"color"` | Mode d'arrière-plan |
| `color` | string | `"#ffffff"` | Couleur hexadécimale de l'arrière-plan (lorsque `backgroundType` vaut `color`) |
| `gradientColor1` | string | - | Première couleur hexadécimale du dégradé |
| `gradientColor2` | string | - | Deuxième couleur hexadécimale du dégradé |
| `gradientAngle` | integer (0-360) | `180` | Angle du dégradé en degrés |
| `feather` | integer (0-20) | `0` | Rayon d'adoucissement des bords |
| `format` | `"png"` \| `"webp"` | `"png"` | Format de sortie |
## Flou d'arrière-plan {#blur-background}
**Route de l'outil :** `blur-background`
**Modèle :** rembg / BiRefNet (partagé avec remove-background)
Applique un flou à l'arrière-plan tout en gardant le sujet net.
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `intensity` | integer (1-100) | `50` | Intensité du flou |
| `feather` | integer (0-20) | `0` | Rayon d'adoucissement des bords |
| `format` | `"png"` \| `"webp"` | `"png"` | Format de sortie |
## Agrandissement d'image {#image-upscaling}
**Route de l'outil :** `upscale`
**Modèle :** RealESRGAN (avec repli Lanczos lorsqu'il est indisponible)
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `scale` | number | `2` | Facteur d'agrandissement |
| `model` | string | `"auto"` | Variante du modèle |
| `faceEnhance` | boolean | `false` | Appliquer une passe d'amélioration des visages GFPGAN |
| `denoise` | number | `0` | Force du débruitage |
| `format` | string | `"auto"` | Remplacement du format de sortie |
| `quality` | number | `95` | Qualité de sortie (1-100) |
## OCR / Extraction de texte {#ocr-text-extraction}
**Route de l'outil :** `ocr`
**Modèles :** Tesseract (rapide), PaddleOCR PP-OCRv5 (équilibré), PaddleOCR-VL 1.5 (meilleur)
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Niveau de traitement |
| `language` | string | `"auto"` | Langue : `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
| `enhance` | boolean | `true` | Prétraiter l'image pour améliorer la précision de l'OCR |
| `engine` | string | - | Déprécié. Fait correspondre `tesseract` à `fast`, `paddleocr` à `balanced` |
Renvoie des résultats structurés avec des cadres de délimitation, des scores de confiance et des blocs de texte extraits.
## OCR de PDF {#pdf-ocr}
**Route de l'outil :** `ocr-pdf`
**Modèles :** Même système de niveaux que l'OCR d'image
Extrait le texte de documents PDF numérisés à l'aide d'un OCR alimenté par IA, page par page.
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Niveau de traitement |
| `language` | string | `"auto"` | Langue : `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
| `pages` | string | `"all"` | Sélection de pages : `"all"`, `"1-3"`, `"1,3,5"` |
## Floutage de visages / PII {#face-pii-blur}
**Route de l'outil :** `blur-faces`
**Modèle :** détection de visages MediaPipe
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `blurRadius` | number (1-100) | `30` | Rayon du flou gaussien |
| `sensitivity` | number (0-1) | `0.5` | Seuil de confiance de détection |
## Amélioration des visages {#face-enhancement}
**Route de l'outil :** `enhance-faces`
**Modèles :** GFPGAN, CodeFormer
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `model` | `"auto"` \| `"gfpgan"` \| `"codeformer"` | `"auto"` | Modèle d'amélioration |
| `strength` | number (0-1) | `0.8` | Force de l'amélioration |
| `sensitivity` | number (0-1) | `0.5` | Seuil de détection de visages |
| `onlyCenterFace` | boolean | `false` | Améliorer uniquement le visage le plus central |
## Colorisation par IA {#ai-colorization}
**Route de l'outil :** `colorize`
**Modèle :** DDColor (avec repli OpenCV DNN)
Convertit les photos en noir et blanc ou en niveaux de gris en couleur.
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `intensity` | number (0-1) | `1.0` | Force de la saturation des couleurs |
| `model` | `"auto"` \| `"ddcolor"` \| `"opencv"` | `"auto"` | Variante du modèle |
## Suppression du bruit {#noise-removal}
**Route de l'outil :** `noise-removal`
**Modèle :** SCUNet (pipeline de débruitage à plusieurs niveaux)
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `tier` | `"quick"` \| `"balanced"` \| `"quality"` \| `"maximum"` | `"balanced"` | Niveau de traitement |
| `strength` | number (0-100) | `50` | Force du débruitage |
| `detailPreservation` | number (0-100) | `50` | Quantité de détails à préserver ; une valeur plus élevée conserve plus de texture |
| `colorNoise` | number (0-100) | `30` | Force de réduction du bruit de couleur |
| `format` | string | `"original"` | Format de sortie : `original`, `png`, `jpeg`, `webp`, `avif`, `jxl` |
| `quality` | number (1-100) | `90` | Qualité d'encodage de sortie |
## Suppression des yeux rouges {#red-eye-removal}
**Route de l'outil :** `red-eye-removal`
Détecte les points de repère du visage, localise les régions des yeux et corrige la sursaturation du canal rouge.
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `sensitivity` | number (0-100) | `50` | Seuil de détection des pixels rouges |
| `strength` | number (0-100) | `70` | Force de la correction |
| `format` | string | - | Remplacement du format de sortie (optionnel) |
| `quality` | number (1-100) | `90` | Qualité de sortie |
## Restauration de photos {#photo-restoration}
**Route de l'outil :** `restore-photo`
Pipeline en plusieurs étapes pour les photos anciennes ou endommagées : détection et réparation des rayures/déchirures, amélioration des visages, débruitage et colorisation optionnelle.
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `scratchRemoval` | boolean | `true` | Détecter et réparer les rayures, les déchirures |
| `faceEnhancement` | boolean | `true` | Appliquer une passe d'amélioration des visages |
| `fidelity` | number (0-1) | `0.7` | Force de l'amélioration des visages (plus élevé = plus conservateur) |
| `denoise` | boolean | `true` | Appliquer une passe de débruitage |
| `denoiseStrength` | number (0-100) | `25` | Force du débruitage |
| `colorize` | boolean | `false` | Coloriser après la restauration |
| `colorizeStrength` | number (0-100) | `85` | Intensité de la colorisation |
## Photo d'identité {#passport-photo}
**Route de l'outil :** `passport-photo`
**Modèles :** points de repère du visage MediaPipe + suppression d'arrière-plan BiRefNet
Flux de travail en deux phases : analyser (détecter le visage + supprimer l'arrière-plan) puis générer (recadrer, redimensionner, disposer en mosaïque). Prend en charge plus de 37 pays répartis sur 6 régions.
### Phase 1 : Analyser {#phase-1-analyze}
`POST /api/v1/tools/image/passport-photo/analyze`
Accepte un fichier image (multipart). Renvoie les données des points de repère du visage, un aperçu en base64 et les dimensions de l'image.
### Phase 2 : Générer {#phase-2-generate}
`POST /api/v1/tools/image/passport-photo/generate`
Accepte un corps JSON contenant les résultats de la Phase 1 ainsi que les paramètres de génération :
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `jobId` | string | (requis) | ID de tâche de la Phase 1 |
| `filename` | string | (requis) | Nom de fichier d'origine de la Phase 1 |
| `countryCode` | string | (requis) | Code de pays ISO (par ex., `US`, `GB`, `IN`) |
| `documentType` | string | `"passport"` | Type de document |
| `bgColor` | string | `"#FFFFFF"` | Couleur d'arrière-plan hexadécimale |
| `printLayout` | string | `"none"` | Disposition d'impression : `none`, `4x6`, `a4`, `letter` |
| `maxFileSizeKb` | number | `0` | Taille de fichier maximale en Ko (0 = aucune limite) |
| `dpi` | number (72-1200) | `300` | DPI de sortie |
| `customWidthMm` | number | - | Largeur personnalisée en mm (remplace la spécification du pays) |
| `customHeightMm` | number | - | Hauteur personnalisée en mm (remplace la spécification du pays) |
| `zoom` | number (0.5-3) | `1` | Facteur de zoom |
| `adjustX` | number | `0` | Ajustement de la position horizontale |
| `adjustY` | number | `0` | Ajustement de la position verticale |
| `landmarks` | object | (requis) | Points de repère de la Phase 1 |
| `imageWidth` | number | (requis) | Largeur de l'image de la Phase 1 |
| `imageHeight` | number | (requis) | Hauteur de l'image de la Phase 1 |
## Effacement d'objets (remplissage) {#object-erasing-inpainting}
**Route de l'outil :** `erase-object`
**Modèle :** LaMa via ONNX Runtime
Le masque est envoyé en tant que **deuxième partie de fichier** (nom de champ `mask`), et non en base64. Les pixels blancs du masque indiquent les zones à effacer. Les paramètres `format` et `quality` sont envoyés en tant que champs de formulaire de premier niveau.
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `file` | file | (requis) | Image source (multipart) |
| `mask` | file | (requis) | Image de masque (multipart, nom de champ `mask`, blanc = effacer) |
| `format` | string | `"auto"` | Format de sortie : `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl` |
| `quality` | integer (1-100) | `95` | Qualité de sortie |
Accéléré par CUDA lorsqu'un GPU NVIDIA est disponible.
## Extension de canevas par IA {#ai-canvas-expand}
**Route de l'outil :** `ai-canvas-expand`
**Modèle :** extension basée sur LaMa
Étend le canevas d'une image dans n'importe quelle direction et remplit les nouvelles zones avec un contenu généré par IA qui correspond à l'image existante.
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `extendTop` | integer | `0` | Pixels à étendre en haut |
| `extendRight` | integer | `0` | Pixels à étendre à droite |
| `extendBottom` | integer | `0` | Pixels à étendre en bas |
| `extendLeft` | integer | `0` | Pixels à étendre à gauche |
| `tier` | `"fast"` \| `"balanced"` \| `"high"` | `"balanced"` | Niveau de qualité |
| `format` | string | `"auto"` | Format de sortie : `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl` |
| `quality` | integer (1-100) | `95` | Qualité de sortie |
Au moins une direction d'extension doit être supérieure à 0.
## Recadrage intelligent {#smart-crop}
**Route de l'outil :** `smart-crop`
**Modèle :** détection de visages MediaPipe (mode visage uniquement)
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `mode` | string | `"subject"` | Stratégie de recadrage : `subject`, `face`, `trim` |
| `strategy` | `"attention"` \| `"entropy"` | `"attention"` | Stratégie pour le mode sujet |
| `width` | integer | - | Largeur de sortie |
| `height` | integer | - | Hauteur de sortie |
| `padding` | integer (0-50) | `0` | Pourcentage de marge autour du sujet |
| `facePreset` | string | `"head-shoulders"` | Cadrage prédéfini lorsque `mode=face` |
| `sensitivity` | number (0-1) | `0.5` | Seuil de détection de visages |
| `threshold` | integer (0-255) | `30` | Seuil de détection de l'arrière-plan (mode rognage) |
| `padToSquare` | boolean | `false` | Compléter le résultat rogné pour obtenir un carré |
| `padColor` | string | `"#ffffff"` | Couleur d'arrière-plan pour le remplissage carré |
| `targetSize` | integer | - | Taille cible pour la sortie complétée (pixels) |
| `quality` | integer (1-100) | - | Qualité de sortie |
Les anciennes valeurs de `mode` `attention` et `content` sont acceptées et mises en correspondance avec `subject` et `trim` respectivement.
**Préréglages de visage :**
| Préréglage | Idéal pour |
|--------|---------|
| `closeup` | Portraits |
| `head-shoulders` | Photos de profil |
| `upper-body` | LinkedIn / formel |
| `half-body` | Buste complet |
## Transcrire un fichier audio {#transcribe-audio}
**Route de l'outil :** `transcribe-audio`
**Modèle :** faster-whisper
Convertit la parole en texte. Prend en charge les formats de sortie texte brut, SRT et VTT.
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `language` | string | `"auto"` | Langue : `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
| `outputFormat` | `"txt"` \| `"srt"` \| `"vtt"` | `"txt"` | Format de sortie |
## Sous-titres automatiques {#auto-subtitles}
**Route de l'outil :** `auto-subtitles`
**Modèle :** faster-whisper (extrait l'audio de la vidéo, puis le transcrit)
Génère des fichiers de sous-titres à partir de la piste audio d'une vidéo.
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `language` | string | `"auto"` | Langue : `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
| `format` | `"srt"` \| `"vtt"` | `"srt"` | Format de sous-titre de sortie |
## Correcteur de transparence PNG {#png-transparency-fixer}
**Route de l'outil :** `transparency-fixer`
**Modèle :** détourage HR BiRefNet (résolution 2048x2048)
Corrige les PNG « faussement transparents » où l'arrière-plan a été supprimé mais a laissé un liseré, des halos ou des artefacts semi-transparents. Utilise le modèle de détourage haute résolution de BiRefNet pour produire un canal alpha propre, puis applique un traitement de suppression de liseré configurable pour éliminer la contamination des couleurs le long des bords.
**Chaîne de repli en cas de OOM :** Si le détourage HR de BiRefNet dépasse la mémoire disponible, l'outil se rabat automatiquement sur `birefnet-general`, puis sur `u2net`.
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `defringe` | number (0-100) | `30` | Force de suppression du liseré sur les bords pour éliminer la contamination des couleurs |
| `outputFormat` | `"png"` \| `"webp"` | `"png"` | Format de l'image de sortie |
| `removeWatermark` | boolean | `false` | Appliquer un prétraitement de suppression du filigrane (filtre médian) |
```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"}'
```
---
## Outils avec des capacités d'IA optionnelles {#tools-with-optional-ai-capabilities}
Les outils suivants ne sont pas des outils du sidecar Python mais utilisent des fonctionnalités d'IA lorsque certaines options sont activées.
### Amélioration d'image {#image-enhancement}
**Route de l'outil :** `image-enhancement`
**Moteur :** basé sur l'analyse (histogramme et statistiques Sharp)
Analyse l'image et applique des corrections automatiques pour l'exposition, le contraste, la balance des blancs, la saturation, la netteté et le bruit. Prend en charge des modes spécifiques à la scène.
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `mode` | `"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"` | `"auto"` | Mode de scène pour ajuster les corrections |
| `intensity` | number (0-100) | `50` | Force globale de la correction |
| `corrections.exposure` | boolean | `true` | Appliquer la correction de l'exposition |
| `corrections.contrast` | boolean | `true` | Appliquer la correction du contraste |
| `corrections.whiteBalance` | boolean | `true` | Appliquer la correction de la balance des blancs |
| `corrections.saturation` | boolean | `true` | Appliquer la correction de la saturation |
| `corrections.sharpness` | boolean | `true` | Appliquer la correction de la netteté |
| `corrections.denoise` | boolean | `true` | Appliquer le débruitage |
| `deepEnhance` | boolean | `false` | Activer la suppression du bruit par IA via SCUNet (nécessite le groupe `upscale-enhance`) |
Un point de terminaison d'analyse supplémentaire est disponible à `POST /api/v1/tools/image/image-enhancement/analyze` qui renvoie les corrections détectées sans les appliquer.
### Redimensionnement contextuel (découpe de coutures) {#content-aware-resize-seam-carving}
**Route de l'outil :** `content-aware-resize`
**Moteur :** binaire Go `caire` (pas Python : aucun bénéfice GPU)
Redimensionne intelligemment les images en supprimant les coutures à faible énergie, en préservant le contenu important.
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `width` | number | - | Largeur cible |
| `height` | number | - | Hauteur cible |
| `protectFaces` | boolean | `false` | Protéger les régions de visage détectées (nécessite le groupe `face-detection`) |
| `blurRadius` | number (0-20) | `4` | Pré-flou pour le calcul de l'énergie |
| `sobelThreshold` | number (1-20) | `2` | Seuil de sensibilité des bords |
| `square` | boolean | `false` | Forcer une sortie carrée |
apps/docs/fr/api/image-engine.md
+211
View File
@@ -0,0 +1,211 @@
---
description: "Référence des opérations du moteur d'image. Toutes les opérations de traitement d'image basées sur Sharp et leurs paramètres."
i18n_source_hash: 42febdf85fa8
i18n_provenance: human
i18n_output_hash: 0aafaaa6273a
---
# Moteur d'image {#image-engine}
Le paquet `@snapotter/image-engine` gère toutes les opérations d'image non liées à l'IA. Il encapsule [Sharp](https://sharp.pixelplumbing.com/) et s'exécute entièrement en cours de processus sans dépendances externes.
## Opérations {#operations}
### resize {#resize}
Met une image à l'échelle à des dimensions précises ou par pourcentage.
| Paramètre | Type | Description |
|---|---|---|
| `width` | number | Largeur cible en pixels |
| `height` | number | Hauteur cible en pixels |
| `fit` | string | `cover`, `contain`, `fill`, `inside`, ou `outside` |
| `withoutEnlargement` | boolean | Si vrai, n'agrandit pas les images plus petites |
| `percentage` | number | Mettre à l'échelle par pourcentage au lieu de dimensions absolues |
Vous pouvez définir `width`, `height`, ou les deux. Si vous n'en définissez qu'un seul, l'autre est calculé pour conserver le rapport hauteur/largeur.
### crop {#crop}
Découpe une région rectangulaire de l'image.
| Paramètre | Type | Description |
|---|---|---|
| `left` | number | Décalage X depuis le bord gauche |
| `top` | number | Décalage Y depuis le bord supérieur |
| `width` | number | Largeur de la zone de recadrage |
| `height` | number | Hauteur de la zone de recadrage |
| `unit` | string | `px` (par défaut) ou `percent` |
### rotate {#rotate}
Fait pivoter l'image d'un angle donné.
| Paramètre | Type | Description |
|---|---|---|
| `angle` | number | Angle de rotation en degrés (0-360) |
| `background` | string | Couleur de remplissage pour la zone exposée (par défaut : `#000000`). Ne s'applique qu'aux angles non multiples de 90 degrés. |
### flip {#flip}
Met l'image en miroir horizontalement, verticalement, ou les deux. Au moins un des deux doit être vrai.
| Paramètre | Type | Description |
|---|---|---|
| `horizontal` | boolean | Miroir de gauche à droite |
| `vertical` | boolean | Miroir de haut en bas |
### convert {#convert}
Change le format de l'image.
| Paramètre | Type | Description |
|---|---|---|
| `format` | string | Format cible : `jpg`, `png`, `webp`, `avif`, `tiff`, `gif`, `jxl`, `heic`, `heif`, `bmp`, `ico`, `jp2`, `qoi` |
| `quality` | number | Qualité de compression (1-100, s'applique aux formats avec perte) |
Les sept premiers formats (de `jpg` à `jxl`) sont encodés par Sharp en cours de processus. Les formats restants utilisent des encodeurs externes au niveau de l'API : `heic`/`heif` via heif-enc, `bmp`/`ico` via ImageMagick, `jp2` via opj_compress, et `qoi` via un codec TypeScript intégré.
### compress {#compress}
Réduit la taille du fichier tout en conservant le même format.
| Paramètre | Type | Description |
|---|---|---|
| `quality` | number | Qualité cible (1-100) |
| `targetSizeBytes` | number | Taille de fichier cible optionnelle en octets |
| `format` | string | Remplacement de format optionnel |
### strip-metadata {#strip-metadata}
Supprime les métadonnées EXIF, IPTC, XMP et ICC de l'image. Sans paramètres (ou `stripAll: true`), supprime tout. Passez des indicateurs individuels pour une suppression sélective.
| Paramètre | Type | Description |
|---|---|---|
| `stripAll` | boolean | Supprimer toutes les métadonnées (par défaut lorsqu'aucun indicateur n'est défini) |
| `stripExif` | boolean | Supprimer les données EXIF (y compris le GPS si `stripGps` n'est pas défini séparément) |
| `stripGps` | boolean | Supprimer les données de localisation GPS |
| `stripIcc` | boolean | Supprimer le profil de couleur ICC |
| `stripXmp` | boolean | Supprimer les métadonnées XMP |
### Ajustements de couleur {#color-adjustments}
Ces opérations modifient les propriétés de couleur d'une image. Chacune prend une seule valeur numérique.
| Opération | Paramètre | Plage | Description |
|---|---|---|---|
| `brightness` | `value` | -100 à 100 | Ajuster la luminosité |
| `contrast` | `value` | -100 à 100 | Ajuster le contraste |
| `saturation` | `value` | -100 à 100 | Ajuster la saturation des couleurs |
### Filtres de couleur {#color-filters}
Ceux-ci appliquent une transformation de couleur fixe. Ils ne prennent aucun paramètre.
| Opération | Description |
|---|---|
| `grayscale` | Convertir en niveaux de gris |
| `sepia` | Appliquer une teinte sépia |
| `invert` | Inverser toutes les couleurs |
### Canaux de couleur {#color-channels}
Ajuste les canaux de couleur RVB individuels. Les valeurs sont des multiplicateurs où 100 = aucun changement.
| Paramètre | Type | Description |
|---|---|---|
| `red` | number | Multiplicateur du canal rouge (0 à 200, 100 = inchangé) |
| `green` | number | Multiplicateur du canal vert (0 à 200, 100 = inchangé) |
| `blue` | number | Multiplicateur du canal bleu (0 à 200, 100 = inchangé) |
### sharpen {#sharpen}
Accentuation simple contrôlée par une seule valeur.
| Paramètre | Type | Description |
|---|---|---|
| `value` | number | Intensité de l'accentuation (0 à 100). Associée à un sigma gaussien de 0,5-10. |
### sharpen-advanced {#sharpen-advanced}
Accentuation avancée avec trois méthodes sélectionnables et une pré-passe optionnelle de réduction du bruit.
| Paramètre | Type | Description |
|---|---|---|
| `method` | string | `adaptive`, `unsharp-mask`, ou `high-pass` |
| `sigma` | number | Rayon du flou gaussien, 0,5-10 (adaptatif) |
| `m1` | number | Accentuation des zones planes, 0-10 (adaptatif) |
| `m2` | number | Accentuation des zones texturées, 0-20 (adaptatif) |
| `x1` | number | Seuil plat/dentelé, 0-10 (adaptatif) |
| `y2` | number | Éclaircissement maximal (limite de halo), 0-50 (adaptatif) |
| `y3` | number | Assombrissement maximal (limite de halo), 0-50 (adaptatif) |
| `amount` | number | Pourcentage d'intensité, 0-500 (masque flou) |
| `radius` | number | Rayon du flou, 0,1-5,0 (masque flou) |
| `threshold` | number | Luminosité minimale des contours, 0-255 (masque flou) |
| `strength` | number | Intensité du mélange, 0-100 (passe-haut) |
| `kernelSize` | number | `3` ou `5` pour un noyau 3x3 / 5x5 (passe-haut) |
| `denoise` | string | Pré-passe de réduction du bruit : `off`, `light`, `medium`, ou `strong` |
Les paramètres sont propres à chaque méthode. Ne fournissez que ceux pertinents pour la méthode choisie.
### color-blindness {#color-blindness}
Simule une déficience de la vision des couleurs à l'aide d'une matrice de recombinaison des couleurs 3x3.
| Paramètre | Type | Description |
|---|---|---|
| `type` | string | L'une de : `protanopia`, `deuteranopia`, `tritanopia`, `protanomaly`, `deuteranomaly`, `tritanomaly`, `achromatopsia`, `blueConeMonochromacy` |
### edit-metadata {#edit-metadata}
Écrit ou supprime des champs de métadonnées EXIF/IPTC individuels sans supprimer le bloc entier.
| Paramètre | Type | Description |
|---|---|---|
| `artist` | string | Balise EXIF Artist |
| `copyright` | string | Balise EXIF Copyright |
| `imageDescription` | string | Balise EXIF ImageDescription |
| `software` | string | Balise EXIF Software |
| `dateTime` | string | Balise EXIF DateTime |
| `dateTimeOriginal` | string | Balise EXIF DateTimeOriginal |
| `clearGps` | boolean | Supprimer toutes les balises GPS |
| `fieldsToRemove` | string[] | Liste des noms de champs EXIF à supprimer |
Tous les paramètres sont optionnels. Les champs listés dans `fieldsToRemove` sont supprimés du bloc EXIF existant. Les champs définis via les paramètres nommés sont écrits (ou écrasés). Les clés binaires/dangereuses comme MakerNote sont ignorées silencieusement.
## Détection de format {#format-detection}
Le moteur détecte automatiquement les formats d'entrée à partir des en-têtes de fichier, et non simplement des extensions de fichier. Cela signifie qu'un fichier `.jpg` qui est en réalité un PNG sera traité correctement. La détection utilise une approche multicouche : d'abord les octets magiques, puis l'extension de fichier en repli.
SnapOtter prend en charge **plus de 55 formats d'entrée** et **13 formats de sortie**, dont 23 formats RAW d'appareils photo de plus de 20 marques, des formats professionnels (PSD, EPS, OpenEXR, HDR), des codecs modernes (JPEG XL, AVIF, HEIC, QOI, JPEG 2000) et des formats scientifiques/de jeu (FITS, DDS). Le décodage est géré nativement par Sharp lorsque c'est possible, avec repli automatique sur ImageMagick, LibRaw et des décodeurs CLI spécialisés.
Consultez la page [Formats pris en charge](/fr/guide/supported-formats) pour la liste complète.
## Extraction des métadonnées {#metadata-extraction}
L'outil `info` renvoie les métadonnées de l'image. Consultez [Informations sur l'image](/fr/tools/image/info) pour la référence complète des champs.
```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 }
]
}
```
apps/docs/fr/api/rest.md
+702
View File
@@ -0,0 +1,702 @@
---
description: "Référence complète de l'API REST. Points de terminaison des outils, traitement par lots, pipelines, bibliothèque de fichiers, authentification, équipes et opérations d'administration."
i18n_source_hash: 8646977f7cc9
i18n_provenance: machine
i18n_output_hash: 450fd529e479
---
# Référence de l'API REST {#rest-api-reference}
La documentation interactive de l'API, avec des exemples de requête et de réponse, est disponible sur [http://localhost:1349/api/docs](http://localhost:1349/api/docs).
Spécifications lisibles par machine :
- `/api/v1/openapi.yaml` - spécification OpenAPI 3.1
- `/llms.txt` - résumé adapté aux LLM
- `/llms-full.txt` - documentation complète adaptée aux LLM
## Authentification {#authentication}
Tous les points de terminaison exigent une authentification, sauf lorsque `AUTH_ENABLED=false`.
### Jeton de session {#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>"
```
Les sessions expirent au bout de 7 jours (configurable via `SESSION_DURATION_HOURS`).
### Clés d'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>"
```
Les clés sont préfixées par `si_` et stockées sous forme de hachages scrypt : la clé brute est affichée une seule fois et ne peut plus jamais être récupérée.
### Points de terminaison d'authentification {#auth-endpoints}
| Méthode | Chemin | Accès | Description |
|--------|------|--------|-------------|
| `POST` | `/api/auth/login` | Public | Connexion, obtention d'un jeton de session |
| `POST` | `/api/auth/logout` | Auth | Détruire la session actuelle |
| `GET` | `/api/auth/session` | Auth | Valider la session actuelle |
| `POST` | `/api/auth/change-password` | Auth | Changer son propre mot de passe (invalide toutes les autres sessions et clés d'API) |
| `GET` | `/api/auth/users` | Admin | Lister tous les utilisateurs |
| `POST` | `/api/auth/register` | Admin | Créer un nouvel utilisateur |
| `PUT` | `/api/auth/users/:id` | Admin | Mettre à jour le rôle ou l'équipe d'un utilisateur |
| `POST` | `/api/auth/users/:id/reset-password` | Admin | Réinitialiser le mot de passe d'un utilisateur |
| `DELETE` | `/api/auth/users/:id` | Admin | Supprimer un utilisateur |
| `GET` | `/api/v1/config/auth` | Public | Vérifier si l'authentification est activée (`{ authEnabled: bool }`) |
| `POST` | `/api/auth/mfa/enroll` | Auth | Démarrer l'inscription à l'authentification multifacteur TOTP. Nécessite la fonctionnalité entreprise `mfa` |
| `POST` | `/api/auth/mfa/verify` | Auth | Confirmer l'inscription à l'authentification multifacteur avec un code TOTP |
| `POST` | `/api/auth/mfa/complete` | Public | Terminer un défi de connexion multifacteur en attente |
| `POST` | `/api/auth/mfa/disable` | Auth | Désactiver l'authentification multifacteur pour l'utilisateur actuel |
| `POST` | `/api/auth/users/:id/mfa/reset` | Admin (`users:manage`) | Réinitialiser l'authentification multifacteur d'un utilisateur |
| `GET` | `/api/auth/oidc/login` | Public | Démarrer la connexion OIDC lorsque OIDC est activé |
| `GET` | `/api/auth/oidc/callback` | Public | Rappel d'autorisation OIDC |
| `GET` | `/api/auth/saml/metadata` | Public | XML de métadonnées SP SAML lorsque SAML est activé |
| `GET` | `/api/auth/saml/login` | Public | Démarrer la connexion SAML |
| `POST` | `/api/auth/saml/callback` | Public | Service consommateur d'assertions SAML |
Lorsque l'authentification multifacteur est activée pour un utilisateur, `POST /api/auth/login` renvoie `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` au lieu d'un jeton de session. Envoyez ce `mfaToken` accompagné d'un code TOTP ou d'un code de récupération à `/api/auth/mfa/complete`.
### Autorisations {#permissions}
| Autorisation | Admin | Utilisateur |
|-----------|:-----:|:----:|
| Utiliser les outils | ✓ | ✓ |
| Ses propres fichiers/pipelines/clés d'API | ✓ | ✓ |
| Voir les fichiers/pipelines/clés de tous les utilisateurs | ✓ | - |
| Écrire les paramètres | ✓ | - |
| Gérer les utilisateurs et les équipes | ✓ | - |
| Gérer l'image de marque | ✓ | - |
## Vérification de l'état {#health-check}
| Méthode | Chemin | Accès | Description |
|--------|------|--------|-------------|
| `GET` | `/api/v1/health` | Public | Vérification de base de l'état. Renvoie `{"status":"healthy","version":"..."}` avec 200, ou `{"status":"unhealthy"}` avec 503 si la base de données est inaccessible. |
| `GET` | `/api/v1/readyz` | Public | Sonde de disponibilité. Vérifie PostgreSQL, Redis, l'espace disque et S3 lorsqu'il est configuré. Renvoie 503 lorsque l'instance ne doit pas recevoir de trafic. |
| `GET` | `/api/v1/admin/health` | Admin (`system:health`) | Diagnostics détaillés incluant la durée de fonctionnement, le mode de stockage, l'état de la base de données, l'état de la file d'attente et la disponibilité du GPU. |
## Utilisation des outils {#using-tools}
Chaque outil suit le même schéma :
```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>` est l'un de `image`, `video`, `audio`, `pdf`, ou `files`.
- Le téléversement est `multipart/form-data`.
- `settings` est une chaîne JSON contenant des options spécifiques à l'outil.
- `clientJobId` est un champ de formulaire optionnel pour la corrélation de progression fournie par l'appelant.
- `fileId` est un champ de formulaire optionnel référençant un élément existant de la bibliothèque de fichiers. Lorsqu'il est présent, la sortie traitée est enregistrée comme nouvelle version et la réponse inclut `savedFileId`.
- **Les outils rapides** renvoient généralement du JSON en 200 : `{"jobId":"...","downloadUrl":"/api/v1/download/<jobId>/<filename>","originalSize":1234,"processedSize":567}`. Récupérez le fichier traité depuis `downloadUrl`.
- **Tout outil mis en file d'attente** peut renvoyer du JSON en 202 s'il est de longue durée ou dépasse la fenêtre d'attente synchrone : `{"jobId":"...","async":true}`. Connectez-vous au SSE pour suivre la progression, puis téléchargez une fois terminé (voir [Suivi de la progression](#progress-tracking)).
- **Les routes par lots** renvoient une archive ZIP diffusée directement (avec l'en-tête `X-Job-Id`) pour les outils enregistrés dans le registre générique de traitement par lots.
## Référence des outils {#tools-reference}
### Préréglages de conversion {#conversion-presets}
Le catalogue partagé inclut 83 points de terminaison de préréglages de conversion dédiés, tels que `jpg-to-png`, `mov-to-mp4`, `m4a-to-mp3`, `pdf-to-jpg`, et `excel-to-csv`. Les préréglages sont des routes d'outils de première classe :
`POST /api/v1/tools/<section>/<presetId>`
Chaque préréglage verrouille le format de sortie et délègue à un outil de base tel que `convert`, `convert-video`, `extract-audio`, `convert-audio`, `image-to-pdf`, `pdf-to-image`, `svg-to-raster`, ou `convert-spreadsheet`. Consultez [Préréglages de conversion](/fr/tools/conversion-presets) pour le tableau complet des routes et les paramètres optionnels.
### Essentiels {#essentials}
| ID de l'outil | Nom | Paramètres principaux |
|---------|------|-------------|
| `resize` | Redimensionner | `width`, `height`, `fit` (cover/contain/fill/inside/outside), `percentage`, `withoutEnlargement`, plus 23 préréglages pour les réseaux sociaux |
| `crop` | Rogner | `left`, `top`, `width`, `height`, `unit` (px/pourcentage) |
| `rotate` | Pivoter et retourner | `angle`, `horizontal` (bool), `vertical` (bool) |
| `convert` | Convertir | `format` (jpg/png/webp/avif/tiff/gif/heic/heif), `quality` |
| `compress` | Compresser | `mode` (quality/targetSize), `quality` (1–100), `targetSizeKb` |
### Optimisation {#optimization}
| ID de l'outil | Nom | Paramètres principaux |
|---------|------|-------------|
| `optimize-for-web` | Optimiser pour le Web | `format` (webp/jpeg/avif/png), `quality`, `maxWidth`, `maxHeight`, `progressive`, `stripMetadata` |
| `strip-metadata` | Supprimer les métadonnées | - |
| `edit-metadata` | Modifier les métadonnées | `title`, `description`, `author`, `copyright`, `keywords`, `gps` (lat/lon), `dateTime` |
| `bulk-rename` | Renommage en masse | `pattern` (prend en charge `{n}`, `{date}`, `{original}`), `startIndex`, `padding` |
| `image-to-pdf` | Image vers PDF | `pageSize` (A4/Letter/...), `orientation`, `margin`, `targetSize` ({value, unit}) |
| `favicon` | Générateur de favicon | `padding`, `backgroundColor`, `borderRadius` - génère toutes les tailles standard |
### Réglages {#adjustments}
| ID de l'outil | Nom | Paramètres principaux |
|---------|------|-------------|
| `adjust-colors` | Ajuster les couleurs | `brightness`, `contrast`, `exposure`, `saturation`, `temperature`, `tint`, `hue`, `sharpness`, `red`, `green`, `blue`, `effect` (none/grayscale/sepia/invert) |
| `sharpening` | Accentuation | `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` | Remplacer une couleur | `sourceColor`, `targetColor` (remplacement), `makeTransparent`, `tolerance` |
| `color-blindness` | Simulation de daltonisme | `simulationType` (protanopia/deuteranopia/tritanopia/protanomaly/deuteranomaly/tritanomaly/achromatopsia/blueConeMonochromacy, par défaut \"deuteranomaly\") |
| `duotone` | Duotone | `shadow` (hex), `highlight` (hex), `intensity` (0-100) |
| `pixelate` | Pixelliser | `blockSize` (2-128), `region` ({left, top, width, height} pour une pixellisation partielle) |
| `vignette` | Vignettage | `strength` (0.1-1), `color` (hex), `radius`, `softness`, `roundness`, `centerX`, `centerY` |
### Outils d'IA {#ai-tools}
Tous les outils d'IA s'exécutent sur votre matériel : CPU par défaut, ou NVIDIA CUDA lorsqu'un GPU NVIDIA compatible est disponible. L'accélération via iGPU Intel/AMD par VA-API, Quick Sync ou OpenCL n'est pas prise en charge aujourd'hui pour l'inférence d'IA. Aucune connexion Internet requise.
| ID de l'outil | Nom | Modèle d'IA | Paramètres principaux |
|---------|------|---------|-------------|
| `remove-background` | Supprimer l'arrière-plan | rembg (BiRefNet / U2-Net) | `model`, `backgroundType` (transparent/color/gradient/blur/image), `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurEnabled`, `blurIntensity`, `shadowEnabled`, `shadowOpacity` |
| `upscale` | Agrandissement d'image | RealESRGAN | `scale` (2/4), `model`, `faceEnhance`, `denoise`, `format`, `quality` |
| `erase-object` | Gomme d'objets | LaMa (ONNX) | Le masque est envoyé comme deuxième partie de fichier (nom de champ `mask`), `format`, `quality` |
| `ocr` | OCR / Extraction de texte | PaddleOCR / Tesseract | `quality` (fast/balanced/best), `language`, `enhance` |
| `blur-faces` | Floutage des visages / données personnelles | MediaPipe | `blurRadius`, `sensitivity` |
| `smart-crop` | Rognage intelligent | 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` | Amélioration d'image | Basé sur l'analyse | `mode` (auto/exposure/contrast/color/sharpness), `strength` |
| `enhance-faces` | Amélioration des visages | GFPGAN / CodeFormer | `model` (gfpgan/codeformer), `strength`, `sensitivity`, `centerFace` |
| `colorize` | Colorisation par IA | DDColor | `intensity`, `model` |
| `noise-removal` | Suppression du bruit | Débruitage à plusieurs niveaux | `tier` (quick/balanced/quality/maximum), `strength`, `detailPreservation`, `colorNoise`, `format`, `quality` |
| `red-eye-removal` | Suppression des yeux rouges | Points de repère du visage + analyse des couleurs | `sensitivity`, `strength` |
| `restore-photo` | Restauration de photos | Pipeline multi-étapes | `mode` (auto/light/heavy), `scratchRemoval`, `faceEnhancement`, `fidelity`, `denoise`, `denoiseStrength`, `colorize` |
| `passport-photo` | Photo d'identité | Points de repère MediaPipe | Flux en deux phases. L'analyse utilise le multipart `file` ; la génération utilise du JSON avec `countryCode`, `bgColor`, `printLayout` (none/4x6/a4), points de repère, dimensions de l'image |
| `content-aware-resize` | Redimensionnement adaptatif au contenu | Découpe par coutures (caire) | `width`, `height`, `protectFaces`, `blurRadius`, `sobelThreshold`, `square` |
| `transparency-fixer` | Correcteur de transparence PNG | Détourage HR BiRefNet | `defringe` (0-100), `outputFormat` (png/webp) |
| `background-replace` | Remplacer l'arrière-plan | rembg (BiRefNet) | `backgroundType` (color/gradient), `color` (hex), `gradientColor1`, `gradientColor2`, `gradientAngle`, `feather` (0-20), `format` (png/webp) |
| `blur-background` | Flouter l'arrière-plan | rembg (BiRefNet) | `intensity` (1-100), `feather` (0-20), `format` (png/webp) |
| `ai-canvas-expand` | Extension de canevas par IA | LaMa (outpainting) | `extendTop`, `extendRight`, `extendBottom`, `extendLeft` (px), `tier` (fast/balanced/high), `format`, `quality` |
### Filigrane et superposition {#watermark-overlay}
| ID de l'outil | Nom | Paramètres principaux |
|---------|------|-------------|
| `watermark-text` | Filigrane de texte | `text`, `font`, `fontSize`, `color`, `opacity`, `position`, `rotation`, `tile` |
| `watermark-image` | Filigrane d'image | `opacity`, `position`, `scale` - le deuxième fichier est le filigrane |
| `text-overlay` | Superposition de texte | `text`, `font`, `fontSize`, `color`, `x`, `y`, `background`, `padding`, `borderRadius` |
| `compose` | Composition d'images | `x`, `y`, `opacity`, `blend` - le deuxième fichier est superposé par-dessus |
| `meme-generator` | Générateur de mèmes | `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`. Prend en charge le mode modèle (corps JSON avec `templateId`) ou le mode image personnalisée (multipart avec fichier). |
### Utilitaires {#utilities}
| ID de l'outil | Nom | Paramètres principaux |
|---------|------|-------------|
| `info` | Infos sur l'image | - (renvoie width, height, format, size, channels, hasAlpha, DPI, EXIF) |
| `compare` | Comparer des images | `mode` (side-by-side/overlay/diff), `diffThreshold` - le deuxième fichier est la cible de comparaison |
| `find-duplicates` | Trouver les doublons | `threshold` (distance de hachage perceptuel, par défaut 8) - multi-fichiers |
| `color-palette` | Palette de couleurs | `count` (nombre de couleurs dominantes), `format` (hex/rgb) |
| `qr-generate` | Générateur de code QR | `data`, `size`, `margin`, `colorDark`, `colorLight`, `errorCorrectionLevel`, `dotStyle`, `cornerStyle`, `logo` (fichier optionnel) |
| `barcode-read` | Lecteur de code-barres | - (détecte automatiquement QR, EAN, Code128, DataMatrix, etc.) |
| `image-to-base64` | Image vers Base64 | `format` (data-uri/plain), `mimeType` |
| `html-to-image` | HTML vers image | `url`, `format` (png/jpg/webp), `quality`, `fullPage`, `devicePreset` (desktop/tablet/mobile/custom), `viewportWidth`, `viewportHeight` |
| `histogram` | Histogramme | `scale` (linear/log) - renvoie un graphique d'histogramme RGB + statistiques par canal |
| `lqip-placeholder` | Espace réservé LQIP | `width` (4-64), `blur`, `strategy` (blur/pixelate/solid), `format` (webp/png/jpeg), `quality` |
| `barcode-generate` | Générateur de code-barres | `text`, `type` (code128/ean13/upca/code39/itf14/datamatrix), `scale` (1-8), `includeText` (bool). Corps JSON, aucun téléversement de fichier. |
### Mise en page et composition {#layout-composition}
| ID de l'outil | Nom | Paramètres principaux |
|---------|------|-------------|
| `collage` | Collage / Grille | `template` (plus de 25 dispositions), `gap`, `backgroundColor`, `borderRadius` - multi-fichiers |
| `stitch` | Assembler / Combiner | `direction` (horizontal/vertical/grid), `gap`, `backgroundColor`, `alignment` - multi-fichiers |
| `split` | Découpe d'image | `mode` (grid/rows/cols), `rows`, `cols`, `tileWidth`, `tileHeight` |
| `border` | Bordure et cadre | `width`, `color`, `style` (solid/gradient/pattern), `borderRadius`, `padding`, `shadow` |
| `beautify` | Embellir une capture d'écran | `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` | Rognage circulaire | `zoom` (1-5), `offsetX`, `offsetY`, `borderWidth`, `borderColor`, `background` (transparent/hex), `outputSize` |
| `image-pad` | Marges d'image | `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` | Feuille de sprites | `columns` (1-16), `padding`, `background` (hex), `format` (png/webp/jpeg), `quality` - multi-fichiers (2-64 images) |
### Format et conversion {#format-conversion}
| ID de l'outil | Nom | Paramètres principaux |
|---------|------|-------------|
| `svg-to-raster` | SVG vers matriciel | `format` (png/jpeg/webp/avif/tiff/gif/heif), `width`, `height`, `scale`, `dpi`, `background` |
| `vectorize` | Image vers SVG | `colorMode` (bw/color), `threshold`, `colorPrecision`, `filterSpeckle`, `pathMode` (none/polygon/spline) |
| `gif-tools` | Outils GIF | `action` (resize/optimize/reverse/speed/extract-frames/rotate/add-text), paramètres spécifiques à l'action |
| `gif-webp` | Convertisseur GIF/WebP | `quality` (1-100), `lossless` (bool), `resizePercent` (10-100) |
### Outils vidéo {#video-tools}
| ID de l'outil | Nom | Paramètres principaux |
|---------|------|-------------|
| `convert-video` | Convertir une vidéo | `format` (mp4/mov/webm/avi/mkv), `quality` (high/balanced/small) |
| `compress-video` | Compresser une vidéo | `quality` (light/balanced/strong), `resolution` (original/1080p/720p/480p) |
| `trim-video` | Découper une vidéo | `startS`, `endS`, `precise` (bool, coupe précise à l'image près) |
| `mute-video` | Couper le son d'une vidéo | - |
| `video-to-gif` | Vidéo vers GIF | `fps` (1-30), `width`, `startS`, `durationS` (max 60 s) |
| `resize-video` | Redimensionner une vidéo | `width`, `height`, `preset` (custom/2160p/1440p/1080p/720p/480p/360p) |
| `crop-video` | Rogner une vidéo | `width`, `height`, `x`, `y` |
| `rotate-video` | Pivoter une vidéo | `transform` (cw90/ccw90/180/hflip/vflip) |
| `change-fps` | Modifier les images par seconde | `fps` (1-120) |
| `video-color` | Couleur de la vidéo | `brightness`, `contrast`, `saturation`, `gamma` |
| `video-speed` | Vitesse de la vidéo | `factor` (0.25-4), `keepPitch` (bool) |
| `reverse-video` | Inverser une vidéo | - (max 5 minutes) |
| `video-loudnorm` | Normaliser l'audio | - (EBU R128) |
| `aspect-pad` | Marges au format | `target` (16:9/9:16/1:1/4:3/3:4), `color` (hex) |
| `blur-pad` | Marges floutées | `target` (16:9/9:16/1:1/4:3/3:4), `blur` (2-50) |
| `watermark-video` | Filigrane sur vidéo | `text`, `position`, `fontSize`, `opacity`, `color` |
| `stabilize-video` | Stabiliser une vidéo | `smoothing` (5-60, en images) |
| `gif-to-video` | GIF vers vidéo | `format` (mp4/webm/mov) |
| `video-to-webp` | Vidéo vers WebP | `fps`, `width`, `quality`, `loop` (bool) |
| `video-to-frames` | Vidéo vers images | `mode` (all/nth/timestamps), `n`, `timestamps`, `format` (png/jpg) |
| `merge-videos` | Fusionner des vidéos | - (multi-fichiers, normalisées à la résolution de la première vidéo) |
| `replace-audio` | Remplacer l'audio | - (vidéo + fichier audio, deux fichiers) |
| `burn-subtitles` | Incruster des sous-titres | `fontSize` (8-72) - vidéo + fichier de sous-titres |
| `embed-subtitles` | Intégrer des sous-titres | `language` (code ISO 639-2/B) - vidéo + fichier de sous-titres |
| `extract-subtitles` | Extraire des sous-titres | - (produit du SRT) |
| `images-to-video` | Images vers vidéo | `secondsPerImage` (0.5-10), `resolution` (1080p/720p/square), `fps` - multi-fichiers |
| `video-metadata` | Nettoyer les métadonnées vidéo | - |
| `auto-subtitles` | Sous-titres automatiques (IA) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `format` (srt/vtt) |
| `extract-audio` | Extraire l'audio | `format` (mp3/wav/m4a/ogg) |
### Outils audio {#audio-tools}
| ID de l'outil | Nom | Paramètres principaux |
|---------|------|-------------|
| `convert-audio` | Convertir l'audio | `format` (mp3/wav/ogg/flac/m4a), `bitrateKbps` (32-320) |
| `trim-audio` | Découper l'audio | `startS`, `endS` |
| `volume-adjust` | Ajuster le volume | `gainDb` (-30 à 30) |
| `normalize-audio` | Normaliser l'audio | - (EBU R128, -16 LUFS) |
| `fade-audio` | Fondu audio | `fadeInS` (0-30), `fadeOutS` (0-30) |
| `reverse-audio` | Inverser l'audio | - |
| `audio-speed` | Vitesse de l'audio | `factor` (0.25-4) |
| `pitch-shift` | Décalage de hauteur | `semitones` (-12 à 12) |
| `audio-channels` | Canaux audio | `mode` (stereo-to-mono/mono-to-stereo/swap) |
| `silence-removal` | Suppression des silences | `thresholdDb` (-80 à -20), `minSilenceS` (0.1-5) |
| `noise-reduction` | Réduction du bruit | `strength` (light/medium/strong) |
| `merge-audio` | Fusionner l'audio | `format` (mp3/wav/flac/m4a) - multi-fichiers |
| `split-audio` | Diviser l'audio | `mode` (time/parts/silence), `segmentS`, `parts`, `thresholdDb`, `minSilenceS` |
| `ringtone-maker` | Créateur de sonnerie | `startS`, `durationS` (1-30) |
| `waveform-image` | Image de forme d'onde | `width`, `height`, `color` (hex) |
| `audio-metadata` | Métadonnées audio | `strip` (bool), `title`, `artist`, `album` |
| `transcribe-audio` | Transcrire l'audio (IA) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `outputFormat` (txt/srt/vtt) |
### Outils de documents {#document-tools}
| ID de l'outil | Nom | Paramètres principaux |
|---------|------|-------------|
| `merge-pdf` | Fusionner des PDF | - (multi-fichiers, jusqu'à 20 PDF) |
| `split-pdf` | Diviser un PDF | `mode` (range/every), `range`, `everyN` (1-500) |
| `compress-pdf` | Compresser un PDF | `mode` (quality/targetSize), `quality` (1-100), `targetSizeKb` |
| `rotate-pdf` | Pivoter un PDF | `angle` (90/180/270), `range` (plage de pages) |
| `extract-pages` | Extraire des pages | `range` (syntaxe qpdf, par exemple \"1-5,8,10-z\") |
| `remove-pages` | Supprimer des pages | `pages` (plage qpdf à supprimer) |
| `organize-pdf` | Organiser un PDF | `order` (ordre des pages qpdf, par exemple \"3,1,2,5-z\") |
| `protect-pdf` | Protéger un PDF | `userPassword`, `ownerPassword` (AES-256) |
| `unlock-pdf` | Déverrouiller un PDF | `password` |
| `repair-pdf` | Réparer un PDF | - |
| `linearize-pdf` | Optimiser un PDF pour le Web | - (linéariser pour un affichage web rapide) |
| `grayscale-pdf` | PDF en niveaux de gris | - |
| `pdfa-convert` | Convertir en PDF/A | - (PDF/A-2 d'archivage) |
| `crop-pdf` | Rogner un PDF | `margin` (0-2000 points) |
| `nup-pdf` | PDF N pages par feuille | `perSheet` (2/3/4/8/9/12/16) |
| `booklet-pdf` | PDF en livret | `perSheet` (2/4/6/8) |
| `watermark-pdf` | Filigrane sur PDF | `text`, `position`, `fontSize`, `opacity`, `rotation` |
| `pdf-page-numbers` | Numéros de page du PDF | `position` (bl/bc/br/tl/tc/tr), `fontSize` |
| `flatten-pdf` | Aplatir un PDF | - (intègre les formulaires et les annotations) |
| `redact-pdf` | Caviarder un PDF | `terms` (string[]), `caseSensitive` (bool) |
| `sign-pdf` | Signer un PDF | Route multipart personnalisée avec le PDF `file`, les fichiers de signature `sig0`, `sig1`, et le tableau JSON `placements` |
| `pdf-to-text` | PDF vers texte | - |
| `pdf-to-word` | PDF vers Word | - |
| `pdf-metadata` | Métadonnées du PDF | `title`, `author`, `subject`, `keywords` |
| `convert-document` | Convertir un document | `format` (docx/odt/rtf/txt) |
| `convert-presentation` | Convertir une présentation | `format` (pptx/odp) |
| `convert-spreadsheet` | Convertir une feuille de calcul | `format` (xlsx/ods/csv) |
| `excel-to-pdf` | Excel vers PDF | - |
| `word-to-pdf` | Word vers PDF | - |
| `powerpoint-to-pdf` | PowerPoint vers PDF | - |
| `html-to-pdf` | HTML vers PDF | - (ressources distantes désactivées) |
| `markdown-to-docx` | Markdown vers Word | - |
| `markdown-to-html` | Markdown vers HTML | - |
| `markdown-to-pdf` | Markdown vers PDF | - (ressources distantes désactivées) |
| `epub-convert` | Convertir un EPUB | `format` (pdf/docx/html/md) |
| `to-epub` | Convertir en EPUB | - (accepte .docx, .md, .html, .txt) |
| `ocr-pdf` | OCR de PDF (IA) | `quality` (fast/balanced/best), `language` (auto/en/de/fr/es/zh/ja/ko), `pages` |
| `pdf-to-image` | PDF vers image | `pages` (all/range), `format`, `dpi`, `quality` |
| `pdf-to-jpg` | PDF vers JPG | `pages`, `dpi`, `quality`, `colorMode` |
| `pdf-to-png` | PDF vers PNG | `pages`, `dpi`, `quality`, `colorMode` |
| `pdf-to-tiff` | PDF vers TIFF | `pages`, `dpi`, `quality`, `colorMode` |
### Outils de fichiers {#file-tools}
| ID de l'outil | Nom | Paramètres principaux |
|---------|------|-------------|
| `chart-maker` | Créateur de graphiques | `kind` (bar/line/pie), `title`, `width`, `height` |
| `csv-excel` | CSV vers Excel | `sheet` (numéro de feuille de calcul pour l'entrée XLSX) - bidirectionnel |
| `csv-json` | CSV vers JSON | `pretty` (bool) - bidirectionnel |
| `json-xml` | JSON vers XML | `pretty` (bool) - bidirectionnel |
| `split-csv` | Diviser un CSV | `rowsPerFile` (1-1000000), `keepHeader` (bool) |
| `merge-csvs` | Fusionner des CSV | - (multi-fichiers, colonnes correspondantes) |
| `yaml-json` | YAML / JSON | - (bidirectionnel) |
| `xml-to-csv` | XML vers CSV | - (trouve automatiquement les éléments répétés) |
| `excel-to-csv` | Excel vers CSV | préréglage de conversion dédié adossé à `convert-spreadsheet` |
| `create-zip` | Créer un ZIP | - (multi-fichiers, 2-50 fichiers) |
| `extract-zip` | Extraire un ZIP | - (protégé contre les bombes) |
### HTML vers image {#html-to-image}
Capturez une page web sous forme d'image. Contrairement aux autres outils, ce point de terminaison accepte `application/json` au lieu de données de formulaire multipart (aucun téléversement de fichier nécessaire).
**Point de terminaison :** `POST /api/v1/tools/image/html-to-image`
**Content-Type :** `application/json`
| Paramètre | Type | Par défaut | Description |
|-----------|------|---------|-------------|
| `url` | string | (requis) | URL à capturer (http/https uniquement) |
| `format` | string | `"png"` | Format de sortie : `jpg`, `png`, `webp` |
| `quality` | number | `90` | Qualité 1-100 (JPG/WebP uniquement) |
| `fullPage` | boolean | `false` | Capturer la page entière défilable |
| `devicePreset` | string | `"desktop"` | `desktop`, `tablet`, `mobile`, `custom` |
| `viewportWidth` | number | `1280` | Largeur personnalisée de la fenêtre d'affichage 320-3840 |
| `viewportHeight` | number | `720` | Hauteur personnalisée de la fenêtre d'affichage 320-2160 |
**Exemple :**
```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"}'
```
**Réponse :**
```json
{
"jobId": "uuid",
"downloadUrl": "/api/v1/download/{jobId}/screenshot.png",
"originalSize": 0,
"processedSize": 54321
}
```
### Sous-routes des outils {#tool-sub-routes}
Certains outils exposent des points de terminaison supplémentaires au-delà du `POST /api/v1/tools/<section>/<toolId>` standard :
| Méthode | Chemin | Description |
|--------|------|-------------|
| `GET` | `/api/v1/tools/popular` | Renvoie les ID d'outils populaires, en se rabattant sur une liste par défaut sélectionnée lorsque les données d'utilisation sont rares |
| `POST` | `/api/v1/tools/image/remove-background/effects` | Applique des effets d'arrière-plan (couleur/dégradé/flou/ombre) sans réexécuter l'IA. Utilise le masque mis en cache lors de la suppression initiale. |
| `POST` | `/api/v1/tools/image/edit-metadata/inspect` | Lit les métadonnées EXIF/IPTC/XMP existantes d'une image |
| `POST` | `/api/v1/tools/image/strip-metadata/inspect` | Inspecte les champs de métadonnées avant leur suppression |
| `POST` | `/api/v1/tools/image/passport-photo/analyze` | Phase 1 : détection de visage par IA + suppression de l'arrière-plan. Renvoie les points de repère du visage et les données mises en cache. |
| `POST` | `/api/v1/tools/image/passport-photo/generate` | Phase 2 : rognage, redimensionnement et disposition en mosaïque à partir de l'analyse mise en cache. Aucune réexécution de l'IA. |
| `POST` | `/api/v1/tools/image/gif-tools/info` | Récupère les métadonnées du GIF (nombre d'images, dimensions, durée) |
| `POST` | `/api/v1/tools/pdf/pdf-to-image/info` | Récupère les métadonnées du PDF (nombre de pages, dimensions) |
| `POST` | `/api/v1/tools/pdf/pdf-to-image/preview` | Génère un aperçu d'une page PDF spécifique |
| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/info` | Récupère les métadonnées du PDF pour le préréglage JPG dédié |
| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/preview` | Génère un aperçu de page PDF au format préréglé JPG |
| `POST` | `/api/v1/tools/pdf/pdf-to-png/info` | Récupère les métadonnées du PDF pour le préréglage PNG dédié |
| `POST` | `/api/v1/tools/pdf/pdf-to-png/preview` | Génère un aperçu de page PDF au format préréglé PNG |
| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/info` | Récupère les métadonnées du PDF pour le préréglage TIFF dédié |
| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/preview` | Génère un aperçu de page PDF au format préréglé TIFF |
| `POST` | `/api/v1/tools/image/svg-to-raster/batch` | Convertit en lot plusieurs SVG vers du matriciel |
| `POST` | `/api/v1/tools/image/image-enhancement/analyze` | Analyse la qualité de l'image et renvoie des recommandations d'amélioration |
| `POST` | `/api/v1/tools/image/optimize-for-web/preview` | Aperçu léger pour l'ajustement en direct des paramètres. Renvoie une image optimisée avec des en-têtes de taille. |
## Traitement par lots {#batch-processing}
Appliquez un outil générique compatible avec le traitement par lots à plusieurs fichiers à la fois. Renvoie une archive ZIP. Les routes personnalisées multi-fichiers ou multi-étapes, telles que la signature de PDF, l'OCR de PDF et les routes de préréglage PDF vers image, utilisent leur propre contrat de point de terminaison au lieu de la route générique `/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 concurrence est contrôlée par `CONCURRENT_JOBS` (par défaut : détecté automatiquement à partir des cœurs CPU). `MAX_BATCH_SIZE` limite le nombre de fichiers par lot (par défaut : 100 ; définissez 0 pour illimité).
## Pipelines {#pipelines}
### Exécuter un 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}}]}'
```
La sortie de chaque étape constitue l'entrée de l'étape suivante. Les pipelines autorisent 20 étapes par défaut, configurable via `MAX_PIPELINE_STEPS`. Définissez `MAX_PIPELINE_STEPS=0` pour supprimer la limite.
### Enregistrer et gérer les pipelines {#save-and-manage-pipelines}
| Méthode | Chemin | Description |
|--------|------|-------------|
| `POST` | `/api/v1/pipeline/save` | Enregistre un pipeline nommé (`name`, `description`, `steps[]`) |
| `GET` | `/api/v1/pipeline/list` | Liste les pipelines enregistrés (les administrateurs voient tout ; les utilisateurs voient les leurs) |
| `DELETE` | `/api/v1/pipeline/:id` | Supprime (propriétaire ou administrateur) |
| `GET` | `/api/v1/pipeline/tools` | Liste les ID d'outils valides pour les étapes de pipeline |
## Suivi de la progression {#progress-tracking}
Les tâches de longue durée, les outils mis en file d'attente, les tâches par lots et les pipelines émettent une progression en temps réel via Server-Sent Events. Le flux de progression est public et indexé par ID de tâche, de sorte que les clients n'ont pas besoin d'envoyer d'en-tête d'autorisation pour le lire.
```bash
# Connect to the SSE stream (jobId is in the JSON response body from the tool endpoint)
curl -N http://localhost:1349/api/v1/jobs/<jobId>/progress
```
Format des événements :
```
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":[]}
```
Vous pouvez demander l'annulation d'une tâche en file d'attente ou en cours d'exécution avec `POST /api/v1/jobs/:jobId/cancel`. La réponse est `{"canceled":true|false}`.
## Bibliothèque de fichiers {#file-library}
Stockage de fichiers persistant avec historique des versions.
| Méthode | Chemin | Description |
|--------|------|-------------|
| `POST` | `/api/v1/upload` | Téléverse des fichiers dans l'espace de travail (traitement temporaire) |
| `POST` | `/api/v1/files/upload` | Téléverse des fichiers dans la bibliothèque de fichiers persistante |
| `POST` | `/api/v1/files/save-result` | Enregistre le résultat du traitement d'un outil comme nouvelle version de fichier |
| `GET` | `/api/v1/files` | Liste les fichiers enregistrés (paginé, avec recherche) |
| `GET` | `/api/v1/files/:id` | Récupère les métadonnées du fichier + la chaîne de versions |
| `GET` | `/api/v1/files/:id/download` | Télécharge un fichier |
| `GET` | `/api/v1/files/:id/thumbnail` | Récupère une miniature JPEG de 300 px |
| `DELETE` | `/api/v1/files` | Supprime en masse des fichiers et leurs chaînes de versions (corps : `{ ids: [...] }`) |
| `POST` | `/api/v1/fetch-urls` | Récupère des URL distantes dans l'espace de travail pour les imports basés sur URL |
| `POST` | `/api/v1/preview` | Génère un aperçu WebP compatible avec le navigateur (pour les formats HEIC/HEIF/RAW) |
| `GET` | `/api/v1/files/:id/preview` | Diffuse un aperçu mis en cache ou généré, compatible avec le navigateur, pour un PDF, un document bureautique, une vidéo ou un fichier audio enregistré |
| `POST` | `/api/v1/preview/generate` | Génère à la demande un aperçu MP4 ou MP3 pour un fichier multimédia téléversé sans l'enregistrer au préalable |
| `GET` | `/api/v1/download/:jobId/:filename` | Télécharge un fichier traité depuis un espace de travail |
Pour enregistrer automatiquement le résultat d'un outil dans la bibliothèque, incluez `fileId` comme champ de formulaire multipart référençant un fichier existant de la bibliothèque. Le résultat traité sera enregistré comme nouvelle version.
## Gestion des clés d'API {#api-key-management}
| Méthode | Chemin | Accès | Description |
|--------|------|--------|-------------|
| `POST` | `/api/v1/api-keys` | Auth | Génère une nouvelle clé - affichée une seule fois |
| `GET` | `/api/v1/api-keys` | Auth | Liste les clés (name, id, lastUsedAt - pas la clé brute) |
| `DELETE` | `/api/v1/api-keys/:id` | Auth | Supprime une clé |
## Équipes {#teams}
| Méthode | Chemin | Accès | Description |
|--------|------|--------|-------------|
| `GET` | `/api/v1/teams` | Admin (`teams:manage`) | Liste les équipes |
| `POST` | `/api/v1/teams` | Admin (`teams:manage`) | Crée une équipe |
| `PUT` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Renomme une équipe |
| `DELETE` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Supprime une équipe (impossible de supprimer l'équipe par défaut ou les équipes ayant des membres) |
## Paramètres {#settings}
Configuration clé-valeur d'exécution (lecture par tout utilisateur authentifié, écriture par l'administrateur uniquement).
| Méthode | Chemin | Description |
|--------|------|-------------|
| `GET` | `/api/v1/settings` | Récupère tous les paramètres |
| `PUT` | `/api/v1/settings` | Met à jour en masse les paramètres (corps JSON avec des paires clé-valeur) |
| `GET` | `/api/v1/settings/:key` | Récupère un paramètre spécifique par clé |
Clés connues : `disabledTools` (tableau JSON d'ID d'outils), `enableExperimentalTools` (chaîne booléenne), `loginAttemptLimit` (nombre).
## Préférences {#preferences}
Les préférences par utilisateur sont distinctes des paramètres de l'instance. Tout utilisateur authentifié peut lire et mettre à jour sa propre carte de préférences.
| Méthode | Chemin | Description |
|--------|------|-------------|
| `GET` | `/api/v1/preferences` | Récupère les préférences de l'utilisateur actuel sous forme de `{ "preferences": { ... } }` |
| `PUT` | `/api/v1/preferences` | Insère ou met à jour une ou plusieurs clés de préférence pour l'utilisateur actuel |
## Rôles {#roles}
Gestion de rôles personnalisés avec des autorisations granulaires.
| Méthode | Chemin | Accès | Description |
|--------|------|--------|-------------|
| `GET` | `/api/v1/roles` | Admin (`audit:read`) | Liste tous les rôles avec le nombre d'utilisateurs |
| `POST` | `/api/v1/roles` | Admin (`security:manage`) | Crée un rôle personnalisé (`name`, `description`, `permissions`) |
| `PUT` | `/api/v1/roles/:id` | Admin (`security:manage`) | Met à jour un rôle personnalisé (impossible de modifier les rôles intégrés) |
| `DELETE` | `/api/v1/roles/:id` | Admin (`security:manage`) | Supprime un rôle personnalisé (impossible de supprimer les rôles intégrés ; les utilisateurs concernés reviennent au rôle `user`) |
Autorisations disponibles (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`.
## Journal d'audit {#audit-log}
Point de terminaison réservé aux administrateurs pour examiner les actions pertinentes en matière de sécurité.
| Méthode | Chemin | Accès | Description |
|--------|------|--------|-------------|
| `GET` | `/api/v1/audit-log` | Admin (`audit:read`) | Journal d'audit paginé avec filtres optionnels |
Paramètres de requête :
| Paramètre | Description |
|-----------|-------------|
| `page` | Numéro de page (par défaut : 1) |
| `limit` | Entrées par page (par défaut : 50, max : 100) |
| `action` | Filtre par type d'action (par exemple `ROLE_CREATED`, `ROLE_DELETED`) |
| `ip` | Filtre par adresse IP source |
| `from` | Filtre les entrées postérieures à cette date ISO 8601 |
| `to` | Filtre les entrées antérieures à cette date ISO 8601 |
## Analytique {#analytics}
| Méthode | Chemin | Accès | Description |
|--------|------|--------|-------------|
| `GET` | `/api/v1/config/analytics` | Public | Récupère la configuration d'analytique effective (clé PostHog, DSN Sentry, taux d'échantillonnage). Les clés, le DSN et l'ID d'instance sont vides lorsque l'analytique est désactivée, que ce soit par la compilation ou par le paramètre d'instance `analyticsEnabled`. |
| `POST` | `/api/v1/feedback` | Auth | Soumet un retour utilisateur explicite au projet PostHog configuré sous forme de `feedback_submitted`. La route respecte le verrou d'analytique, limite le débit des soumissions, retire les champs de contact sauf si `contactOk` est vrai, et n'accepte jamais le contenu des fichiers, les noms de fichiers, les chemins de téléversement ni le texte d'erreur privé brut. Lorsque l'analytique est désactivée, elle renvoie `{ "ok": true, "accepted": false }`. |
| `PUT` | `/api/v1/settings` | Admin (`settings:write`) | Définit le refus à l'échelle de l'instance. Envoyez un corps JSON `{ "analyticsEnabled": "false" }` pour désactiver l'analytique pour tout le monde, ou `"true"` pour la réactiver. |
## Fonctionnalités / Bundles d'IA {#features-ai-bundles}
Gérez les bundles de fonctionnalités d'IA (installez/désinstallez des packages de modèles d'IA dans l'environnement Docker). Préférez le point de terminaison d'installation au niveau de l'outil lorsque vous activez un outil depuis une automatisation personnalisée : certains outils d'IA nécessitent plus d'un bundle partagé, et ce point de terminaison ignore les bundles déjà installés en ne mettant en file d'attente que ceux qui manquent.
| Méthode | Chemin | Accès | Description |
|--------|------|--------|-------------|
| `GET` | `/api/v1/features` | Auth | Liste tous les bundles de fonctionnalités et leur état d'installation |
| `POST` | `/api/v1/admin/features/:bundleId/install` | Admin (`features:manage`) | Installe un bundle de fonctionnalités (asynchrone, renvoie `jobId` pour le suivi de la progression) |
| `POST` | `/api/v1/admin/tools/:toolId/features/install` | Admin (`features:manage`) | Installe chaque bundle requis par un outil ; renvoie l'état par bundle (mis en file d'attente/ignoré) |
| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Admin (`features:manage`) | Désinstalle un bundle de fonctionnalités et nettoie les fichiers de modèle |
| `GET` | `/api/v1/admin/features/disk-usage` | Admin (`features:manage`) | Récupère l'utilisation totale du disque par les modèles d'IA |
| `POST` | `/api/v1/admin/features/import` | Admin (`features:manage`) | Importe une archive de bundle d'IA hors ligne |
## Opérations d'administration {#admin-operations}
Points de terminaison opérationnels pour l'observabilité, l'assistance, les rapports d'utilisation et l'état des sauvegardes.
| Méthode | Chemin | Accès | Description |
|--------|------|--------|-------------|
| `GET` | `/api/v1/admin/log-level` | Admin (`settings:write`) | Lit le niveau de journalisation d'exécution actuel |
| `POST` | `/api/v1/admin/log-level` | Admin (`settings:write`) | Change le niveau de journalisation d'exécution (`fatal`, `error`, `warn`, `info`, `debug`, `trace`, ou `silent`) |
| `GET` | `/api/v1/metrics` | Admin (`system:health`) | Métriques Prometheus au format texte |
| `GET` | `/api/v1/admin/support-bundle` | Admin (`system:health`) | Télécharge un ZIP de bundle de diagnostic d'assistance caviardé |
| `GET` | `/api/v1/admin/usage` | Admin (`audit:read`) | Données du tableau de bord d'utilisation, avec un paramètre de requête `days` optionnel |
| `GET` | `/api/v1/admin/backup-status` | Admin (`system:health`) | Lit les métadonnées de la dernière sauvegarde et l'état de fraîcheur |
| `POST` | `/api/v1/admin/backup-status` | Admin (`system:health`) | Enregistre une sauvegarde terminée (`type`, `sizeBytes` optionnel, `notes` optionnel) |
## API d'entreprise {#enterprise-apis}
Ces routes sont verrouillées par licence selon leur fonctionnalité d'entreprise associée. Elles exigent toujours l'autorisation SnapOtter indiquée.
| Méthode | Chemin | Accès | Description |
|--------|------|--------|-------------|
| `GET` | `/api/v1/enterprise/audit/export` | Admin (`audit:read`) | Exporte les entrées d'audit au format JSON ou CSV avec des filtres |
| `GET` | `/api/v1/enterprise/config/export` | Admin (`system:health`) | Exporte la configuration d'instance caviardée, les rôles personnalisés et les équipes |
| `POST` | `/api/v1/enterprise/config/import` | Admin (`system:health`) | Importe une configuration, avec exécution à blanc optionnelle |
| `GET` | `/api/v1/enterprise/ip-allowlist` | Admin (`security:manage`) | Lit la liste d'autorisation CIDR configurée |
| `PUT` | `/api/v1/enterprise/ip-allowlist` | Admin (`security:manage`) | Met à jour la liste d'autorisation CIDR avec prévention de l'auto-verrouillage |
| `GET` | `/api/v1/enterprise/legal-hold` | Admin (`compliance:manage`) | Liste les blocages juridiques des utilisateurs et des équipes |
| `PUT` | `/api/v1/enterprise/legal-hold` | Admin (`compliance:manage`) | Applique ou lève un blocage juridique sur un utilisateur ou une équipe |
| `POST` | `/api/v1/enterprise/scim/token` | Admin (`users:manage`) | Génère un jeton bearer SCIM, renvoyé une seule fois |
| `DELETE` | `/api/v1/enterprise/scim/token` | Admin (`users:manage`) | Révoque le jeton bearer SCIM actuel |
| `GET` | `/api/v1/enterprise/siem/config` | Admin (`webhooks:manage`) | Lit la configuration de transfert SIEM |
| `PUT` | `/api/v1/enterprise/siem/config` | Admin (`webhooks:manage`) | Met à jour la configuration de transfert SIEM |
| `GET` | `/api/v1/enterprise/webhooks` | Admin (`webhooks:manage`) | Liste les destinations de webhook |
| `POST` | `/api/v1/enterprise/webhooks` | Admin (`webhooks:manage`) | Crée une destination de webhook |
| `PUT` | `/api/v1/enterprise/webhooks/:index` | Admin (`webhooks:manage`) | Met à jour une destination de webhook |
| `DELETE` | `/api/v1/enterprise/webhooks/:index` | Admin (`webhooks:manage`) | Supprime une destination de webhook |
| `POST` | `/api/v1/enterprise/webhooks/:index/test` | Admin (`webhooks:manage`) | Envoie une charge utile de webhook de test |
| `POST` | `/api/v1/enterprise/users/:id/export` | Admin (`compliance:manage`) | Démarre une tâche d'export d'utilisateur RGPD |
| `GET` | `/api/v1/enterprise/users/:id/export/:jobId` | Admin (`compliance:manage`) | Lit l'état de l'export RGPD et l'URL de téléchargement |
| `DELETE` | `/api/v1/enterprise/users/:id/purge` | Admin (`compliance:manage`) | Purge définitivement les données d'un utilisateur après confirmation |
| `DELETE` | `/api/v1/enterprise/teams/:id/purge` | Admin (`compliance:manage`) | Purge définitivement les données d'une équipe après confirmation |
| `GET` | `/api/v1/admin/version` | Admin (`system:health`) | Lit les métadonnées de version de l'application, de la build, de Node et du schéma |
| `GET` | `/api/v1/admin/migrations/pending` | Admin (`system:health`) | Compare les migrations packagées avec les migrations appliquées |
| `GET` | `/api/v1/admin/upgrade-check` | Admin (`system:health`) | Exécute les vérifications de préparation à la mise à niveau |
### SCIM 2.0 {#scim-2-0}
Les points de terminaison de découverte SCIM sont publics. Les points de terminaison d'utilisateurs et de groupes exigent le jeton bearer SCIM généré ci-dessus.
| Méthode | Chemin | Accès | Description |
|--------|------|--------|-------------|
| `GET` | `/api/v1/scim/v2/ServiceProviderConfig` | Public | Capacités du serveur SCIM |
| `GET` | `/api/v1/scim/v2/Schemas` | Public | Découverte du schéma SCIM |
| `GET` | `/api/v1/scim/v2/ResourceTypes` | Public | Découverte des types de ressources SCIM |
| `GET` | `/api/v1/scim/v2/Users` | Jeton SCIM | Liste les utilisateurs, avec un filtre SCIM optionnel |
| `POST` | `/api/v1/scim/v2/Users` | Jeton SCIM | Crée un utilisateur |
| `GET` | `/api/v1/scim/v2/Users/:id` | Jeton SCIM | Récupère un utilisateur |
| `PUT` | `/api/v1/scim/v2/Users/:id` | Jeton SCIM | Remplace un utilisateur |
| `DELETE` | `/api/v1/scim/v2/Users/:id` | Jeton SCIM | Désactive un utilisateur en douceur |
| `GET` | `/api/v1/scim/v2/Groups` | Jeton SCIM | Liste les équipes en tant que groupes SCIM |
| `POST` | `/api/v1/scim/v2/Groups` | Jeton SCIM | Crée une équipe |
| `GET` | `/api/v1/scim/v2/Groups/:id` | Jeton SCIM | Récupère une équipe |
| `PUT` | `/api/v1/scim/v2/Groups/:id` | Jeton SCIM | Remplace une équipe et l'appartenance au groupe |
| `DELETE` | `/api/v1/scim/v2/Groups/:id` | Jeton SCIM | Supprime une équipe |
## Modèles de mèmes {#meme-templates}
API d'appui pour l'outil de génération de mèmes.
| Méthode | Chemin | Accès | Description |
|--------|------|--------|-------------|
| `GET` | `/api/v1/meme-templates` | Auth | Liste tous les modèles de mèmes disponibles avec les positions des zones de texte |
| `GET` | `/api/v1/meme-templates/full/:filename` | Auth | Sert l'image du modèle en taille réelle |
| `GET` | `/api/v1/meme-templates/thumbs/:filename` | Auth | Sert la miniature du modèle |
| `GET` | `/api/v1/meme-templates/fonts/:filename` | Auth | Sert le fichier de police utilisé pour le rendu du texte des mèmes |
## Réponses d'erreur {#error-responses}
Toutes les erreurs renvoient du JSON :
```json
{
"error": "Human-readable message",
"code": "MACHINE_READABLE_CODE"
}
```
| Statut | Signification |
|--------|---------|
| 400 | Requête invalide / échec de la validation |
| 401 | Non authentifié |
| 403 | Autorisations insuffisantes |
| 404 | Ressource introuvable |
| 413 | Fichier trop volumineux (voir `MAX_UPLOAD_SIZE_MB`) |
| 422 | Échec du traitement après validation |
| 429 | Débit limité (voir `RATE_LIMIT_PER_MIN`) |
| 501 | Le bundle de fonctionnalités d'IA requis n'est pas installé (`FEATURE_NOT_INSTALLED`) |
| 500 | Erreur interne du serveur |