Developer guide · Smart Focus

Choose a subject.
Make the crop explicit.

Working Smart Focus URL examples. Replace the illustrative source and image path with your own published source.

Smart FocusTry face and person selection in the live image playground.Try Smart Focus →

Start with an image URL

https://imgexo.com/your-source/team.jpg
  ?w=640&h=360&fit=crop&crop=faces

Try the live playground to select detected faces and people on bundled sample images. These example source names are placeholders; replace them with your published source.

Choose a framing mode

See the focal point

?w=640&h=360&fit=crop&crop=focalpoint&fp-x=0.35&fp-y=0.4&fp-z=2&fp-debug=true

Show a crosshair at the selected focal point. true or 1 enables it; false or 0 disables it. Debug is part of the rendered output; leave it off for normal delivery.

Keep faces in frame

?w=640&h=360&fit=crop&crop=faces

Frame detected faces as a group where the requested geometry permits. A narrow crop may not fit every detected face.

Focus on people

?w=480&h=640&fit=crop&crop=person

Use detected person bounds to guide the crop. Review the preview for the image and aspect ratio you intend to serve.

Choose an automatic fallback

?w=320&h=320&fit=crop&crop=auto

Try faces, then people, then local entropy-based framing. fit=smart-crop is an alias for fit=crop&crop=auto when no crop mode is supplied.

Make a tighter portrait

?w=320&h=320&fit=facearea&faceindex=2&facepad=1.5

Frame face 2 as shown in this image’s analysis. faceindex is 1-based; facepad controls framing context, with values above 1 adding space around the selected face.

Set your own focal point

?w=640&h=360&fit=crop&crop=focalpoint&fp-x=0.35&fp-y=0.4&fp-z=2

Use normalized coordinates from 0 to 1. fp-z controls zoom: 1 is the default framing scale; larger values make a closer crop. Manual focus does not require face detection.

Make the fallback order explicit

?w=320&h=320&fit=crop&crop=faces,person,entropy

Try each mode in order when no matching subject is found. Explicitly selecting a missing faceindex is a validation error rather than silently choosing a different person.

How visual selection maps to the API

The console inspector shows face and person boxes on the original thumbnail. Selecting a face uses faceindex with fit=facearea; selecting a person uses crop=person with its subject-index. Both indices start at 1 and refer to detections in this image, not to a person’s identity.

The crop outline represents the preview crop. Changes should be previewed again before using the generated URL. The inspector explains a no-match fallback or a clipped group rather than implying every subject fits.

Parameter limits

faceindex
Integer from 1 to 50. Selects an available face in the image’s analysis. An unavailable index is rejected.
subject-index
Integer from 1 to 50. Selects an available detected person for crop=person.
facepad
Greater than 0 and up to 10. Controls face-area context; the default is 1. Values above 1 expand the requested context within image bounds.
fp-x / fp-y
Coordinates from 0 to 1 for crop=focalpoint; the default is 0.5 on each axis.
fp-z
Zoom from 1 to 100 for manual focal-point cropping; the default is 1. Output dimensions and source limits still apply.
fp-debug
Crosshair overlay: true / 1 on; false / 0 / omission off. Active with fit=crop and crop=focalpoint. The machine API uses a JSON boolean.
ar
Positive W:H aspect ratio for crop or min. One dimension derives the other; two dimensions bound the output. Source limits still apply.

Move focal-point URLs from Imgix

Keep the image path and the same query parameters when changing your configured delivery base to Imgexo. The shared URL adds your published source slug; a verified custom hostname can retain the original path. No frontend parameter renaming is needed for manual focal-point crops.

?w=640&h=360&fit=crop&crop=focalpoint
&fp-x=0.35&fp-y=0.4&fp-z=2&fp-debug=true

Defaults are fp-x=0.5, fp-y=0.5, fp-z=1 and debug off. Coordinates refer to the oriented original, or to the region selected by rect. The crop stays inside the source bounds, including focal points at 0 and 1. Enable both fit=crop and crop=focalpoint; other ordinary modes ignore focal-point parameters. Manual focus does not call AI or a detector.

Width alone preserves the source ratio. To choose a responsive ratio, use w=640&ar=16:9; it produces 640 × 360. DPR scales output pixels; zoom changes framing. Combine these with a source rectangle or right-angle rotation when needed.

Try focal-point cropping in the Playground →

Existing Imgix signatures are not Imgexo authorization tokens. Compatibility mode accepts bounded unsigned image URLs; signed-only sources need new Imgexo signatures. Source limits still apply. Framing and parameter compatibility do not promise identical encoded bytes or debug-stroke pixels, or support for unrelated Imgix parameters. At extreme zoom, Imgix can undershoot requested dimensions through source-pixel rounding; Imgexo keeps your requested output dimensions. Review representative product images before switching traffic.

Reference: Imgix focal-point API.

Analysis, quotas and privacy

Automatic face and person modes use detection analysis that can be reused across output sizes. Analysis and rendering have separate limits. Manual focal points do not require a detection request.

Detection describes subject locations; it does not identify people or build an identity database. No region-specific processing or EU-only detection promise is made in this guide.

Validate with your images

Test portraits, groups, occluded subjects and layouts with different aspect ratios. Inspect the actual crop outline and explanation. Group preservation is conditional on the source geometry and requested crop. Different detectors and encoders can produce different results from the same parameters.

Big on images.
Light on everything else.

Let’s build a simpler image pipeline for your next million requests.

Enterprise image optimization. Built for scale.