Create a round avatar
https://imgexo.com/your-source/portrait.jpg ?w=400&h=400&fit=facearea&facepad=2&mask=ellipse&fm=png
Replace the source and path with your published source. The console Playground includes a Create a round avatar preset, face number, face padding and an ellipse-mask switch.
Control the framing
fit=facearea requires both w and h. Faces are ordered by area, largest first; ties are ordered from left to right, then top to bottom. faceindex is an integer from 1 to 50, default 1, and refers to a detection in this image, never a person’s identity.
facepad is greater than 0 and at most 10, default 1. A value of 2 requests twice the face box dimensions before matching the output aspect ratio. The crop shifts and shrinks when necessary to stay inside the source. Near image edges or at extreme aspect ratios, the source can limit the available context.
Face-area framing cannot be combined with rect or another crop anchor. For manual control, use fit=crop&crop=focalpoint or a source rectangle instead; the ellipse mask also works with these transforms.
Deliver actual transparency
mask=ellipse applies an ellipse to the final output dimensions after resizing and rotation. Equal dimensions create a circle; unequal dimensions create an oval. dpr scales the encoded output. Use fm=png, fm=webp or fm=avif for alpha transparency. Without an explicit format, the mask defaults to PNG unless automatic format negotiation selects WebP or AVIF. JPEG flattens corners using bg, default white.
Detection and reuse
The first analysis sends a bounded, oriented image to the face-detection provider. Detection must be configured for the serving environment; provider usage is billed separately. Each new analysis consumes one workspace AI operation, including failed provider attempts. AI opt-out and monthly AI limits are enforced before a provider call. Only face boxes are retained in the workspace-scoped analysis cache, keyed by image content for seven days and reused across sizes. Changed image content gets a new analysis key. Standard source access checks, transform limits and variant caching still apply.
Detection cannot guarantee every face will be found. NO_FACE_DETECTED and FACE_INDEX_NOT_FOUND return 422. Provider failures return a 5xx error; there is no silent center-crop substitute. An unknown mask or invalid padding returns 400.
The public bundled-portrait demo uses previously detected coordinates and runs the same crop-and-mask renderer, without a paid detection request per visitor.
See the avatar example