mirror of https://github.com/snapotter-hq/SnapOtter.git synced 2026-08-03 07:46:42 +02:00

Files

T

SnapOtter 7db6bb97da docs: add per-tool API documentation and fix parity gaps

- Create 53 per-tool VitePress documentation pages with accurate
  parameters from Zod schemas, example requests, and response formats
- Add root llms.txt for LLM-friendly repo browsing
- Fix OpenAPI spec: add auth and 422 error schemas to
  edit-metadata/inspect and strip-metadata/inspect sub-routes
- Fix tool count inconsistency (52 -> 53) across landing site,
  e2e tests, and local docs
- Rename color-adjustments.ts to adjust-colors.ts to match tool ID
- Update VitePress sidebar with all 8 tool categories and top nav

2026-06-08 11:52:28 +08:00

2.8 KiB

Raw Blame History

Smart Crop

Smart subject-aware, face-aware, or trim-based cropping. Uses Sharp's attention/entropy strategies and AI face detection for intelligent framing.

API Endpoint

POST /api/v1/tools/smart-crop

Processing: Synchronous (uses createToolRoute factory, returns result directly)

Model bundle: face-detection (200-300 MB) -- required only for face mode

Parameters

Parameter	Type	Required	Default	Description
file	file	Yes	-	Image file (multipart)
mode	string	No	`"subject"`	Crop mode: `subject`, `face`, `trim`. (Legacy values `attention` and `content` map to `subject` and `trim`)
strategy	string	No	`"attention"`	Strategy for subject mode: `attention` or `entropy`
width	integer	No	-	Target width in pixels
height	integer	No	-	Target height in pixels
padding	integer	No	`0`	Padding percentage around subject (0-50)
facePreset	string	No	`"head-shoulders"`	Face framing preset: `closeup`, `head-shoulders`, `upper-body`, `half-body`
sensitivity	number	No	`0.5`	Face detection sensitivity (0-1)
threshold	integer	No	`30`	Trim mode threshold for background detection (0-255)
padToSquare	boolean	No	`false`	Pad trimmed result to a square
padColor	string	No	`"#ffffff"`	Background color for padding
targetSize	integer	No	-	Target size for padded output (pixels)
quality	integer	No	-	Output quality (1-100)

Example Request

curl -X POST http://localhost:13490/api/v1/tools/smart-crop \
  -F "file=@portrait.jpg" \
  -F 'settings={"mode":"face","width":1080,"height":1080,"facePreset":"head-shoulders"}'

Response (200 OK)

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

Modes

Subject Mode

Uses Sharp's attention or entropy strategy to find the most visually interesting region and crops around it.

Face Mode

Detects faces using AI, then frames the crop around detected faces using the specified facePreset. Falls back to subject mode (attention strategy) if no faces are detected.

Trim Mode

Removes uniform borders/background from the image. Optionally pads the result to a square with a specified background color and target size.

Notes

This tool uses the synchronous createToolRoute factory, so it returns a standard response (not 202 async).
Face mode requires the face-detection model bundle (200-300 MB).
Subject and trim modes work without any AI model bundle.
The facePreset determines how tightly the crop frames detected faces: closeup is the tightest, half-body is the widest.
If no width/height are specified, defaults to 1080x1080.

2.8 KiB Raw Blame History