Skip to content
Console

Shapes and canvas

Parameter overview

ParameterDescriptionValues
flipFliph horizontal / v vertical / hv both
borderBorder, in the format width,colorWidth in pixels or as a percentage (of the image's short edge)
padPadding on all sidesPixels, 0 ~ 4000
pad-left / pad-top / pad-right / pad-bottomPadding on one sidePixels, 0 ~ 4000
boxSolid box, in the format x,y,w,hPixels or percentages (of the image's width and height)
box-colorBox color. Defaults to blackHex color; semi-transparent allowed
box-radiusBox corner radiusPixels or a percentage (of the box's short edge)
maskShape maskcorners rounded rectangle / ellipse ellipse
corner-radiusCorner radius. Required when mask=cornersA 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 bg color. If bg is 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:

https://demo.bitiful.com/girl.jpeg?box=0,85%25,100%25,15%25&box-color=a0000000&txt=标题文字&txt-pos=0.5,0.96

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=ellipse uses the ellipse inscribed in the image; for a square image, this is a circle.
  • A percentage corner-radius is calculated from the image's short edge, so 50% 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.