Recorte inteligente

Recorte inteligente sensible al sujeto, a las caras o basado en el recorte de bordes. Usa las estrategias de atención/entropía de Sharp y la detección de caras por IA para un encuadre inteligente.

API Endpoint

POST /api/v1/tools/image/smart-crop

Procesamiento: Asíncrono (devuelve 202, sondea /api/v1/jobs/{jobId}/progress para conocer el estado mediante SSE)

Paquete de modelos: face-detection (200-300 MB): necesario solo para el modo face

Parámetros

Parámetro	Tipo	Obligatorio	Predeterminado	Descripción
file	file	Sí	-	Archivo de imagen (multipart)
mode	string	No	"subject"	Modo de recorte: subject, face, trim. (Los valores heredados attention y content se asignan a subject y trim)
strategy	string	No	"attention"	Estrategia para el modo de sujeto: attention o entropy
width	integer	No	-	Ancho objetivo en píxeles
height	integer	No	-	Alto objetivo en píxeles
padding	integer	No	0	Porcentaje de relleno alrededor del sujeto (0-50)
facePreset	string	No	"head-shoulders"	Ajuste preestablecido de encuadre de caras: closeup, head-shoulders, upper-body, half-body
sensitivity	number	No	0.5	Sensibilidad de la detección de caras (0-1)
threshold	integer	No	30	Umbral del modo de recorte de bordes para la detección del fondo (0-255)
padToSquare	boolean	No	false	Rellena el resultado recortado hasta formar un cuadrado
padColor	string	No	"#ffffff"	Color de fondo para el relleno
targetSize	integer	No	-	Tamaño objetivo de la salida rellenada (píxeles)
quality	integer	No	-	Calidad de salida (1-100)

Ejemplo de solicitud

curl -X POST http://localhost:1349/api/v1/tools/image/smart-crop \
  -F "[email protected]" \
  -F 'settings={"mode":"face","width":1080,"height":1080,"facePreset":"head-shoulders"}'

Respuesta

Respuesta inicial (202 Accepted)

{
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "async": true
}

Progreso (SSE en /api/v1/jobs/{jobId}/progress)

event: progress
data: {"phase":"processing","percent":50}

Resultado final (mediante SSE)

{
  "phase": "complete",
  "percent": 100,
  "result": {
    "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "downloadUrl": "/api/v1/download/{jobId}/portrait_smartcrop.jpg",
    "originalSize": 500000,
    "processedSize": 320000
  }
}

Modos

Modo de sujeto

Usa la estrategia de atención o entropía de Sharp para encontrar la región visualmente más interesante y recorta a su alrededor.

Modo de caras

Detecta caras mediante IA y luego encuadra el recorte alrededor de las caras detectadas usando el facePreset especificado. Recurre al modo de sujeto (estrategia de atención) si no se detecta ninguna cara.

Modo de recorte de bordes

Elimina los bordes/fondos uniformes de la imagen. De forma opcional, rellena el resultado hasta formar un cuadrado con un color de fondo y un tamaño objetivo especificados.

Notas

• Esta herramienta usa la fábrica createToolRoute con executionHint: "long", por lo que devuelve 202 con progreso por SSE.
• El modo de caras requiere el paquete de modelos face-detection (200-300 MB).
• Los modos de sujeto y recorte de bordes funcionan sin ningún paquete de modelos de IA.
• El facePreset determina la precisión con que el recorte encuadra las caras detectadas: closeup es el más ajustado, half-body es el más amplio.
• Si no se especifica ancho/alto, el valor predeterminado es 1080x1080.