Image face crop

POST /api/image-face-crop

Detect a face in a photo and return a tight rectangular crop centred on the face. Useful for avatar generation from full-body photos.

Detects a face in the input photo and returns a tight crop centred on it. Configurable padding around the face. Uses a deep-learning face detector (more reliable than classic Haar cascades, especially for non-frontal faces and partially-occluded faces). Useful for generating avatar / profile-picture crops from full-body or group photos.

Inputs

Name	Type	Default	Description
image*	file	—	Source image bytes.
padding	number (0…2)	0.4	Padding around the face bounding box, as a fraction of face size. 0 = tight; 0.4 = comfortable avatar.
aspect	string	"square"	Output aspect ratio. "square" (default), "original" (preserve face box), or a numeric ratio like "4:5".
outWidth	number (0…4096)	0	Resize the crop to this width (height derived from aspect). 0 = keep crop's native size.
format	enum (jpeg \| png)	"jpeg"	Output encoding.
quality	number (1…100)	90	JPEG quality (ignored for PNG).
scoreThreshold	number (0…1)	0.6	confidence threshold for accepting a face.

Response

Modes: binary, base64-json. Cache: yes (24h TTL).