---
title: 'API Parameters'
description: 'The complete reference of transformation parameters recognized by the TwicPics API.'
category: 'reference'
position: 3
---

# Parameters

<docs-page-description :description="description"></docs-page-description>

For consistency, [transformations](/docs/reference/transformations) use the same format for parameters that represent similar underlying concepts.

## anchor

An _anchor_ represents a border or a corner of an image.

The following literals are accepted:

- `bottom`
- `bottom-left`
- `bottom-right`
- `left`
- `top`
- `top-left`
- `top-right`
- `right`

## angle

An _angle_ represents... an angle.

It can be a [number](#number) in which case it is rounded to the nearest multiple of 90 and represents an angle expressed in degrees.

The following literals are also accepted:
| Literal | Angle |
| - | -:|
| `anticlockwise` | -90° |
| `clockwise` | 90° |
| `counterclockwise` | -90° |
| `flip` | 180° |
| `left` | -90° |
| `reverse` | 180° |
| `right` | 90° |

## axis

An _axis_ represents the horizontal axis, the vertical axis or both.

The following literals are accepted:
| Literal | Axis |
| - | -:|
| `both` | both |
| `h` | horizontal |
| `horizontal` | horizontal |
| `v` | vertical |
| `vertical` | vertical |
| `x` | horizontal |
| `y` | vertical |

## boolean

A _boolean_ represents... a boolean value (true or false).

The following literals are accepted:
| Literal | Boolean |
| - | -:|
| `false` | false |
| `no` | false |
| `off` | false |
| `on` | true |
| `true` | true |
| `yes` | true |

## color

A _color_ represents... a color! It can be specified as:

- a color name like `red` or `green` (see the comprehensive list further down this section),
- a three character hexadecimal value like `76E` for RGB colors with no alpha,
- a four character hexadecimal value like `76E8` for RGB colors with alpha,
- a six character hexadecimal value like `A68040` for RGB colors with no alpha,
- a eight character hexadecimal value like `A6804080` for RGB colors with alpha,
- a CSS-like RGB expression: `rgb(<red>,<green>,<blue>)`,
- a CSS-like RGBA expression: `rgba(<red>,<green>,<blue>,<alpha>)`,
- a CSS-like HSL expression: `hsl(<hue>,<saturation>,<lightness>)`,
- a CSS like HSLA expression: `hsla(<hue>,<saturation>,<lightness>,<alpha>)`.

TwicPics also adds `transparent` so that you can easily create an invisible [placeholder](/docs/reference/placeholders) using `placeholder:transparent`.

Finally, you also have the possibility to add an alpha value to color names, three character hexadecimal colors, and six character hexadecimal color. Simply append the decimal part of the alpha component to the color expression.

| Examples    |                               |
| :---------- | :---------------------------: |
| `violet.25` | <DocColor value="violet.25"/> |
| `008.75`    | <DocColor value="008.75"/>    |
| `808080.3`  | <DocColor value="808080.3"/>  |

Finally, here is the list of all supported color names:

| Name                     | Preview                                    |
| :----------------------- | :----------------------------------------: |
| `alice-blue`             | <DocColor value="alice-blue"/>             |
| `antique-white`          | <DocColor value="antique-white"/>          |
| `aqua`                   | <DocColor value="aqua"/>                   |
| `aquamarine`             | <DocColor value="aquamarine"/>             |
| `azure`                  | <DocColor value="azure"/>                  |
| `beige`                  | <DocColor value="beige"/>                  |
| `bisque`                 | <DocColor value="bisque"/>                 |
| `black`                  | <DocColor value="black"/>                  |
| `blanched-almond`        | <DocColor value="blanched-almond"/>        |
| `blue`                   | <DocColor value="blue"/>                   |
| `blue-violet`            | <DocColor value="blue-violet"/>            |
| `brown`                  | <DocColor value="brown"/>                  |
| `burlywood`              | <DocColor value="burlywood"/>              |
| `cadet-blue`             | <DocColor value="cadet-blue"/>             |
| `chartreuse`             | <DocColor value="chartreuse"/>             |
| `chocolate`              | <DocColor value="chocolate"/>              |
| `coral`                  | <DocColor value="coral"/>                  |
| `cornflower-blue`        | <DocColor value="cornflower-blue"/>        |
| `cornsilk`               | <DocColor value="cornsilk"/>               |
| `crimson`                | <DocColor value="crimson"/>                |
| `cyan`                   | <DocColor value="cyan"/>                   |
| `dark-blue`              | <DocColor value="dark-blue"/>              |
| `dark-cyan`              | <DocColor value="dark-cyan"/>              |
| `dark-goldenrod`         | <DocColor value="dark-goldenrod"/>         |
| `dark-gray`              | <DocColor value="dark-gray"/>              |
| `dark-green`             | <DocColor value="dark-green"/>             |
| `dark-khaki`             | <DocColor value="dark-khaki"/>             |
| `dark-magenta`           | <DocColor value="dark-magenta"/>           |
| `dark-olive-green`       | <DocColor value="dark-olive-green"/>       |
| `dark-orange`            | <DocColor value="dark-orange"/>            |
| `dark-orchid`            | <DocColor value="dark-orchid"/>            |
| `dark-red`               | <DocColor value="dark-red"/>               |
| `dark-salmon`            | <DocColor value="dark-salmon"/>            |
| `dark-sea-green`         | <DocColor value="dark-sea-green"/>         |
| `dark-slate-blue`        | <DocColor value="dark-slate-blue"/>        |
| `dark-slate-gray`        | <DocColor value="dark-slate-gray"/>        |
| `dark-turquoise`         | <DocColor value="dark-turquoise"/>         |
| `dark-violet`            | <DocColor value="dark-violet"/>            |
| `deep-pink`              | <DocColor value="deep-pink"/>              |
| `deep-sky-blue`          | <DocColor value="deep-sky-blue"/>          |
| `dim-gray`               | <DocColor value="dim-gray"/>               |
| `dodger-blue`            | <DocColor value="dodger-blue"/>            |
| `firebrick`              | <DocColor value="firebrick"/>              |
| `floral-white`           | <DocColor value="floral-white"/>           |
| `forest-green`           | <DocColor value="forest-green"/>           |
| `fuchsia`                | <DocColor value="fuchsia"/>                |
| `gainsboro`              | <DocColor value="gainsboro"/>              |
| `ghost-white`            | <DocColor value="ghost-white"/>            |
| `gold`                   | <DocColor value="gold"/>                   |
| `goldenrod`              | <DocColor value="goldenrod"/>              |
| `gray`                   | <DocColor value="gray"/>                   |
| `green`                  | <DocColor value="green"/>                  |
| `green-yellow`           | <DocColor value="green-yellow"/>           |
| `honeydew`               | <DocColor value="honeydew"/>               |
| `hot-pink`               | <DocColor value="hot-pink"/>               |
| `indian-red`             | <DocColor value="indian-red"/>             |
| `indigo`                 | <DocColor value="indigo"/>                 |
| `ivory`                  | <DocColor value="ivory"/>                  |
| `khaki`                  | <DocColor value="khaki"/>                  |
| `lavender`               | <DocColor value="lavender"/>               |
| `lavender-blush`         | <DocColor value="lavender-blush"/>         |
| `lawn-green`             | <DocColor value="lawn-green"/>             |
| `lemon-chiffon`          | <DocColor value="lemon-chiffon"/>          |
| `light-blue`             | <DocColor value="light-blue"/>             |
| `light-coral`            | <DocColor value="light-coral"/>            |
| `light-cyan`             | <DocColor value="light-cyan"/>             |
| `light-goldenrod-yellow` | <DocColor value="light-goldenrod-yellow"/> |
| `light-gray`             | <DocColor value="light-gray"/>             |
| `light-green`            | <DocColor value="light-green"/>            |
| `light-pink`             | <DocColor value="light-pink"/>             |
| `light-salmon`           | <DocColor value="light-salmon"/>           |
| `light-sea-green`        | <DocColor value="light-sea-green"/>        |
| `light-sky-blue`         | <DocColor value="light-sky-blue"/>         |
| `light-slate-gray`       | <DocColor value="light-slate-gray"/>       |
| `light-steel-blue`       | <DocColor value="light-steel-blue"/>       |
| `light-yellow`           | <DocColor value="light-yellow"/>           |
| `lime`                   | <DocColor value="lime"/>                   |
| `lime-green`             | <DocColor value="lime-green"/>             |
| `linen`                  | <DocColor value="linen"/>                  |
| `magenta`                | <DocColor value="magenta"/>                |
| `maroon`                 | <DocColor value="maroon"/>                 |
| `medium-aquamarine`      | <DocColor value="medium-aquamarine"/>      |
| `medium-blue`            | <DocColor value="medium-blue"/>            |
| `medium-orchid`          | <DocColor value="medium-orchid"/>          |
| `medium-purple`          | <DocColor value="medium-purple"/>          |
| `medium-sea-green`       | <DocColor value="medium-sea-green"/>       |
| `medium-slate-blue`      | <DocColor value="medium-slate-blue"/>      |
| `medium-spring-green`    | <DocColor value="medium-spring-green"/>    |
| `medium-turquoise`       | <DocColor value="medium-turquoise"/>       |
| `medium-violet-red`      | <DocColor value="medium-violet-red"/>      |
| `midnight-blue`          | <DocColor value="midnight-blue"/>          |
| `mint-cream`             | <DocColor value="mint-cream"/>             |
| `misty-rose`             | <DocColor value="misty-rose"/>             |
| `moccasin`               | <DocColor value="moccasin"/>               |
| `navajo-white`           | <DocColor value="navajo-white"/>           |
| `navy`                   | <DocColor value="navy"/>                   |
| `old-lace`               | <DocColor value="old-lace"/>               |
| `olive`                  | <DocColor value="olive"/>                  |
| `olive-drab`             | <DocColor value="olive-drab"/>             |
| `orange`                 | <DocColor value="orange"/>                 |
| `orange-red`             | <DocColor value="orange-red"/>             |
| `orchid`                 | <DocColor value="orchid"/>                 |
| `pale-goldenrod`         | <DocColor value="pale-goldenrod"/>         |
| `pale-green`             | <DocColor value="pale-green"/>             |
| `pale-turquoise`         | <DocColor value="pale-turquoise"/>         |
| `pale-violet-red`        | <DocColor value="pale-violet-red"/>        |
| `papaya-whip`            | <DocColor value="papaya-whip"/>            |
| `peach-puff`             | <DocColor value="peach-puff"/>             |
| `peru`                   | <DocColor value="peru"/>                   |
| `pink`                   | <DocColor value="pink"/>                   |
| `plum`                   | <DocColor value="plum"/>                   |
| `powder-blue`            | <DocColor value="powder-blue"/>            |
| `purple`                 | <DocColor value="purple"/>                 |
| `rebecca-purple`         | <DocColor value="rebecca-purple"/>         |
| `red`                    | <DocColor value="red"/>                    |
| `rosy-brown`             | <DocColor value="rosy-brown"/>             |
| `royal-blue`             | <DocColor value="royal-blue"/>             |
| `saddle-brown`           | <DocColor value="saddle-brown"/>           |
| `salmon`                 | <DocColor value="salmon"/>                 |
| `sandy-brown`            | <DocColor value="sandy-brown"/>            |
| `sea-green`              | <DocColor value="sea-green"/>              |
| `seashell`               | <DocColor value="seashell"/>               |
| `sienna`                 | <DocColor value="sienna"/>                 |
| `silver`                 | <DocColor value="silver"/>                 |
| `sky-blue`               | <DocColor value="sky-blue"/>               |
| `slate-blue`             | <DocColor value="slate-blue"/>             |
| `slate-gray`             | <DocColor value="slate-gray"/>             |
| `snow`                   | <DocColor value="snow"/>                   |
| `spring-green`           | <DocColor value="spring-green"/>           |
| `steel-blue`             | <DocColor value="steel-blue"/>             |
| `tan`                    | <DocColor value="tan"/>                    |
| `teal`                   | <DocColor value="teal"/>                   |
| `thistle`                | <DocColor value="thistle"/>                |
| `tomato`                 | <DocColor value="tomato"/>                 |
| `turquoise`              | <DocColor value="turquoise"/>              |
| `violet`                 | <DocColor value="violet"/>                 |
| `wheat`                  | <DocColor value="wheat"/>                  |
| `white`                  | <DocColor value="white"/>                  |
| `white-smoke`            | <DocColor value="white-smoke"/>            |
| `yellow`                 | <DocColor value="yellow"/>                 |
| `yellow-green`           | <DocColor value="yellow-green"/>           |

## coordinates

_Coordinates_ represent a point in an image, specified as a couple of **positive** <span class="api">[lengths](#length)</span> separated by the character `x`:

- the first _length_ is the coordinate along the x-axis (following the width of the image)
- the second _length_ is the coordinate along the y-axis (following the height of the image)

TwicPics uses the same coordinate system as CSS: zero-based, left-to-right and top-to-bottom.

If we take the example of an image that is 640 pixel-wide and 480 pixel-high:

- `0x0` points to the top-left corner pixel
- `639x479` points to the bottom-right corner pixel.

<doc-alert type="info">It is perfectly fine to mix _lengths_ of different _units_ in the same _coordinates_. For instance, in the context of yet another 640 per 480 sample image, _coordinates_ `100x50p` actually translate to `100x240`.</doc-alert>

## crop size

A _crop size_ is a <span class="api">[size](#size)</span> where omitted dimensions are assumed to be the same as the input image.

For instance:

- `320` and `320x-` are equivalent to `320x1s`
- `-x240` is equivalent to `1sx240`

## length

TwicPics _lengths_ are equivalent to CSS length values. They consist of a <span class="api">[number](#number)</span> eventually followed by a _unit_ specifier:

- when no _unit_ is specified, the _length_ is in _pixels_, for instance `50` is a _pixel length_ that can be read as "50 pixels"
- with the _unit_ specifier "s", the _length_ is a _scale_, for instance `(1/3)s` is a _scale length_ that can be read as "one third"
- with the _unit_ specifier "p", the _length_ is a _percentage_, for instance `4.5p` is a _percentage length_ representing "4.5%"

## number

TwicPics _numbers_ can be JSON-encoded number literals or expressions that, when computed, result in an actual number. Expressions are embedded in parenthesis. Operators `+`, `-`, `*` and `/` are supported for additions, subtractions, multiplications and divisions respectively. Classic algebraic precedence is respected and parenthesis can be used to circumvent it.

For instance, `50`, `7.2`, `(1/3)`, `(5*(7+2)/3)` are all valid _numbers_.

## padding

A _padding_ is a list of comma-separated [lengths](#length) that follows the CSS convention:
- `<top>,<right>,<bottom>,<left>`
- `<top>,<horizontal>,<bottom>`
- `<vertical>,<horizontal>`
- `<both>`

For instance, `10,100,23,47`, `0,25p`, `(1/3)s` are all valid _paddings_.

## ratio

A _ratio_ represents the proportional relationship between a width and a height. It is specified as a couple of **strictly positive** <span class="api">[numbers](#number)</span> separated by the character `:`:

- the first _number_ is the number of length units contained in the width
- the second _number_ is the number of length units contained in the height

For instance, the _ratio_ `9:3` indicates that the width is 9-units long while the height is 3-units long. In terms of proportions, the width is (9/3=)3 times longer than the height.

## size

A _size_ represents a 2D area, specified as a couple of **strictly positive** <span class="api">[lengths](#length)</span> separated by the character `x`:

- the first _length_ is the width of the area
- the second _length_ is the height of the area

For instance `640x480` is 640 pixel-wide per 480 pixel-high.

It is possible to omit one of the dimensions using the character `-`. In that case, TwicPics will automatically compute the missing dimension so that the size respects the aspect ratio of the source image. For instance, if the source image is 640 pixel-wide per 480 pixel-high, then _sizes_ `320x-` and `-x240` are both equivalent to `320x240`.

As a shortcut, it is possible to omit the height by specifying just a width. For instance, the _size_ `320` is equivalent to `320x-`.

<doc-alert type="info">It is totally legal to mix _lengths_ of different _units_ in the same _size_. For instance, `10px150` is a perfectly valid size.</doc-alert>