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

All 181 docs markdown files translated into 20 languages (apps/docs/<locale>/**). Companion to the i18n code PR; admin-merged because the file count exceeds GitHub's per-PR CI trigger limit. Validated by pnpm i18n:check (all surfaces, 0 stale/missing) and a clean all-locale docs build.
2026-08-03 07:46:42 +02:00 · 2026-07-11 13:52:47 +08:00
parent 00b651c9f8
commit 4963ab3bbd
3620 changed files with 306134 additions and 0 deletions
@@ -0,0 +1,438 @@
+---
+description: "Referencia del motor de IA con todas las herramientas de ML locales. Eliminación de fondo, escalado, OCR, detección de rostros, restauración de fotos y más."
+i18n_source_hash: 14728c1dcd05
+i18n_provenance: machine
+i18n_output_hash: 73caa426553a
+---
+
+# Referencia del motor de IA {#ai-engine-reference}
+
+El paquete `@snapotter/ai` conecta Node.js con un **sidecar de Python persistente** para todas las operaciones de ML. El proceso despachador permanece activo entre solicitudes para lograr un arranque en caliente rápido. NVIDIA CUDA se detecta automáticamente al inicio y se usa cuando está disponible; de lo contrario, las herramientas de IA se ejecutan en la CPU.
+
+La aceleración con iGPU de Intel/AMD a través de VA-API, Quick Sync u OpenCL no es compatible hoy con la inferencia de IA. Mapear `/dev/dri` dentro de un contenedor no acelera estas herramientas del sidecar de Python a menos que haya disponible una GPU NVIDIA compatible con CUDA.
+
+19 herramientas de IA del sidecar de Python en cuatro modalidades (imagen, audio, video, documento), más 2 herramientas con capacidades de IA opcionales. Todos los modelos se ejecutan localmente: no se requiere internet tras la descarga inicial del modelo.
+
+## Arquitectura {#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 perfil de despachador "docs" independiente reemplaza la lista de permitidos de IA con scripts de procesamiento de documentos (`doc_pagecount`, `doc_health`, `doc_flatten`, `doc_redact`, `doc_text`, `doc_to_word`, `doc_metadata`, `doc_html_pdf`) y omite las importaciones pesadas de ML.
+
+**Tiempos de espera:** 300 s por defecto; OCR y la eliminación de fondo con BiRefNet obtienen 600 s.
+
+## Paquetes de funciones {#feature-bundles}
+
+Los modelos de IA se empaquetan por pila de dependencias compartida, no un archivo por herramienta. Un paquete de funciones puede habilitar varias herramientas cuando estas usan la misma familia de modelos, los mismos wheels de Python o las mismas librerías nativas. Esto mantiene la imagen Docker de la versión más pequeña y evita almacenar copias duplicadas de los mismos modelos de matting de fondo, detección de rostros, OCR, restauración y voz.
+
+La imagen Docker incluye la aplicación más el entorno de ejecución común. Los archivos de modelos grandes se descargan bajo demanda en el volumen persistente `/data/ai`, y luego los reutiliza cada herramienta que los necesite. Si un paquete ya está instalado porque otra herramienta lo necesitó, habilitar una nueva herramienta dependiente no vuelve a descargar ese paquete.
+
+Cada herramienta de IA requiere uno o más paquetes de funciones antes de poder ejecutarse. La interfaz de administración instala por herramienta a través de `POST /api/v1/admin/tools/:toolId/features/install`, que resuelve la lista completa de paquetes, omite los paquetes que ya están instalados y encola solo las descargas faltantes. Por ejemplo, habilitar Foto de pasaporte en una instancia nueva encola `background-removal` y `face-detection`; habilitarla después de que Eliminación de fondo ya está instalado encola solo `face-detection`.
+
+| Paquete | Tamaño | Grupo de dependencias compartidas | Herramientas que lo usan |
+|--------|------|-------------------------|-------------------|
+| `background-removal` | 4-5 GB | matting de fondo rembg / BiRefNet | remove-background, passport-photo, transparency-fixer, background-replace, blur-background |
+| `face-detection` | 200-300 MB | detección de rostros y puntos de referencia de MediaPipe | blur-faces, red-eye-removal, smart-crop |
+| `object-eraser-colorize` | 1-2 GB | inpainting/outpainting con LaMa y DDColor | erase-object, colorize, ai-canvas-expand |
+| `upscale-enhance` | 5-6 GB | RealESRGAN, GFPGAN / CodeFormer, reducción de ruido | upscale, enhance-faces, noise-removal |
+| `photo-restoration` | 4-5 GB | reparación de arañazos y pipeline de restauración | restore-photo |
+| `ocr` | 5-6 GB | pila de OCR PaddleOCR / Tesseract | ocr, ocr-pdf |
+| `transcription` | ~600 MB | modelos de voz a texto faster-whisper | transcribe-audio, auto-subtitles |
+
+Herramientas con dependencias entre paquetes:
+
+| Herramienta | Paquetes requeridos | Motivo |
+|------|------------------|-----|
+| `passport-photo` | `background-removal`, `face-detection` | Elimina el fondo y luego usa los puntos de referencia del rostro para encuadrar el recorte según las reglas de fotos de pasaporte y de identificación. |
+| `enhance-faces` | `upscale-enhance`, `face-detection` | Detecta rostros antes de ejecutar la mejora con GFPGAN o CodeFormer en las regiones de rostro seleccionadas. |
+
+Una herramienta está disponible solo cuando todos sus paquetes requeridos están instalados. Las instalaciones parciales son válidas y se manejan de forma incremental: los paquetes instalados se reutilizan, los paquetes faltantes se muestran como descargas y las instalaciones en cola se ejecutan una a la vez para que el entorno de Python compartido no se modifique de forma concurrente.
+
+---
+
+## Eliminación de fondo {#background-removal}
+
+**Ruta de la herramienta:** `remove-background`  
+**Modelo:** rembg con BiRefNet (por defecto) o variantes de U2-Net
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `model` | string | - | Variante del modelo (anulación opcional) |
+| `backgroundType` | string | `"transparent"` | Uno de: `transparent`, `color`, `gradient`, `blur`, `image` |
+| `backgroundColor` | string | - | Color hexadecimal para fondo sólido |
+| `gradientColor1` | string | - | Primer color del degradado |
+| `gradientColor2` | string | - | Segundo color del degradado |
+| `gradientAngle` | number | - | Ángulo del degradado en grados |
+| `blurEnabled` | boolean | - | Activar el efecto de desenfoque de fondo |
+| `blurIntensity` | number (0-100) | - | Intensidad del desenfoque |
+| `shadowEnabled` | boolean | - | Activar la sombra proyectada sobre el sujeto |
+| `shadowOpacity` | number (0-100) | - | Opacidad de la sombra |
+| `outputFormat` | string | - | Formato de salida: `png`, `webp` o `avif` |
+| `edgeRefine` | integer (0-3) | - | Nivel de refinamiento de bordes |
+| `decontaminate` | boolean | - | Eliminar la contaminación de color de los bordes |
+
+## Reemplazo de fondo {#background-replace}
+
+**Ruta de la herramienta:** `background-replace`  
+**Modelo:** rembg / BiRefNet (compartido con remove-background)
+
+Elimina el fondo y lo reemplaza por un color sólido o un degradado.
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `backgroundType` | `"color"` \| `"gradient"` | `"color"` | Modo de fondo |
+| `color` | string | `"#ffffff"` | Color hexadecimal del fondo (cuando `backgroundType` es `color`) |
+| `gradientColor1` | string | - | Primer color hexadecimal del degradado |
+| `gradientColor2` | string | - | Segundo color hexadecimal del degradado |
+| `gradientAngle` | integer (0-360) | `180` | Ángulo del degradado en grados |
+| `feather` | integer (0-20) | `0` | Radio de difuminado de bordes |
+| `format` | `"png"` \| `"webp"` | `"png"` | Formato de salida |
+
+## Desenfocar fondo {#blur-background}
+
+**Ruta de la herramienta:** `blur-background`  
+**Modelo:** rembg / BiRefNet (compartido con remove-background)
+
+Desenfoca el fondo mientras mantiene nítido al sujeto.
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `intensity` | integer (1-100) | `50` | Intensidad del desenfoque |
+| `feather` | integer (0-20) | `0` | Radio de difuminado de bordes |
+| `format` | `"png"` \| `"webp"` | `"png"` | Formato de salida |
+
+## Escalado de imagen {#image-upscaling}
+
+**Ruta de la herramienta:** `upscale`  
+**Modelo:** RealESRGAN (con respaldo Lanczos cuando no está disponible)
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `scale` | number | `2` | Factor de escalado |
+| `model` | string | `"auto"` | Variante del modelo |
+| `faceEnhance` | boolean | `false` | Aplicar una pasada de mejora de rostros con GFPGAN |
+| `denoise` | number | `0` | Intensidad de la reducción de ruido |
+| `format` | string | `"auto"` | Anulación del formato de salida |
+| `quality` | number | `95` | Calidad de salida (1-100) |
+
+## OCR / Extracción de texto {#ocr-text-extraction}
+
+**Ruta de la herramienta:** `ocr`  
+**Modelos:** Tesseract (rápido), PaddleOCR PP-OCRv5 (equilibrado), PaddleOCR-VL 1.5 (mejor)
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Nivel de procesamiento |
+| `language` | string | `"auto"` | Idioma: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
+| `enhance` | boolean | `true` | Preprocesar la imagen para mejorar la precisión del OCR |
+| `engine` | string | - | Obsoleto. Asigna `tesseract` a `fast`, y `paddleocr` a `balanced` |
+
+Devuelve resultados estructurados con cuadros delimitadores, puntuaciones de confianza y bloques de texto extraídos.
+
+## OCR de PDF {#pdf-ocr}
+
+**Ruta de la herramienta:** `ocr-pdf`  
+**Modelos:** El mismo sistema de niveles que el OCR de imágenes
+
+Extrae texto de documentos PDF escaneados usando OCR con IA, página por página.
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `quality` | `"fast"` \| `"balanced"` \| `"best"` | `"balanced"` | Nivel de procesamiento |
+| `language` | string | `"auto"` | Idioma: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko` |
+| `pages` | string | `"all"` | Selección de páginas: `"all"`, `"1-3"`, `"1,3,5"` |
+
+## Desenfoque de rostros / PII {#face-pii-blur}
+
+**Ruta de la herramienta:** `blur-faces`  
+**Modelo:** detección de rostros de MediaPipe
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `blurRadius` | number (1-100) | `30` | Radio del desenfoque gaussiano |
+| `sensitivity` | number (0-1) | `0.5` | Umbral de confianza de detección |
+
+## Mejora de rostros {#face-enhancement}
+
+**Ruta de la herramienta:** `enhance-faces`  
+**Modelos:** GFPGAN, CodeFormer
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `model` | `"auto"` \| `"gfpgan"` \| `"codeformer"` | `"auto"` | Modelo de mejora |
+| `strength` | number (0-1) | `0.8` | Intensidad de la mejora |
+| `sensitivity` | number (0-1) | `0.5` | Umbral de detección de rostros |
+| `onlyCenterFace` | boolean | `false` | Mejorar solo el rostro más central |
+
+## Coloración con IA {#ai-colorization}
+
+**Ruta de la herramienta:** `colorize`  
+**Modelo:** DDColor (con respaldo OpenCV DNN)
+
+Convierte fotos en blanco y negro o en escala de grises a color completo.
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `intensity` | number (0-1) | `1.0` | Intensidad de la saturación de color |
+| `model` | `"auto"` \| `"ddcolor"` \| `"opencv"` | `"auto"` | Variante del modelo |
+
+## Eliminación de ruido {#noise-removal}
+
+**Ruta de la herramienta:** `noise-removal`  
+**Modelo:** SCUNet (pipeline de reducción de ruido por niveles)
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `tier` | `"quick"` \| `"balanced"` \| `"quality"` \| `"maximum"` | `"balanced"` | Nivel de procesamiento |
+| `strength` | number (0-100) | `50` | Intensidad de la reducción de ruido |
+| `detailPreservation` | number (0-100) | `50` | Cuánto detalle preservar; un valor más alto conserva más textura |
+| `colorNoise` | number (0-100) | `30` | Intensidad de la reducción de ruido de color |
+| `format` | string | `"original"` | Formato de salida: `original`, `png`, `jpeg`, `webp`, `avif`, `jxl` |
+| `quality` | number (1-100) | `90` | Calidad de codificación de salida |
+
+## Eliminación de ojos rojos {#red-eye-removal}
+
+**Ruta de la herramienta:** `red-eye-removal`
+
+Detecta los puntos de referencia del rostro, localiza las regiones de los ojos y corrige la sobresaturación del canal rojo.
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `sensitivity` | number (0-100) | `50` | Umbral de detección de píxeles rojos |
+| `strength` | number (0-100) | `70` | Intensidad de la corrección |
+| `format` | string | - | Anulación del formato de salida (opcional) |
+| `quality` | number (1-100) | `90` | Calidad de salida |
+
+## Restauración de fotos {#photo-restoration}
+
+**Ruta de la herramienta:** `restore-photo`
+
+Pipeline de varios pasos para fotos antiguas o dañadas: detección y reparación de arañazos/roturas, mejora de rostros, reducción de ruido y coloración opcional.
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `scratchRemoval` | boolean | `true` | Detectar y reparar arañazos, roturas |
+| `faceEnhancement` | boolean | `true` | Aplicar una pasada de mejora de rostros |
+| `fidelity` | number (0-1) | `0.7` | Intensidad de la mejora de rostros (mayor = más conservador) |
+| `denoise` | boolean | `true` | Aplicar una pasada de reducción de ruido |
+| `denoiseStrength` | number (0-100) | `25` | Intensidad de la reducción de ruido |
+| `colorize` | boolean | `false` | Colorizar tras la restauración |
+| `colorizeStrength` | number (0-100) | `85` | Intensidad de la coloración |
+
+## Foto de pasaporte {#passport-photo}
+
+**Ruta de la herramienta:** `passport-photo`  
+**Modelos:** puntos de referencia del rostro de MediaPipe + eliminación de fondo con BiRefNet
+
+Flujo de trabajo en dos fases: analizar (detectar rostro + eliminar fondo) y luego generar (recortar, redimensionar, mosaico). Admite más de 37 países en 6 regiones.
+
+### Fase 1: Analizar {#phase-1-analyze}
+
+`POST /api/v1/tools/image/passport-photo/analyze`
+
+Acepta un archivo de imagen (multipart). Devuelve los datos de puntos de referencia del rostro, una vista previa en base64 y las dimensiones de la imagen.
+
+### Fase 2: Generar {#phase-2-generate}
+
+`POST /api/v1/tools/image/passport-photo/generate`
+
+Acepta un cuerpo JSON con los resultados de la Fase 1 más los ajustes de generación:
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `jobId` | string | (requerido) | ID del trabajo de la Fase 1 |
+| `filename` | string | (requerido) | Nombre de archivo original de la Fase 1 |
+| `countryCode` | string | (requerido) | Código de país ISO (p. ej., `US`, `GB`, `IN`) |
+| `documentType` | string | `"passport"` | Tipo de documento |
+| `bgColor` | string | `"#FFFFFF"` | Color de fondo hexadecimal |
+| `printLayout` | string | `"none"` | Diseño de impresión: `none`, `4x6`, `a4`, `letter` |
+| `maxFileSizeKb` | number | `0` | Tamaño máximo de archivo en KB (0 = sin límite) |
+| `dpi` | number (72-1200) | `300` | DPI de salida |
+| `customWidthMm` | number | - | Ancho personalizado en mm (anula la especificación del país) |
+| `customHeightMm` | number | - | Alto personalizado en mm (anula la especificación del país) |
+| `zoom` | number (0.5-3) | `1` | Factor de zoom |
+| `adjustX` | number | `0` | Ajuste de la posición horizontal |
+| `adjustY` | number | `0` | Ajuste de la posición vertical |
+| `landmarks` | object | (requerido) | Puntos de referencia de la Fase 1 |
+| `imageWidth` | number | (requerido) | Ancho de imagen de la Fase 1 |
+| `imageHeight` | number | (requerido) | Alto de imagen de la Fase 1 |
+
+## Borrado de objetos (inpainting) {#object-erasing-inpainting}
+
+**Ruta de la herramienta:** `erase-object`  
+**Modelo:** LaMa vía ONNX Runtime
+
+La máscara se envía como una **segunda parte de archivo** (nombre de campo `mask`), no como base64. Los píxeles blancos en la máscara indican las áreas a borrar. Los ajustes `format` y `quality` se envían como campos de formulario de nivel superior.
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `file` | file | (requerido) | Imagen de origen (multipart) |
+| `mask` | file | (requerido) | Imagen de máscara (multipart, nombre de campo `mask`, blanco = borrar) |
+| `format` | string | `"auto"` | Formato de salida: `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl` |
+| `quality` | integer (1-100) | `95` | Calidad de salida |
+
+Acelerado por CUDA cuando hay disponible una GPU NVIDIA.
+
+## Expansión de lienzo con IA {#ai-canvas-expand}
+
+**Ruta de la herramienta:** `ai-canvas-expand`  
+**Modelo:** outpainting basado en LaMa
+
+Expande el lienzo de una imagen en cualquier dirección y rellena las áreas nuevas con contenido generado por IA que coincide con la imagen existente.
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `extendTop` | integer | `0` | Píxeles a extender por arriba |
+| `extendRight` | integer | `0` | Píxeles a extender por la derecha |
+| `extendBottom` | integer | `0` | Píxeles a extender por abajo |
+| `extendLeft` | integer | `0` | Píxeles a extender por la izquierda |
+| `tier` | `"fast"` \| `"balanced"` \| `"high"` | `"balanced"` | Nivel de calidad |
+| `format` | string | `"auto"` | Formato de salida: `auto`, `png`, `jpg`, `jpeg`, `webp`, `tiff`, `gif`, `avif`, `heic`, `heif`, `jxl` |
+| `quality` | integer (1-100) | `95` | Calidad de salida |
+
+Al menos una dirección de extensión debe ser mayor que 0.
+
+## Recorte inteligente {#smart-crop}
+
+**Ruta de la herramienta:** `smart-crop`  
+**Modelo:** detección de rostros de MediaPipe (solo en modo rostro)
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `mode` | string | `"subject"` | Estrategia de recorte: `subject`, `face`, `trim` |
+| `strategy` | `"attention"` \| `"entropy"` | `"attention"` | Estrategia para el modo sujeto |
+| `width` | integer | - | Ancho de salida |
+| `height` | integer | - | Alto de salida |
+| `padding` | integer (0-50) | `0` | Porcentaje de relleno alrededor del sujeto |
+| `facePreset` | string | `"head-shoulders"` | Encuadre predefinido cuando `mode=face` |
+| `sensitivity` | number (0-1) | `0.5` | Umbral de detección de rostros |
+| `threshold` | integer (0-255) | `30` | Umbral de detección de fondo (modo recorte) |
+| `padToSquare` | boolean | `false` | Rellenar el resultado recortado hasta un cuadrado |
+| `padColor` | string | `"#ffffff"` | Color de fondo para el relleno cuadrado |
+| `targetSize` | integer | - | Tamaño objetivo para la salida rellenada (píxeles) |
+| `quality` | integer (1-100) | - | Calidad de salida |
+
+Los valores heredados de `mode`, `attention` y `content`, se aceptan y se asignan a `subject` y `trim` respectivamente.
+
+**Ajustes predefinidos de rostro:**
+
+| Ajuste predefinido | Mejor para |
+|--------|---------|
+| `closeup` | Retratos de cabeza |
+| `head-shoulders` | Fotos de perfil |
+| `upper-body` | LinkedIn / formal |
+| `half-body` | Parte superior completa del cuerpo |
+
+## Transcribir audio {#transcribe-audio}
+
+**Ruta de la herramienta:** `transcribe-audio`  
+**Modelo:** faster-whisper
+
+Convierte voz en texto. Admite formatos de salida de texto plano, SRT y VTT.
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `language` | string | `"auto"` | Idioma: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
+| `outputFormat` | `"txt"` \| `"srt"` \| `"vtt"` | `"txt"` | Formato de salida |
+
+## Subtítulos automáticos {#auto-subtitles}
+
+**Ruta de la herramienta:** `auto-subtitles`  
+**Modelo:** faster-whisper (extrae el audio del video y luego lo transcribe)
+
+Genera archivos de subtítulos a partir de la pista de audio de un video.
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `language` | string | `"auto"` | Idioma: `auto`, `en`, `de`, `fr`, `es`, `zh`, `ja`, `ko`, `id`, `th`, `vi` |
+| `format` | `"srt"` \| `"vtt"` | `"srt"` | Formato de subtítulos de salida |
+
+## Corrector de transparencia PNG {#png-transparency-fixer}
+
+**Ruta de la herramienta:** `transparency-fixer`  
+**Modelo:** matting HR de BiRefNet (resolución 2048x2048)
+
+Corrige los PNG con "falsa transparencia", donde se eliminó el fondo pero quedaron bordes irregulares, halos o artefactos semitransparentes. Usa el modelo de matting de alta resolución de BiRefNet para producir un canal alfa limpio y luego aplica un procesamiento de eliminación de bordes configurable para quitar la contaminación de color a lo largo de los bordes.
+
+**Cadena de respaldo ante OOM:** Si el matting HR de BiRefNet supera la memoria disponible, la herramienta recurre automáticamente a `birefnet-general`, y luego a `u2net`.
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `defringe` | number (0-100) | `30` | Intensidad de la eliminación de bordes para quitar la contaminación de color |
+| `outputFormat` | `"png"` \| `"webp"` | `"png"` | Formato de imagen de salida |
+| `removeWatermark` | boolean | `false` | Aplicar preprocesamiento de eliminación de marca de agua (filtro de mediana) |
+
+```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"}'
+```
+
+---
+
+## Herramientas con capacidades de IA opcionales {#tools-with-optional-ai-capabilities}
+
+Las siguientes herramientas no son herramientas del sidecar de Python, pero usan funciones de IA cuando se activan ciertas opciones.
+
+### Mejora de imagen {#image-enhancement}
+
+**Ruta de la herramienta:** `image-enhancement`  
+**Motor:** Basado en análisis (histograma y estadísticas de Sharp)
+
+Analiza la imagen y aplica correcciones automáticas de exposición, contraste, balance de blancos, saturación, nitidez y ruido. Admite modos específicos de escena.
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `mode` | `"auto"` \| `"portrait"` \| `"landscape"` \| `"low-light"` \| `"food"` \| `"document"` | `"auto"` | Modo de escena para ajustar las correcciones |
+| `intensity` | number (0-100) | `50` | Intensidad general de la corrección |
+| `corrections.exposure` | boolean | `true` | Aplicar corrección de exposición |
+| `corrections.contrast` | boolean | `true` | Aplicar corrección de contraste |
+| `corrections.whiteBalance` | boolean | `true` | Aplicar corrección de balance de blancos |
+| `corrections.saturation` | boolean | `true` | Aplicar corrección de saturación |
+| `corrections.sharpness` | boolean | `true` | Aplicar corrección de nitidez |
+| `corrections.denoise` | boolean | `true` | Aplicar reducción de ruido |
+| `deepEnhance` | boolean | `false` | Activar la eliminación de ruido con IA vía SCUNet (requiere el paquete `upscale-enhance`) |
+
+Hay disponible un endpoint de análisis adicional en `POST /api/v1/tools/image/image-enhancement/analyze` que devuelve las correcciones detectadas sin aplicarlas.
+
+### Redimensionado con reconocimiento de contenido (seam carving) {#content-aware-resize-seam-carving}
+
+**Ruta de la herramienta:** `content-aware-resize`  
+**Motor:** binario `caire` de Go (no Python: sin beneficio de GPU)
+
+Redimensiona imágenes de forma inteligente eliminando costuras de baja energía, preservando el contenido importante.
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `width` | number | - | Ancho objetivo |
+| `height` | number | - | Alto objetivo |
+| `protectFaces` | boolean | `false` | Proteger las regiones de rostro detectadas (requiere el paquete `face-detection`) |
+| `blurRadius` | number (0-20) | `4` | Predesenfoque para el cálculo de energía |
+| `sobelThreshold` | number (1-20) | `2` | Umbral de sensibilidad de bordes |
+| `square` | boolean | `false` | Forzar salida cuadrada |
@@ -0,0 +1,211 @@
+---
+description: "Referencia de operaciones del motor de imágenes. Todas las operaciones de procesamiento de imágenes basadas en Sharp y sus parámetros."
+i18n_source_hash: 42febdf85fa8
+i18n_provenance: human
+i18n_output_hash: fbd5ae93bf8b
+---
+
+# Motor de imágenes {#image-engine}
+
+El paquete `@snapotter/image-engine` gestiona todas las operaciones de imagen que no son de IA. Envuelve [Sharp](https://sharp.pixelplumbing.com/) y se ejecuta por completo en el proceso, sin dependencias externas.
+
+## Operaciones {#operations}
+
+### resize {#resize}
+
+Escala una imagen a dimensiones específicas o por porcentaje.
+
+| Parámetro | Tipo | Descripción |
+|---|---|---|
+| `width` | number | Ancho objetivo en píxeles |
+| `height` | number | Alto objetivo en píxeles |
+| `fit` | string | `cover`, `contain`, `fill`, `inside` o `outside` |
+| `withoutEnlargement` | boolean | Si es verdadero, no ampliará imágenes más pequeñas |
+| `percentage` | number | Escalar por porcentaje en lugar de dimensiones absolutas |
+
+Puedes establecer `width`, `height` o ambos. Si solo estableces uno, el otro se calcula para mantener la relación de aspecto.
+
+### crop {#crop}
+
+Recorta una región rectangular de la imagen.
+
+| Parámetro | Tipo | Descripción |
+|---|---|---|
+| `left` | number | Desplazamiento X desde el borde izquierdo |
+| `top` | number | Desplazamiento Y desde el borde superior |
+| `width` | number | Ancho del área de recorte |
+| `height` | number | Alto del área de recorte |
+| `unit` | string | `px` (por defecto) o `percent` |
+
+### rotate {#rotate}
+
+Rota la imagen un ángulo determinado.
+
+| Parámetro | Tipo | Descripción |
+|---|---|---|
+| `angle` | number | Ángulo de rotación en grados (0-360) |
+| `background` | string | Color de relleno para el área expuesta (por defecto: `#000000`). Solo se aplica a ángulos que no sean de 90 grados. |
+
+### flip {#flip}
+
+Refleja la imagen en horizontal, en vertical o en ambas direcciones. Al menos una debe ser verdadera.
+
+| Parámetro | Tipo | Descripción |
+|---|---|---|
+| `horizontal` | boolean | Reflejar de izquierda a derecha |
+| `vertical` | boolean | Reflejar de arriba a abajo |
+
+### convert {#convert}
+
+Cambia el formato de la imagen.
+
+| Parámetro | Tipo | Descripción |
+|---|---|---|
+| `format` | string | Formato objetivo: `jpg`, `png`, `webp`, `avif`, `tiff`, `gif`, `jxl`, `heic`, `heif`, `bmp`, `ico`, `jp2`, `qoi` |
+| `quality` | number | Calidad de compresión (1-100, se aplica a los formatos con pérdida) |
+
+Los primeros siete formatos (de `jpg` a `jxl`) los codifica Sharp en el proceso. Los formatos restantes usan codificadores externos en la capa de la API: `heic`/`heif` mediante heif-enc, `bmp`/`ico` mediante ImageMagick, `jp2` mediante opj_compress y `qoi` mediante un códec TypeScript en línea.
+
+### compress {#compress}
+
+Reduce el tamaño del archivo manteniendo el mismo formato.
+
+| Parámetro | Tipo | Descripción |
+|---|---|---|
+| `quality` | number | Calidad objetivo (1-100) |
+| `targetSizeBytes` | number | Tamaño de archivo objetivo opcional en bytes |
+| `format` | string | Anulación de formato opcional |
+
+### strip-metadata {#strip-metadata}
+
+Elimina los metadatos EXIF, IPTC, XMP e ICC de la imagen. Sin parámetros (o con `stripAll: true`), elimina todo. Pasa banderas individuales para una eliminación selectiva.
+
+| Parámetro | Tipo | Descripción |
+|---|---|---|
+| `stripAll` | boolean | Eliminar todos los metadatos (por defecto cuando no se establece ninguna bandera) |
+| `stripExif` | boolean | Eliminar los datos EXIF (incluido el GPS si `stripGps` no se establece por separado) |
+| `stripGps` | boolean | Eliminar los datos de ubicación GPS |
+| `stripIcc` | boolean | Eliminar el perfil de color ICC |
+| `stripXmp` | boolean | Eliminar los metadatos XMP |
+
+### Ajustes de color {#color-adjustments}
+
+Estas operaciones modifican las propiedades de color de una imagen. Cada una toma un único valor numérico.
+
+| Operación | Parámetro | Rango | Descripción |
+|---|---|---|---|
+| `brightness` | `value` | -100 a 100 | Ajustar el brillo |
+| `contrast` | `value` | -100 a 100 | Ajustar el contraste |
+| `saturation` | `value` | -100 a 100 | Ajustar la saturación de color |
+
+### Filtros de color {#color-filters}
+
+Estos aplican una transformación de color fija. No toman parámetros.
+
+| Operación | Descripción |
+|---|---|
+| `grayscale` | Convertir a escala de grises |
+| `sepia` | Aplicar un tono sepia |
+| `invert` | Invertir todos los colores |
+
+### Canales de color {#color-channels}
+
+Ajusta los canales de color RGB individuales. Los valores son multiplicadores donde 100 = sin cambios.
+
+| Parámetro | Tipo | Descripción |
+|---|---|---|
+| `red` | number | Multiplicador del canal rojo (0 a 200, 100 = sin cambios) |
+| `green` | number | Multiplicador del canal verde (0 a 200, 100 = sin cambios) |
+| `blue` | number | Multiplicador del canal azul (0 a 200, 100 = sin cambios) |
+
+### sharpen {#sharpen}
+
+Enfoque simple controlado por un único valor.
+
+| Parámetro | Tipo | Descripción |
+|---|---|---|
+| `value` | number | Intensidad del enfoque (0 a 100). Se asigna a un sigma gaussiano de 0,5-10. |
+
+### sharpen-advanced {#sharpen-advanced}
+
+Enfoque avanzado con tres métodos seleccionables y una pasada previa opcional de reducción de ruido.
+
+| Parámetro | Tipo | Descripción |
+|---|---|---|
+| `method` | string | `adaptive`, `unsharp-mask` o `high-pass` |
+| `sigma` | number | Radio del desenfoque gaussiano, 0,5-10 (adaptativo) |
+| `m1` | number | Enfoque de áreas planas, 0-10 (adaptativo) |
+| `m2` | number | Enfoque de áreas con textura, 0-20 (adaptativo) |
+| `x1` | number | Umbral plano/dentado, 0-10 (adaptativo) |
+| `y2` | number | Aclarado máximo (límite de halo), 0-50 (adaptativo) |
+| `y3` | number | Oscurecimiento máximo (límite de halo), 0-50 (adaptativo) |
+| `amount` | number | Porcentaje de intensidad, 0-500 (máscara de enfoque) |
+| `radius` | number | Radio de desenfoque, 0,1-5,0 (máscara de enfoque) |
+| `threshold` | number | Brillo mínimo de borde, 0-255 (máscara de enfoque) |
+| `strength` | number | Intensidad de mezcla, 0-100 (paso alto) |
+| `kernelSize` | number | `3` o `5` para el núcleo 3x3 / 5x5 (paso alto) |
+| `denoise` | string | Pasada previa de reducción de ruido: `off`, `light`, `medium` o `strong` |
+
+Los parámetros son específicos de cada método. Proporciona solo los relevantes para el método elegido.
+
+### color-blindness {#color-blindness}
+
+Simula una deficiencia de la visión de color usando una matriz de recombinación de color 3x3.
+
+| Parámetro | Tipo | Descripción |
+|---|---|---|
+| `type` | string | Uno de: `protanopia`, `deuteranopia`, `tritanopia`, `protanomaly`, `deuteranomaly`, `tritanomaly`, `achromatopsia`, `blueConeMonochromacy` |
+
+### edit-metadata {#edit-metadata}
+
+Escribe o elimina campos de metadatos EXIF/IPTC individuales sin borrar el bloque completo.
+
+| Parámetro | Tipo | Descripción |
+|---|---|---|
+| `artist` | string | Etiqueta EXIF Artist |
+| `copyright` | string | Etiqueta EXIF Copyright |
+| `imageDescription` | string | Etiqueta EXIF ImageDescription |
+| `software` | string | Etiqueta EXIF Software |
+| `dateTime` | string | Etiqueta EXIF DateTime |
+| `dateTimeOriginal` | string | Etiqueta EXIF DateTimeOriginal |
+| `clearGps` | boolean | Eliminar todas las etiquetas GPS |
+| `fieldsToRemove` | string[] | Lista de nombres de campos EXIF a eliminar |
+
+Todos los parámetros son opcionales. Los campos que figuran en `fieldsToRemove` se eliminan del bloque EXIF existente. Los campos establecidos mediante los parámetros con nombre se escriben (o se sobrescriben). Las claves binarias/inseguras como MakerNote se ignoran de forma silenciosa.
+
+## Detección de formato {#format-detection}
+
+El motor detecta los formatos de entrada automáticamente a partir de las cabeceras de los archivos, no solo de las extensiones. Esto significa que un archivo `.jpg` que en realidad es un PNG se gestionará correctamente. La detección usa un enfoque de varias capas: primero los bytes mágicos y luego la extensión del archivo como respaldo.
+
+SnapOtter admite **más de 55 formatos de entrada** y **13 formatos de salida**, incluidos 23 formatos RAW de cámara de más de 20 marcas, formatos profesionales (PSD, EPS, OpenEXR, HDR), códecs modernos (JPEG XL, AVIF, HEIC, QOI, JPEG 2000) y formatos científicos/de videojuegos (FITS, DDS). La decodificación la gestiona Sharp de forma nativa siempre que es posible, con respaldo automático a ImageMagick, LibRaw y decodificadores CLI especializados.
+
+Consulta la página [Formatos compatibles](/es/guide/supported-formats) para ver la lista completa.
+
+## Extracción de metadatos {#metadata-extraction}
+
+La herramienta `info` devuelve los metadatos de la imagen. Consulta [Información de la imagen](/es/tools/image/info) para ver la referencia completa de campos.
+
+```json
+{
+  "filename": "photo.jpg",
+  "fileSize": 2450000,
+  "width": 4032,
+  "height": 3024,
+  "format": "jpeg",
+  "channels": 3,
+  "hasAlpha": false,
+  "colorSpace": "srgb",
+  "density": 72,
+  "isProgressive": false,
+  "hasExif": true,
+  "hasIcc": true,
+  "hasXmp": false,
+  "bitDepth": "8",
+  "pages": 1,
+  "histogram": [
+    { "channel": "red", "min": 0, "max": 255, "mean": 128.45, "stdev": 52.31 },
+    { "channel": "green", "min": 2, "max": 253, "mean": 115.22, "stdev": 48.76 },
+    { "channel": "blue", "min": 0, "max": 250, "mean": 102.89, "stdev": 55.14 }
+  ]
+}
+```
@@ -0,0 +1,702 @@
+---
+description: "Referencia completa de la API REST. Endpoints de herramientas, procesamiento por lotes, pipelines, biblioteca de archivos, autenticación, equipos y operaciones de administración."
+i18n_source_hash: 8646977f7cc9
+i18n_provenance: machine
+i18n_output_hash: a9129e12a29c
+---
+
+# Referencia de la API REST {#rest-api-reference}
+
+La documentación interactiva de la API con ejemplos de peticiones y respuestas está disponible en [http://localhost:1349/api/docs](http://localhost:1349/api/docs).
+
+Especificaciones legibles por máquina:
+- `/api/v1/openapi.yaml` - especificación OpenAPI 3.1
+- `/llms.txt` - resumen apto para LLM
+- `/llms-full.txt` - documentación completa apta para LLM
+
+## Autenticación {#authentication}
+
+Todos los endpoints requieren autenticación salvo que `AUTH_ENABLED=false`.
+
+### Token de sesión {#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>"
+```
+
+Las sesiones expiran después de 7 días (configurable mediante `SESSION_DURATION_HOURS`).
+
+### Claves de 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>"
+```
+
+Las claves llevan el prefijo `si_` y se almacenan como hashes scrypt; la clave en bruto se muestra una vez y ya no se puede recuperar.
+
+### Endpoints de autenticación {#auth-endpoints}
+
+| Método | Ruta | Acceso | Descripción |
+|--------|------|--------|-------------|
+| `POST` | `/api/auth/login` | Público | Iniciar sesión y obtener un token de sesión |
+| `POST` | `/api/auth/logout` | Auth | Destruir la sesión actual |
+| `GET` | `/api/auth/session` | Auth | Validar la sesión actual |
+| `POST` | `/api/auth/change-password` | Auth | Cambiar la propia contraseña (invalida todas las demás sesiones y claves de API) |
+| `GET` | `/api/auth/users` | Admin | Listar todos los usuarios |
+| `POST` | `/api/auth/register` | Admin | Crear un nuevo usuario |
+| `PUT` | `/api/auth/users/:id` | Admin | Actualizar el rol o el equipo de un usuario |
+| `POST` | `/api/auth/users/:id/reset-password` | Admin | Restablecer la contraseña de un usuario |
+| `DELETE` | `/api/auth/users/:id` | Admin | Eliminar un usuario |
+| `GET` | `/api/v1/config/auth` | Público | Comprobar si la autenticación está habilitada (`{ authEnabled: bool }`) |
+| `POST` | `/api/auth/mfa/enroll` | Auth | Iniciar la inscripción de MFA con TOTP. Requiere la función enterprise `mfa` |
+| `POST` | `/api/auth/mfa/verify` | Auth | Confirmar la inscripción de MFA con un código TOTP |
+| `POST` | `/api/auth/mfa/complete` | Público | Completar un desafío de inicio de sesión de MFA pendiente |
+| `POST` | `/api/auth/mfa/disable` | Auth | Deshabilitar MFA para el usuario actual |
+| `POST` | `/api/auth/users/:id/mfa/reset` | Admin (`users:manage`) | Restablecer MFA para un usuario |
+| `GET` | `/api/auth/oidc/login` | Público | Iniciar el inicio de sesión OIDC cuando OIDC está habilitado |
+| `GET` | `/api/auth/oidc/callback` | Público | Callback de autorización OIDC |
+| `GET` | `/api/auth/saml/metadata` | Público | XML de metadatos del SP SAML cuando SAML está habilitado |
+| `GET` | `/api/auth/saml/login` | Público | Iniciar el inicio de sesión SAML |
+| `POST` | `/api/auth/saml/callback` | Público | Servicio consumidor de aserciones SAML |
+
+Cuando MFA está habilitado para un usuario, `POST /api/auth/login` devuelve `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` en lugar de un token de sesión. Envía ese `mfaToken` junto con un código TOTP o de recuperación a `/api/auth/mfa/complete`.
+
+### Permisos {#permissions}
+
+| Permiso | Admin | Usuario |
+|-----------|:-----:|:----:|
+| Usar herramientas | ✓ | ✓ |
+| Archivos/pipelines/claves de API propios | ✓ | ✓ |
+| Ver archivos/pipelines/claves de todos los usuarios | ✓ | - |
+| Escribir ajustes | ✓ | - |
+| Gestionar usuarios y equipos | ✓ | - |
+| Gestionar la marca | ✓ | - |
+
+## Comprobación de estado {#health-check}
+
+| Método | Ruta | Acceso | Descripción |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/health` | Público | Comprobación básica de estado. Devuelve `{"status":"healthy","version":"..."}` con 200, o `{"status":"unhealthy"}` con 503 si la base de datos no es accesible. |
+| `GET` | `/api/v1/readyz` | Público | Sonda de disponibilidad. Comprueba PostgreSQL, Redis, el espacio en disco y S3 cuando está configurado. Devuelve 503 cuando la instancia no debería recibir tráfico. |
+| `GET` | `/api/v1/admin/health` | Admin (`system:health`) | Diagnóstico detallado que incluye tiempo de actividad, modo de almacenamiento, estado de la base de datos, estado de la cola y disponibilidad de GPU. |
+
+## Uso de herramientas {#using-tools}
+
+Cada herramienta sigue el mismo patrón:
+
+```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>` es uno de `image`, `video`, `audio`, `pdf` o `files`.
+
+- La subida es `multipart/form-data`.
+- `settings` es una cadena JSON con opciones específicas de la herramienta.
+- `clientJobId` es un campo de formulario opcional para la correlación de progreso proporcionada por quien llama.
+- `fileId` es un campo de formulario opcional que referencia un elemento existente de la biblioteca de archivos. Cuando está presente, la salida procesada se guarda como una nueva versión y la respuesta incluye `savedFileId`.
+- **Las herramientas rápidas** normalmente devuelven 200 JSON: `{"jobId":"...","downloadUrl":"/api/v1/download/<jobId>/<filename>","originalSize":1234,"processedSize":567}`. Obtén el archivo procesado desde `downloadUrl`.
+- **Cualquier herramienta en cola** puede devolver 202 JSON si es de larga duración o supera la ventana de espera síncrona: `{"jobId":"...","async":true}`. Conéctate a SSE para el progreso y descarga cuando termine (consulta [Seguimiento del progreso](#progress-tracking)).
+- **Las rutas por lotes** devuelven un archivo ZIP transmitido directamente (con la cabecera `X-Job-Id`) para las herramientas registradas en el registro genérico por lotes.
+
+## Referencia de herramientas {#tools-reference}
+
+### Preajustes de conversión {#conversion-presets}
+
+El catálogo compartido incluye 83 endpoints de preajustes de conversión dedicados, como `jpg-to-png`, `mov-to-mp4`, `m4a-to-mp3`, `pdf-to-jpg` y `excel-to-csv`. Los preajustes son rutas de herramienta de primera clase:
+
+`POST /api/v1/tools/<section>/<presetId>`
+
+Cada preajuste fija el formato de salida y delega en una herramienta base como `convert`, `convert-video`, `extract-audio`, `convert-audio`, `image-to-pdf`, `pdf-to-image`, `svg-to-raster` o `convert-spreadsheet`. Consulta [Preajustes de conversión](/es/tools/conversion-presets) para ver la tabla de rutas completa y los ajustes opcionales.
+
+### Esenciales {#essentials}
+
+| ID de herramienta | Nombre | Ajustes clave |
+|---------|------|-------------|
+| `resize` | Redimensionar | `width`, `height`, `fit` (cover/contain/fill/inside/outside), `percentage`, `withoutEnlargement`, más 23 preajustes de redes sociales |
+| `crop` | Recortar | `left`, `top`, `width`, `height`, `unit` (px/percent) |
+| `rotate` | Girar y voltear | `angle`, `horizontal` (bool), `vertical` (bool) |
+| `convert` | Convertir | `format` (jpg/png/webp/avif/tiff/gif/heic/heif), `quality` |
+| `compress` | Comprimir | `mode` (quality/targetSize), `quality` (1–100), `targetSizeKb` |
+
+### Optimización {#optimization}
+
+| ID de herramienta | Nombre | Ajustes clave |
+|---------|------|-------------|
+| `optimize-for-web` | Optimizar para web | `format` (webp/jpeg/avif/png), `quality`, `maxWidth`, `maxHeight`, `progressive`, `stripMetadata` |
+| `strip-metadata` | Eliminar metadatos | - |
+| `edit-metadata` | Editar metadatos | `title`, `description`, `author`, `copyright`, `keywords`, `gps` (lat/lon), `dateTime` |
+| `bulk-rename` | Renombrado masivo | `pattern` (admite `{n}`, `{date}`, `{original}`), `startIndex`, `padding` |
+| `image-to-pdf` | Imagen a PDF | `pageSize` (A4/Letter/...), `orientation`, `margin`, `targetSize` ({value, unit}) |
+| `favicon` | Generador de favicon | `padding`, `backgroundColor`, `borderRadius` - genera todos los tamaños estándar |
+
+### Ajustes {#adjustments}
+
+| ID de herramienta | Nombre | Ajustes clave |
+|---------|------|-------------|
+| `adjust-colors` | Ajustar colores | `brightness`, `contrast`, `exposure`, `saturation`, `temperature`, `tint`, `hue`, `sharpness`, `red`, `green`, `blue`, `effect` (none/grayscale/sepia/invert) |
+| `sharpening` | Enfoque | `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` | Reemplazar color | `sourceColor`, `targetColor` (reemplazo), `makeTransparent`, `tolerance` |
+| `color-blindness` | Simulación de daltonismo | `simulationType` (protanopia/deuteranopia/tritanopia/protanomaly/deuteranomaly/tritanomaly/achromatopsia/blueConeMonochromacy, por defecto \"deuteranomaly\") |
+| `duotone` | Duotono | `shadow` (hex), `highlight` (hex), `intensity` (0-100) |
+| `pixelate` | Pixelar | `blockSize` (2-128), `region` ({left, top, width, height} para pixelado parcial) |
+| `vignette` | Viñeta | `strength` (0.1-1), `color` (hex), `radius`, `softness`, `roundness`, `centerX`, `centerY` |
+
+### Herramientas de IA {#ai-tools}
+
+Todas las herramientas de IA se ejecutan en tu hardware: CPU por defecto, o NVIDIA CUDA cuando hay una GPU NVIDIA compatible disponible. La aceleración de iGPU Intel/AMD mediante VA-API, Quick Sync u OpenCL no es compatible hoy en día para la inferencia de IA. No se necesita internet.
+
+| ID de herramienta | Nombre | Modelo de IA | Ajustes clave |
+|---------|------|---------|-------------|
+| `remove-background` | Eliminar fondo | rembg (BiRefNet / U2-Net) | `model`, `backgroundType` (transparent/color/gradient/blur/image), `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurEnabled`, `blurIntensity`, `shadowEnabled`, `shadowOpacity` |
+| `upscale` | Escalado de imagen | RealESRGAN | `scale` (2/4), `model`, `faceEnhance`, `denoise`, `format`, `quality` |
+| `erase-object` | Borrador de objetos | LaMa (ONNX) | Máscara enviada como segunda parte de archivo (nombre de campo `mask`), `format`, `quality` |
+| `ocr` | OCR / Extracción de texto | PaddleOCR / Tesseract | `quality` (fast/balanced/best), `language`, `enhance` |
+| `blur-faces` | Difuminar rostro / PII | MediaPipe | `blurRadius`, `sensitivity` |
+| `smart-crop` | Recorte inteligente | 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` | Mejora de imagen | Basada en análisis | `mode` (auto/exposure/contrast/color/sharpness), `strength` |
+| `enhance-faces` | Mejora de rostros | GFPGAN / CodeFormer | `model` (gfpgan/codeformer), `strength`, `sensitivity`, `centerFace` |
+| `colorize` | Colorización con IA | DDColor | `intensity`, `model` |
+| `noise-removal` | Eliminación de ruido | Reducción de ruido por niveles | `tier` (quick/balanced/quality/maximum), `strength`, `detailPreservation`, `colorNoise`, `format`, `quality` |
+| `red-eye-removal` | Eliminación de ojos rojos | Puntos de referencia faciales + análisis de color | `sensitivity`, `strength` |
+| `restore-photo` | Restauración de fotos | Pipeline de varios pasos | `mode` (auto/light/heavy), `scratchRemoval`, `faceEnhancement`, `fidelity`, `denoise`, `denoiseStrength`, `colorize` |
+| `passport-photo` | Foto de pasaporte | Puntos de referencia de MediaPipe | Flujo en dos fases. El análisis usa multipart `file`; la generación usa JSON con `countryCode`, `bgColor`, `printLayout` (none/4x6/a4), puntos de referencia y dimensiones de la imagen |
+| `content-aware-resize` | Redimensionado con reconocimiento de contenido | Seam carving (caire) | `width`, `height`, `protectFaces`, `blurRadius`, `sobelThreshold`, `square` |
+| `transparency-fixer` | Corrector de transparencia PNG | BiRefNet HR-matting | `defringe` (0-100), `outputFormat` (png/webp) |
+| `background-replace` | Reemplazar fondo | rembg (BiRefNet) | `backgroundType` (color/gradient), `color` (hex), `gradientColor1`, `gradientColor2`, `gradientAngle`, `feather` (0-20), `format` (png/webp) |
+| `blur-background` | Difuminar fondo | rembg (BiRefNet) | `intensity` (1-100), `feather` (0-20), `format` (png/webp) |
+| `ai-canvas-expand` | Expansión de lienzo con IA | LaMa (outpainting) | `extendTop`, `extendRight`, `extendBottom`, `extendLeft` (px), `tier` (fast/balanced/high), `format`, `quality` |
+
+### Marca de agua y superposición {#watermark-overlay}
+
+| ID de herramienta | Nombre | Ajustes clave |
+|---------|------|-------------|
+| `watermark-text` | Marca de agua de texto | `text`, `font`, `fontSize`, `color`, `opacity`, `position`, `rotation`, `tile` |
+| `watermark-image` | Marca de agua de imagen | `opacity`, `position`, `scale` - el segundo archivo es la marca de agua |
+| `text-overlay` | Superposición de texto | `text`, `font`, `fontSize`, `color`, `x`, `y`, `background`, `padding`, `borderRadius` |
+| `compose` | Composición de imagen | `x`, `y`, `opacity`, `blend` - el segundo archivo se superpone encima |
+| `meme-generator` | Generador de memes | `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`. Admite el modo plantilla (cuerpo JSON con `templateId`) o el modo de imagen personalizada (multipart con archivo). |
+
+### Utilidades {#utilities}
+
+| ID de herramienta | Nombre | Ajustes clave |
+|---------|------|-------------|
+| `info` | Información de imagen | - (devuelve ancho, alto, formato, tamaño, canales, hasAlpha, DPI, EXIF) |
+| `compare` | Comparar imágenes | `mode` (side-by-side/overlay/diff), `diffThreshold` - el segundo archivo es el objetivo de la comparación |
+| `find-duplicates` | Buscar duplicados | `threshold` (distancia de hash perceptual, por defecto 8) - multiarchivo |
+| `color-palette` | Paleta de colores | `count` (número de colores dominantes), `format` (hex/rgb) |
+| `qr-generate` | Generador de códigos QR | `data`, `size`, `margin`, `colorDark`, `colorLight`, `errorCorrectionLevel`, `dotStyle`, `cornerStyle`, `logo` (archivo opcional) |
+| `barcode-read` | Lector de códigos de barras | - (detecta automáticamente QR, EAN, Code128, DataMatrix, etc.) |
+| `image-to-base64` | Imagen a Base64 | `format` (data-uri/plain), `mimeType` |
+| `html-to-image` | HTML a imagen | `url`, `format` (png/jpg/webp), `quality`, `fullPage`, `devicePreset` (desktop/tablet/mobile/custom), `viewportWidth`, `viewportHeight` |
+| `histogram` | Histograma | `scale` (linear/log) - devuelve un gráfico de histograma RGB + estadísticas por canal |
+| `lqip-placeholder` | Marcador de posición LQIP | `width` (4-64), `blur`, `strategy` (blur/pixelate/solid), `format` (webp/png/jpeg), `quality` |
+| `barcode-generate` | Generador de códigos de barras | `text`, `type` (code128/ean13/upca/code39/itf14/datamatrix), `scale` (1-8), `includeText` (bool). Cuerpo JSON, sin subida de archivo. |
+
+### Diseño y composición {#layout-composition}
+
+| ID de herramienta | Nombre | Ajustes clave |
+|---------|------|-------------|
+| `collage` | Collage / Cuadrícula | `template` (más de 25 diseños), `gap`, `backgroundColor`, `borderRadius` - multiarchivo |
+| `stitch` | Unir / Combinar | `direction` (horizontal/vertical/grid), `gap`, `backgroundColor`, `alignment` - multiarchivo |
+| `split` | División de imagen | `mode` (grid/rows/cols), `rows`, `cols`, `tileWidth`, `tileHeight` |
+| `border` | Borde y marco | `width`, `color`, `style` (solid/gradient/pattern), `borderRadius`, `padding`, `shadow` |
+| `beautify` | Embellecer captura de pantalla | `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` | Recorte circular | `zoom` (1-5), `offsetX`, `offsetY`, `borderWidth`, `borderColor`, `background` (transparent/hex), `outputSize` |
+| `image-pad` | Relleno de imagen | `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` | Hoja de sprites | `columns` (1-16), `padding`, `background` (hex), `format` (png/webp/jpeg), `quality` - multiarchivo (2-64 imágenes) |
+
+### Formato y conversión {#format-conversion}
+
+| ID de herramienta | Nombre | Ajustes clave |
+|---------|------|-------------|
+| `svg-to-raster` | SVG a ráster | `format` (png/jpeg/webp/avif/tiff/gif/heif), `width`, `height`, `scale`, `dpi`, `background` |
+| `vectorize` | Imagen a SVG | `colorMode` (bw/color), `threshold`, `colorPrecision`, `filterSpeckle`, `pathMode` (none/polygon/spline) |
+| `gif-tools` | Herramientas GIF | `action` (resize/optimize/reverse/speed/extract-frames/rotate/add-text), parámetros específicos de cada acción |
+| `gif-webp` | Conversor GIF/WebP | `quality` (1-100), `lossless` (bool), `resizePercent` (10-100) |
+
+### Herramientas de vídeo {#video-tools}
+
+| ID de herramienta | Nombre | Ajustes clave |
+|---------|------|-------------|
+| `convert-video` | Convertir vídeo | `format` (mp4/mov/webm/avi/mkv), `quality` (high/balanced/small) |
+| `compress-video` | Comprimir vídeo | `quality` (light/balanced/strong), `resolution` (original/1080p/720p/480p) |
+| `trim-video` | Recortar vídeo | `startS`, `endS`, `precise` (bool, corte con precisión de fotograma) |
+| `mute-video` | Silenciar vídeo | - |
+| `video-to-gif` | Vídeo a GIF | `fps` (1-30), `width`, `startS`, `durationS` (máx. 60 s) |
+| `resize-video` | Redimensionar vídeo | `width`, `height`, `preset` (custom/2160p/1440p/1080p/720p/480p/360p) |
+| `crop-video` | Recortar vídeo | `width`, `height`, `x`, `y` |
+| `rotate-video` | Girar vídeo | `transform` (cw90/ccw90/180/hflip/vflip) |
+| `change-fps` | Cambiar FPS | `fps` (1-120) |
+| `video-color` | Color de vídeo | `brightness`, `contrast`, `saturation`, `gamma` |
+| `video-speed` | Velocidad de vídeo | `factor` (0.25-4), `keepPitch` (bool) |
+| `reverse-video` | Invertir vídeo | - (máx. 5 minutos) |
+| `video-loudnorm` | Normalizar audio | - (EBU R128) |
+| `aspect-pad` | Relleno de proporción | `target` (16:9/9:16/1:1/4:3/3:4), `color` (hex) |
+| `blur-pad` | Relleno difuminado | `target` (16:9/9:16/1:1/4:3/3:4), `blur` (2-50) |
+| `watermark-video` | Marca de agua en vídeo | `text`, `position`, `fontSize`, `opacity`, `color` |
+| `stabilize-video` | Estabilizar vídeo | `smoothing` (5-60, en fotogramas) |
+| `gif-to-video` | GIF a vídeo | `format` (mp4/webm/mov) |
+| `video-to-webp` | Vídeo a WebP | `fps`, `width`, `quality`, `loop` (bool) |
+| `video-to-frames` | Vídeo a fotogramas | `mode` (all/nth/timestamps), `n`, `timestamps`, `format` (png/jpg) |
+| `merge-videos` | Combinar vídeos | - (multiarchivo, normalizado a la resolución del primer vídeo) |
+| `replace-audio` | Reemplazar audio | - (archivo de vídeo + audio, dos archivos) |
+| `burn-subtitles` | Incrustar subtítulos | `fontSize` (8-72) - archivo de vídeo + subtítulos |
+| `embed-subtitles` | Insertar subtítulos | `language` (código ISO 639-2/B) - archivo de vídeo + subtítulos |
+| `extract-subtitles` | Extraer subtítulos | - (genera SRT) |
+| `images-to-video` | Imágenes a vídeo | `secondsPerImage` (0.5-10), `resolution` (1080p/720p/square), `fps` - multiarchivo |
+| `video-metadata` | Limpiar metadatos de vídeo | - |
+| `auto-subtitles` | Subtítulos automáticos (IA) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `format` (srt/vtt) |
+| `extract-audio` | Extraer audio | `format` (mp3/wav/m4a/ogg) |
+
+### Herramientas de audio {#audio-tools}
+
+| ID de herramienta | Nombre | Ajustes clave |
+|---------|------|-------------|
+| `convert-audio` | Convertir audio | `format` (mp3/wav/ogg/flac/m4a), `bitrateKbps` (32-320) |
+| `trim-audio` | Recortar audio | `startS`, `endS` |
+| `volume-adjust` | Ajustar volumen | `gainDb` (-30 a 30) |
+| `normalize-audio` | Normalizar audio | - (EBU R128, -16 LUFS) |
+| `fade-audio` | Fundido de audio | `fadeInS` (0-30), `fadeOutS` (0-30) |
+| `reverse-audio` | Invertir audio | - |
+| `audio-speed` | Velocidad de audio | `factor` (0.25-4) |
+| `pitch-shift` | Cambio de tono | `semitones` (-12 a 12) |
+| `audio-channels` | Canales de audio | `mode` (stereo-to-mono/mono-to-stereo/swap) |
+| `silence-removal` | Eliminación de silencios | `thresholdDb` (-80 a -20), `minSilenceS` (0.1-5) |
+| `noise-reduction` | Reducción de ruido | `strength` (light/medium/strong) |
+| `merge-audio` | Combinar audio | `format` (mp3/wav/flac/m4a) - multiarchivo |
+| `split-audio` | Dividir audio | `mode` (time/parts/silence), `segmentS`, `parts`, `thresholdDb`, `minSilenceS` |
+| `ringtone-maker` | Creador de tonos de llamada | `startS`, `durationS` (1-30) |
+| `waveform-image` | Imagen de forma de onda | `width`, `height`, `color` (hex) |
+| `audio-metadata` | Metadatos de audio | `strip` (bool), `title`, `artist`, `album` |
+| `transcribe-audio` | Transcribir audio (IA) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `outputFormat` (txt/srt/vtt) |
+
+### Herramientas de documentos {#document-tools}
+
+| ID de herramienta | Nombre | Ajustes clave |
+|---------|------|-------------|
+| `merge-pdf` | Combinar PDF | - (multiarchivo, hasta 20 PDF) |
+| `split-pdf` | Dividir PDF | `mode` (range/every), `range`, `everyN` (1-500) |
+| `compress-pdf` | Comprimir PDF | `mode` (quality/targetSize), `quality` (1-100), `targetSizeKb` |
+| `rotate-pdf` | Girar PDF | `angle` (90/180/270), `range` (rango de páginas) |
+| `extract-pages` | Extraer páginas | `range` (sintaxis de qpdf, p. ej. \"1-5,8,10-z\") |
+| `remove-pages` | Eliminar páginas | `pages` (rango de qpdf a eliminar) |
+| `organize-pdf` | Organizar PDF | `order` (orden de páginas de qpdf, p. ej. \"3,1,2,5-z\") |
+| `protect-pdf` | Proteger PDF | `userPassword`, `ownerPassword` (AES-256) |
+| `unlock-pdf` | Desbloquear PDF | `password` |
+| `repair-pdf` | Reparar PDF | - |
+| `linearize-pdf` | Optimizar PDF para web | - (lineariza para una visualización web rápida) |
+| `grayscale-pdf` | PDF en escala de grises | - |
+| `pdfa-convert` | Convertir a PDF/A | - (PDF/A-2 de archivo) |
+| `crop-pdf` | Recortar PDF | `margin` (0-2000 puntos) |
+| `nup-pdf` | PDF N-up | `perSheet` (2/3/4/8/9/12/16) |
+| `booklet-pdf` | Folleto PDF | `perSheet` (2/4/6/8) |
+| `watermark-pdf` | Marca de agua en PDF | `text`, `position`, `fontSize`, `opacity`, `rotation` |
+| `pdf-page-numbers` | Números de página de PDF | `position` (bl/bc/br/tl/tc/tr), `fontSize` |
+| `flatten-pdf` | Aplanar PDF | - (fija formularios y anotaciones) |
+| `redact-pdf` | Redactar PDF | `terms` (string[]), `caseSensitive` (bool) |
+| `sign-pdf` | Firmar PDF | Ruta multipart personalizada con PDF `file`, archivos de firma `sig0`, `sig1` y el array JSON `placements` |
+| `pdf-to-text` | PDF a texto | - |
+| `pdf-to-word` | PDF a Word | - |
+| `pdf-metadata` | Metadatos de PDF | `title`, `author`, `subject`, `keywords` |
+| `convert-document` | Convertir documento | `format` (docx/odt/rtf/txt) |
+| `convert-presentation` | Convertir presentación | `format` (pptx/odp) |
+| `convert-spreadsheet` | Convertir hoja de cálculo | `format` (xlsx/ods/csv) |
+| `excel-to-pdf` | Excel a PDF | - |
+| `word-to-pdf` | Word a PDF | - |
+| `powerpoint-to-pdf` | PowerPoint a PDF | - |
+| `html-to-pdf` | HTML a PDF | - (recursos remotos deshabilitados) |
+| `markdown-to-docx` | Markdown a Word | - |
+| `markdown-to-html` | Markdown a HTML | - |
+| `markdown-to-pdf` | Markdown a PDF | - (recursos remotos deshabilitados) |
+| `epub-convert` | Convertir EPUB | `format` (pdf/docx/html/md) |
+| `to-epub` | Convertir a EPUB | - (acepta .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 a imagen | `pages` (all/range), `format`, `dpi`, `quality` |
+| `pdf-to-jpg` | PDF a JPG | `pages`, `dpi`, `quality`, `colorMode` |
+| `pdf-to-png` | PDF a PNG | `pages`, `dpi`, `quality`, `colorMode` |
+| `pdf-to-tiff` | PDF a TIFF | `pages`, `dpi`, `quality`, `colorMode` |
+
+### Herramientas de archivos {#file-tools}
+
+| ID de herramienta | Nombre | Ajustes clave |
+|---------|------|-------------|
+| `chart-maker` | Creador de gráficos | `kind` (bar/line/pie), `title`, `width`, `height` |
+| `csv-excel` | CSV a Excel | `sheet` (número de hoja de cálculo para la entrada XLSX) - bidireccional |
+| `csv-json` | CSV a JSON | `pretty` (bool) - bidireccional |
+| `json-xml` | JSON a XML | `pretty` (bool) - bidireccional |
+| `split-csv` | Dividir CSV | `rowsPerFile` (1-1000000), `keepHeader` (bool) |
+| `merge-csvs` | Combinar CSV | - (multiarchivo, columnas coincidentes) |
+| `yaml-json` | YAML / JSON | - (bidireccional) |
+| `xml-to-csv` | XML a CSV | - (encuentra automáticamente los elementos repetidos) |
+| `excel-to-csv` | Excel a CSV | preajuste de conversión dedicado respaldado por `convert-spreadsheet` |
+| `create-zip` | Crear ZIP | - (multiarchivo, 2-50 archivos) |
+| `extract-zip` | Extraer ZIP | - (protegido contra bombas) |
+
+### HTML a imagen {#html-to-image}
+
+Captura una página web como imagen. A diferencia de otras herramientas, este endpoint acepta `application/json` en lugar de datos de formulario multipart (no hace falta subir archivos).
+
+**Endpoint:** `POST /api/v1/tools/image/html-to-image`
+
+**Content-Type:** `application/json`
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|---------|-------------|
+| `url` | string | (obligatorio) | URL a capturar (solo http/https) |
+| `format` | string | `"png"` | Formato de salida: `jpg`, `png`, `webp` |
+| `quality` | number | `90` | Calidad 1-100 (solo JPG/WebP) |
+| `fullPage` | boolean | `false` | Capturar la página completa con desplazamiento |
+| `devicePreset` | string | `"desktop"` | `desktop`, `tablet`, `mobile`, `custom` |
+| `viewportWidth` | number | `1280` | Ancho personalizado del viewport 320-3840 |
+| `viewportHeight` | number | `720` | Alto personalizado del viewport 320-2160 |
+
+**Ejemplo:**
+
+```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"}'
+```
+
+**Respuesta:**
+
+```json
+{
+  "jobId": "uuid",
+  "downloadUrl": "/api/v1/download/{jobId}/screenshot.png",
+  "originalSize": 0,
+  "processedSize": 54321
+}
+```
+
+### Subrutas de herramientas {#tool-sub-routes}
+
+Algunas herramientas exponen endpoints adicionales más allá del estándar `POST /api/v1/tools/<section>/<toolId>`:
+
+| Método | Ruta | Descripción |
+|--------|------|-------------|
+| `GET` | `/api/v1/tools/popular` | Devuelve los ID de las herramientas populares, recurriendo a una lista predeterminada curada cuando los datos de uso son escasos |
+| `POST` | `/api/v1/tools/image/remove-background/effects` | Aplica efectos de fondo (color/degradado/desenfoque/sombra) sin volver a ejecutar la IA. Usa la máscara en caché de la eliminación inicial. |
+| `POST` | `/api/v1/tools/image/edit-metadata/inspect` | Leer los metadatos EXIF/IPTC/XMP existentes de una imagen |
+| `POST` | `/api/v1/tools/image/strip-metadata/inspect` | Inspeccionar los campos de metadatos antes de eliminarlos |
+| `POST` | `/api/v1/tools/image/passport-photo/analyze` | Fase 1: detección de rostros con IA + eliminación de fondo. Devuelve los puntos de referencia faciales y los datos en caché. |
+| `POST` | `/api/v1/tools/image/passport-photo/generate` | Fase 2: recortar, redimensionar y crear mosaicos usando el análisis en caché. Sin volver a ejecutar la IA. |
+| `POST` | `/api/v1/tools/image/gif-tools/info` | Obtener metadatos del GIF (número de fotogramas, dimensiones, duración) |
+| `POST` | `/api/v1/tools/pdf/pdf-to-image/info` | Obtener metadatos del PDF (número de páginas, dimensiones) |
+| `POST` | `/api/v1/tools/pdf/pdf-to-image/preview` | Generar una vista previa de una página específica del PDF |
+| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/info` | Obtener metadatos del PDF para el preajuste JPG dedicado |
+| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/preview` | Generar una vista previa de página de PDF con el preajuste JPG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-png/info` | Obtener metadatos del PDF para el preajuste PNG dedicado |
+| `POST` | `/api/v1/tools/pdf/pdf-to-png/preview` | Generar una vista previa de página de PDF con el preajuste PNG |
+| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/info` | Obtener metadatos del PDF para el preajuste TIFF dedicado |
+| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/preview` | Generar una vista previa de página de PDF con el preajuste TIFF |
+| `POST` | `/api/v1/tools/image/svg-to-raster/batch` | Convertir por lotes varios SVG a ráster |
+| `POST` | `/api/v1/tools/image/image-enhancement/analyze` | Analizar la calidad de la imagen y devolver recomendaciones de mejora |
+| `POST` | `/api/v1/tools/image/optimize-for-web/preview` | Vista previa ligera para el ajuste de parámetros en vivo. Devuelve una imagen optimizada con cabeceras de tamaño. |
+
+## Procesamiento por lotes {#batch-processing}
+
+Aplica una herramienta genérica habilitada para lotes a varios archivos a la vez. Devuelve un archivo ZIP. Las rutas personalizadas multiarchivo o de varios pasos, como la firma de PDF, el OCR de PDF y las rutas de preajuste de PDF a imagen, usan su propio contrato de endpoint en lugar de la ruta genérica `/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 concurrencia se controla mediante `CONCURRENT_JOBS` (por defecto: detectado automáticamente a partir de los núcleos de la CPU). `MAX_BATCH_SIZE` limita el número de archivos por lote (por defecto: 100; establece 0 para sin límite).
+
+## Pipelines {#pipelines}
+
+### Ejecutar 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 salida de cada paso es la entrada del siguiente paso. Los pipelines permiten 20 pasos por defecto, configurable mediante `MAX_PIPELINE_STEPS`. Establece `MAX_PIPELINE_STEPS=0` para eliminar el límite.
+
+### Guardar y gestionar pipelines {#save-and-manage-pipelines}
+
+| Método | Ruta | Descripción |
+|--------|------|-------------|
+| `POST` | `/api/v1/pipeline/save` | Guardar un pipeline con nombre (`name`, `description`, `steps[]`) |
+| `GET` | `/api/v1/pipeline/list` | Listar los pipelines guardados (los administradores ven todos; los usuarios ven los propios) |
+| `DELETE` | `/api/v1/pipeline/:id` | Eliminar (propietario o administrador) |
+| `GET` | `/api/v1/pipeline/tools` | Listar los ID de herramienta válidos para los pasos del pipeline |
+
+## Seguimiento del progreso {#progress-tracking}
+
+Los trabajos de larga duración, las herramientas en cola, los trabajos por lotes y los pipelines emiten el progreso en tiempo real mediante Server-Sent Events. El flujo de progreso es público y está indexado por el ID del trabajo, así que los clientes no necesitan enviar una cabecera Authorization para leerlo.
+
+```bash
+# Connect to the SSE stream (jobId is in the JSON response body from the tool endpoint)
+curl -N http://localhost:1349/api/v1/jobs/<jobId>/progress
+```
+
+Formato del evento:
+```
+data: {"jobId":"...","type":"single","phase":"processing","stage":"Upscaling","percent":42}
+data: {"jobId":"...","type":"single","phase":"complete","percent":100,"result":{"downloadUrl":"/api/v1/download/..."}}
+data: {"jobId":"...","type":"batch","status":"processing","completedFiles":2,"totalFiles":5,"failedFiles":0,"errors":[]}
+```
+
+Puedes solicitar la cancelación de un trabajo en cola o en ejecución con `POST /api/v1/jobs/:jobId/cancel`. La respuesta es `{"canceled":true|false}`.
+
+## Biblioteca de archivos {#file-library}
+
+Almacenamiento persistente de archivos con historial de versiones.
+
+| Método | Ruta | Descripción |
+|--------|------|-------------|
+| `POST` | `/api/v1/upload` | Subir archivos al espacio de trabajo (procesamiento temporal) |
+| `POST` | `/api/v1/files/upload` | Subir archivos a la biblioteca de archivos persistente |
+| `POST` | `/api/v1/files/save-result` | Guardar el resultado del procesamiento de una herramienta como una nueva versión de archivo |
+| `GET` | `/api/v1/files` | Listar los archivos guardados (paginado, con búsqueda) |
+| `GET` | `/api/v1/files/:id` | Obtener los metadatos del archivo + la cadena de versiones |
+| `GET` | `/api/v1/files/:id/download` | Descargar archivo |
+| `GET` | `/api/v1/files/:id/thumbnail` | Obtener una miniatura JPEG de 300px |
+| `DELETE` | `/api/v1/files` | Eliminar en bloque archivos y sus cadenas de versiones (cuerpo: `{ ids: [...] }`) |
+| `POST` | `/api/v1/fetch-urls` | Obtener URL remotas en el espacio de trabajo para importaciones basadas en URL |
+| `POST` | `/api/v1/preview` | Generar una vista previa WebP compatible con el navegador (para formatos HEIC/HEIF/RAW) |
+| `GET` | `/api/v1/files/:id/preview` | Transmitir una vista previa en caché o generada compatible con el navegador para un PDF, documento de oficina, vídeo o archivo de audio guardado |
+| `POST` | `/api/v1/preview/generate` | Generar una vista previa MP4 o MP3 bajo demanda para un archivo multimedia subido sin guardarlo primero |
+| `GET` | `/api/v1/download/:jobId/:filename` | Descargar un archivo procesado de un espacio de trabajo |
+
+Para guardar automáticamente el resultado de una herramienta en la biblioteca, incluye `fileId` como campo de formulario multipart que referencie un archivo existente de la biblioteca. El resultado procesado se guardará como una nueva versión.
+
+## Gestión de claves de API {#api-key-management}
+
+| Método | Ruta | Acceso | Descripción |
+|--------|------|--------|-------------|
+| `POST` | `/api/v1/api-keys` | Auth | Generar una nueva clave - se muestra una vez |
+| `GET` | `/api/v1/api-keys` | Auth | Listar claves (nombre, id, lastUsedAt - no la clave en bruto) |
+| `DELETE` | `/api/v1/api-keys/:id` | Auth | Eliminar clave |
+
+## Equipos {#teams}
+
+| Método | Ruta | Acceso | Descripción |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/teams` | Admin (`teams:manage`) | Listar equipos |
+| `POST` | `/api/v1/teams` | Admin (`teams:manage`) | Crear equipo |
+| `PUT` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Renombrar equipo |
+| `DELETE` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Eliminar equipo (no se puede eliminar el equipo predeterminado ni los equipos con miembros) |
+
+## Ajustes {#settings}
+
+Configuración clave-valor en tiempo de ejecución (legible por cualquier usuario autenticado, escribible solo por el administrador).
+
+| Método | Ruta | Descripción |
+|--------|------|-------------|
+| `GET` | `/api/v1/settings` | Obtener todos los ajustes |
+| `PUT` | `/api/v1/settings` | Actualizar ajustes en bloque (cuerpo JSON con pares clave-valor) |
+| `GET` | `/api/v1/settings/:key` | Obtener un ajuste específico por clave |
+
+Claves conocidas: `disabledTools` (array JSON de ID de herramienta), `enableExperimentalTools` (cadena bool), `loginAttemptLimit` (número).
+
+## Preferencias {#preferences}
+
+Las preferencias por usuario están separadas de los ajustes de la instancia. Cualquier usuario autenticado puede leer y actualizar su propio mapa de preferencias.
+
+| Método | Ruta | Descripción |
+|--------|------|-------------|
+| `GET` | `/api/v1/preferences` | Obtener las preferencias del usuario actual como `{ "preferences": { ... } }` |
+| `PUT` | `/api/v1/preferences` | Insertar o actualizar una o varias claves de preferencia para el usuario actual |
+
+## Roles {#roles}
+
+Gestión de roles personalizados con permisos granulares.
+
+| Método | Ruta | Acceso | Descripción |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/roles` | Admin (`audit:read`) | Listar todos los roles con el número de usuarios |
+| `POST` | `/api/v1/roles` | Admin (`security:manage`) | Crear un rol personalizado (`name`, `description`, `permissions`) |
+| `PUT` | `/api/v1/roles/:id` | Admin (`security:manage`) | Actualizar un rol personalizado (no se pueden modificar los roles integrados) |
+| `DELETE` | `/api/v1/roles/:id` | Admin (`security:manage`) | Eliminar un rol personalizado (no se pueden eliminar los roles integrados; los usuarios afectados revierten al rol `user`) |
+
+Permisos 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`.
+
+## Registro de auditoría {#audit-log}
+
+Endpoint solo para administradores para revisar acciones relevantes de seguridad.
+
+| Método | Ruta | Acceso | Descripción |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/audit-log` | Admin (`audit:read`) | Registro de auditoría paginado con filtros opcionales |
+
+Parámetros de consulta:
+
+| Parámetro | Descripción |
+|-----------|-------------|
+| `page` | Número de página (por defecto: 1) |
+| `limit` | Entradas por página (por defecto: 50, máx.: 100) |
+| `action` | Filtrar por tipo de acción (p. ej. `ROLE_CREATED`, `ROLE_DELETED`) |
+| `ip` | Filtrar por dirección IP de origen |
+| `from` | Filtrar las entradas posteriores a esta fecha ISO 8601 |
+| `to` | Filtrar las entradas anteriores a esta fecha ISO 8601 |
+
+## Analítica {#analytics}
+
+| Método | Ruta | Acceso | Descripción |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/config/analytics` | Público | Obtener la configuración de analítica efectiva (clave de PostHog, DSN de Sentry, tasa de muestreo). Las claves, el DSN y el ID de instancia quedan en blanco cuando la analítica está desactivada, ya sea por la compilación en tiempo de compilación o por el ajuste `analyticsEnabled` de la instancia. |
+| `POST` | `/api/v1/feedback` | Auth | Enviar comentarios explícitos del usuario al proyecto de PostHog configurado como `feedback_submitted`. La ruta respeta la barrera de analítica, limita la tasa de envíos, elimina los campos de contacto salvo que `contactOk` sea true, y nunca acepta el contenido de archivos, nombres de archivos, rutas de subida ni texto de error privado en bruto. Cuando la analítica está desactivada, devuelve `{ "ok": true, "accepted": false }`. |
+| `PUT` | `/api/v1/settings` | Admin (`settings:write`) | Establecer la exclusión voluntaria a nivel de toda la instancia. Envía un cuerpo JSON `{ "analyticsEnabled": "false" }` para desactivar la analítica para todos, o `"true"` para volver a activarla. |
+
+## Funciones / Paquetes de IA {#features-ai-bundles}
+
+Gestiona los paquetes de funciones de IA (instalar/desinstalar paquetes de modelos de IA en el entorno Docker). Prefiere el endpoint de instalación a nivel de herramienta cuando habilites una herramienta desde una automatización personalizada: algunas herramientas de IA necesitan más de un paquete compartido, y este endpoint omite los paquetes ya instalados y solo pone en cola los que faltan.
+
+| Método | Ruta | Acceso | Descripción |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/features` | Auth | Listar todos los paquetes de funciones y su estado de instalación |
+| `POST` | `/api/v1/admin/features/:bundleId/install` | Admin (`features:manage`) | Instalar un paquete de funciones (asíncrono, devuelve `jobId` para el seguimiento del progreso) |
+| `POST` | `/api/v1/admin/tools/:toolId/features/install` | Admin (`features:manage`) | Instalar todos los paquetes que requiere una herramienta; devuelve el estado en cola/omitido por paquete |
+| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Admin (`features:manage`) | Desinstalar un paquete de funciones y limpiar los archivos de modelos |
+| `GET` | `/api/v1/admin/features/disk-usage` | Admin (`features:manage`) | Obtener el uso total de disco de los modelos de IA |
+| `POST` | `/api/v1/admin/features/import` | Admin (`features:manage`) | Importar un archivo de paquete de IA sin conexión |
+
+## Operaciones de administración {#admin-operations}
+
+Endpoints operativos para observabilidad, soporte, informes de uso y estado de las copias de seguridad.
+
+| Método | Ruta | Acceso | Descripción |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/admin/log-level` | Admin (`settings:write`) | Leer el nivel de log actual en tiempo de ejecución |
+| `POST` | `/api/v1/admin/log-level` | Admin (`settings:write`) | Cambiar el nivel de log en tiempo de ejecución (`fatal`, `error`, `warn`, `info`, `debug`, `trace` o `silent`) |
+| `GET` | `/api/v1/metrics` | Admin (`system:health`) | Métricas de Prometheus en formato de texto |
+| `GET` | `/api/v1/admin/support-bundle` | Admin (`system:health`) | Descargar un ZIP de paquete de soporte de diagnóstico censurado |
+| `GET` | `/api/v1/admin/usage` | Admin (`audit:read`) | Datos del panel de uso, con el parámetro de consulta opcional `days` |
+| `GET` | `/api/v1/admin/backup-status` | Admin (`system:health`) | Leer los metadatos de la última copia de seguridad y su estado de frescura |
+| `POST` | `/api/v1/admin/backup-status` | Admin (`system:health`) | Registrar una copia de seguridad completada (`type`, `sizeBytes` opcional, `notes` opcional) |
+
+## APIs de Enterprise {#enterprise-apis}
+
+Estas rutas están limitadas por licencia según su función enterprise relacionada. Aun así requieren el permiso de SnapOtter indicado.
+
+| Método | Ruta | Acceso | Descripción |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/enterprise/audit/export` | Admin (`audit:read`) | Exportar entradas de auditoría como JSON o CSV con filtros |
+| `GET` | `/api/v1/enterprise/config/export` | Admin (`system:health`) | Exportar la configuración de instancia censurada, los roles personalizados y los equipos |
+| `POST` | `/api/v1/enterprise/config/import` | Admin (`system:health`) | Importar configuración, con ejecución de prueba opcional |
+| `GET` | `/api/v1/enterprise/ip-allowlist` | Admin (`security:manage`) | Leer la lista de permitidos CIDR configurada |
+| `PUT` | `/api/v1/enterprise/ip-allowlist` | Admin (`security:manage`) | Actualizar la lista de permitidos CIDR con prevención de autobloqueo |
+| `GET` | `/api/v1/enterprise/legal-hold` | Admin (`compliance:manage`) | Listar las retenciones legales de usuarios y equipos |
+| `PUT` | `/api/v1/enterprise/legal-hold` | Admin (`compliance:manage`) | Aplicar o liberar una retención legal sobre un usuario o equipo |
+| `POST` | `/api/v1/enterprise/scim/token` | Admin (`users:manage`) | Generar un token bearer de SCIM, devuelto una vez |
+| `DELETE` | `/api/v1/enterprise/scim/token` | Admin (`users:manage`) | Revocar el token bearer de SCIM actual |
+| `GET` | `/api/v1/enterprise/siem/config` | Admin (`webhooks:manage`) | Leer la configuración de reenvío SIEM |
+| `PUT` | `/api/v1/enterprise/siem/config` | Admin (`webhooks:manage`) | Actualizar la configuración de reenvío SIEM |
+| `GET` | `/api/v1/enterprise/webhooks` | Admin (`webhooks:manage`) | Listar los destinos de webhook |
+| `POST` | `/api/v1/enterprise/webhooks` | Admin (`webhooks:manage`) | Crear un destino de webhook |
+| `PUT` | `/api/v1/enterprise/webhooks/:index` | Admin (`webhooks:manage`) | Actualizar un destino de webhook |
+| `DELETE` | `/api/v1/enterprise/webhooks/:index` | Admin (`webhooks:manage`) | Eliminar un destino de webhook |
+| `POST` | `/api/v1/enterprise/webhooks/:index/test` | Admin (`webhooks:manage`) | Enviar una carga útil de webhook de prueba |
+| `POST` | `/api/v1/enterprise/users/:id/export` | Admin (`compliance:manage`) | Iniciar un trabajo de exportación de usuario según el RGPD |
+| `GET` | `/api/v1/enterprise/users/:id/export/:jobId` | Admin (`compliance:manage`) | Leer el estado de la exportación RGPD y la URL de descarga |
+| `DELETE` | `/api/v1/enterprise/users/:id/purge` | Admin (`compliance:manage`) | Purgar permanentemente los datos de un usuario tras la confirmación |
+| `DELETE` | `/api/v1/enterprise/teams/:id/purge` | Admin (`compliance:manage`) | Purgar permanentemente los datos de un equipo tras la confirmación |
+| `GET` | `/api/v1/admin/version` | Admin (`system:health`) | Leer los metadatos de versión de la app, la compilación, Node y el esquema |
+| `GET` | `/api/v1/admin/migrations/pending` | Admin (`system:health`) | Comparar las migraciones empaquetadas con las migraciones aplicadas |
+| `GET` | `/api/v1/admin/upgrade-check` | Admin (`system:health`) | Ejecutar comprobaciones de preparación para la actualización |
+
+### SCIM 2.0 {#scim-2-0}
+
+Los endpoints de descubrimiento de SCIM son públicos. Los endpoints de usuarios y grupos requieren el token bearer de SCIM generado anteriormente.
+
+| Método | Ruta | Acceso | Descripción |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/scim/v2/ServiceProviderConfig` | Público | Capacidades del servidor SCIM |
+| `GET` | `/api/v1/scim/v2/Schemas` | Público | Descubrimiento de esquemas SCIM |
+| `GET` | `/api/v1/scim/v2/ResourceTypes` | Público | Descubrimiento de tipos de recursos SCIM |
+| `GET` | `/api/v1/scim/v2/Users` | Token SCIM | Listar usuarios, con filtro SCIM opcional |
+| `POST` | `/api/v1/scim/v2/Users` | Token SCIM | Crear un usuario |
+| `GET` | `/api/v1/scim/v2/Users/:id` | Token SCIM | Obtener un usuario |
+| `PUT` | `/api/v1/scim/v2/Users/:id` | Token SCIM | Reemplazar un usuario |
+| `DELETE` | `/api/v1/scim/v2/Users/:id` | Token SCIM | Desactivar un usuario de forma reversible |
+| `GET` | `/api/v1/scim/v2/Groups` | Token SCIM | Listar equipos como grupos SCIM |
+| `POST` | `/api/v1/scim/v2/Groups` | Token SCIM | Crear un equipo |
+| `GET` | `/api/v1/scim/v2/Groups/:id` | Token SCIM | Obtener un equipo |
+| `PUT` | `/api/v1/scim/v2/Groups/:id` | Token SCIM | Reemplazar un equipo y la pertenencia al grupo |
+| `DELETE` | `/api/v1/scim/v2/Groups/:id` | Token SCIM | Eliminar un equipo |
+
+## Plantillas de memes {#meme-templates}
+
+API de apoyo para la herramienta generadora de memes.
+
+| Método | Ruta | Acceso | Descripción |
+|--------|------|--------|-------------|
+| `GET` | `/api/v1/meme-templates` | Auth | Listar todas las plantillas de memes disponibles con las posiciones de los cuadros de texto |
+| `GET` | `/api/v1/meme-templates/full/:filename` | Auth | Servir la imagen de la plantilla a tamaño completo |
+| `GET` | `/api/v1/meme-templates/thumbs/:filename` | Auth | Servir la miniatura de la plantilla |
+| `GET` | `/api/v1/meme-templates/fonts/:filename` | Auth | Servir el archivo de fuente usado para renderizar el texto del meme |
+
+## Respuestas de error {#error-responses}
+
+Todos los errores devuelven JSON:
+
+```json
+{
+  "error": "Human-readable message",
+  "code": "MACHINE_READABLE_CODE"
+}
+```
+
+| Estado | Significado |
+|--------|---------|
+| 400 | Petición no válida / validación fallida |
+| 401 | No autenticado |
+| 403 | Permisos insuficientes |
+| 404 | Recurso no encontrado |
+| 413 | Archivo demasiado grande (consulta `MAX_UPLOAD_SIZE_MB`) |
+| 422 | Procesamiento fallido tras la validación |
+| 429 | Límite de tasa alcanzado (consulta `RATE_LIMIT_PER_MIN`) |
+| 501 | El paquete de funciones de IA requerido no está instalado (`FEATURE_NOT_INSTALLED`) |
+| 500 | Error interno del servidor |