Shapes and canvas
Parameter overview
| Parameter | Description | Values |
|---|---|---|
flip | Flip | h horizontal / v vertical / hv both |
border | Border, in the format width,color | Width in pixels or as a percentage (of the image's short edge) |
pad | Padding on all sides | Pixels, 0 ~ 4000 |
pad-left / pad-top / pad-right / pad-bottom | Padding on one side | Pixels, 0 ~ 4000 |
box | Solid box, in the format x,y,w,h | Pixels or percentages (of the image's width and height) |
box-color | Box color. Defaults to black | Hex color; semi-transparent allowed |
box-radius | Box corner radius | Pixels or a percentage (of the box's short edge) |
mask | Shape mask | corners rounded rectangle / ellipse ellipse |
corner-radius | Corner radius. Required when mask=corners | A single value, or top-left,top-right,bottom-right,bottom-left |
Colors are always hexadecimal, in 3-, 4-, 6-, or 8-digit form. In the 4- and 8-digit forms, the first segment is the opacity. For example, 80000000 is black at 50% transparency.
Percentages must be written with % encoded as %25 in URLs.
Flip
https://demo.bitiful.com/girl.jpeg?flip=h
Flipping runs after auto-orientation and rotation. mirror is shorthand for flip=h.
Borders and padding
https://demo.bitiful.com/girl.jpeg?border=10,ff0000
https://demo.bitiful.com/girl.jpeg?pad=40&bg=f5f5f5
- Both borders and padding extend the canvas outward, so the image content itself is never covered.
- Padding uses the
bgcolor. Ifbgis not specified, images with an alpha channel are padded with transparency and all others with white.
Solid boxes
Draws a solid rectangle on the image, placed beneath watermarks. It is often paired with a text watermark to create a title bar or caption strip:
box coordinates are calculated on the processed image (after resizing and rotation). Any part that extends beyond the image is clipped.
Rounded corners and circles
https://demo.bitiful.com/girl.jpeg?mask=corners&corner-radius=24&fmt=png
https://example.com/avatar.jpg?w=200&h=200&mask=ellipse&fmt=png
mask=ellipseuses the ellipse inscribed in the image; for a square image, this is a circle.- A percentage
corner-radiusis calculated from the image's short edge, so50%gives the maximum radius. - The area outside the mask is transparent.
To keep transparency, output a format that supports it (fmt=png, webp, or avif). When you output JPEG, transparent areas are filled with bg, which defaults to white.
Order of operations
Processing runs in the following order:
Resize, rotate → flip → box → watermark → padding and border → mask
As a result, watermarks can sit on top of boxes, borders and padding don't affect watermark positioning, and because the mask runs last, it also rounds the outer corners of the border.
Supported content
- Animated images: boxes and masks apply to every frame.
- HDR images: supported, and the output is still HDR.
- Video: boxes are supported; masks are not and return an error.