# Shapes and canvas

> Flip images, add borders, padding, and solid boxes, or crop images to rounded corners and circles.

## 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 `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.

> **Warning**
>
> 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.
