---
title: 'Placeholders API'
menuTitle: 'Placeholders'
description: 'The complete reference for the TwicPics placeholders API.'
category: 'reference'
position: 5
---

# Placeholders

> The complete reference for the TwicPics placeholders API.

Every [manipulation](transformations#fundamentals) can target a _placeholder_. In that case, TwicPics will compute the final dimensions consequential to the transformations then respond with an SVG image of these dimensions that also displays said dimensions.

## Examples

| Example                                     |                                                      Result                                                      |
| :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------: |
| `cover=1:1/resize=150/placeholder:auto`     |      ![cover=1:1/resize=150/placeholder:auto](https://i.twic.pics/v1/cover=1:1/resize=150/placeholder:auto)      |
| `resize=150x100/placeholder:rgb(128,0,128)` | ![resize=150x100/placeholder:rgb(128,0,128)](<https://i.twic.pics/v1/resize=150x100/placeholder:rgb(128,0,128)>) |
| `placeholder:200x100:medium-violet-red`     |      ![placeholder:200x100:medium-violet-red](https://i.twic.pics/v1/placeholder:200x100:medium-violet-red)      |

## Syntax

A placeholder follows the following syntax: <code><span class="api">placeholder:[<[dimensions](#dimensions)>:]&lt;[colors](#colors)&gt;</span></code>

### Alternative URL format

Using placeholders requires using the following alternative API URL format:

```
https://<sub>.twic.pics/v1/[<manipulation>/]<source_image>
```

where `<source_image>` is a placeholder expression of the form `placeholder:<...>`.

For instance, `https://<sub>.twic.pics/v1/resize=640x480/placeholder:auto` will generate a 640 pixels wide per 480 pixels high gray colored placeholder.

<doc-alert>This alternate URL format is also used internally by [TwicPics Native](/docs/essentials/native).
</doc-alert>

### Working with absolute URLs for paths

If you [used absolute URLs as paths](/docs/essentials/path-configuration#using-absolute-urls) in your domain configuration, you can use:

- absolute `http:` and/or `https:` URLs, provided they have corresponding paths in your domain
- relative URLs, provided they convert to absolute URLs that have corresponding paths in your domain

## Dimensions

Specifying the dimensions of a placeholder is optional. Syntax is `<width>x<height>` where `width` and `height` are strictly positive [numbers](/docs/reference/parameters#number).

It is perfectly valid to create a placeholder with dimensions and no color. In that case, the default colors will be used.

| Example               |                               Result                               |
| :-------------------- | :----------------------------------------------------------------: |
| `placeholder:200x150` | ![placeholder:200x150](https://i.twic.pics/v1/placeholder:200x150) |

<doc-alert type="info">If not specified, the dimensions of a placeholder default to 1920x1080.</doc-alert>

Keep in mind the final dimensions of a placeholder depends on the transformations applied to it. So `resize=(1/10)s/placeholder:auto` will give a placeholder which dimensions are 192 per 108, a tenth of the default ones.

| Example                           |                                            Result                                            |
| :-------------------------------- | :------------------------------------------------------------------------------------------: |
| `resize=(1/10)s/placeholder:auto` | ![resize=(1/10)s/placeholder:auto](<https://i.twic.pics/v1/resize=(1/10)s/placeholder:auto>) |

## Colors

Specifying the colors of a placeholder is mandatory unless dimensions have been specified. Syntax is `[<text>/]background` where `text` and `background` are [color expressions](/docs/reference/parameters#color) to be used for the text and the background of the image respectively.

| Example                       |                                       Result                                       |
| :---------------------------- | :--------------------------------------------------------------------------------: |
| `placeholder:50x50:white/red` | ![placeholder:50x50:white/red](https://i.twic.pics/v1/placeholder:50x50:white/red) |

<doc-alert type="info">If no text color is provided, TwicPics will choose a brightened or darkened version of the background color, whichever yields the best contrast. For a quick placeholder, just use `auto` as the color expression and TwicPics will default to an unobtrusive gray color scheme.</doc-alert>

| Example                    |                                    Result                                    |
| :------------------------- | :--------------------------------------------------------------------------: |
| `placeholder:50x50:orange` | ![placeholder:50x50:orange](https://i.twic.pics/v1/placeholder:50x50:orange) |
| `placeholder:50x50:black`  |  ![placeholder:50x50:black](https://i.twic.pics/v1/placeholder:50x50:black)  |
| `placeholder:50x50:auto`   |   ![placeholder:50x50:auto](https://i.twic.pics/v1/placeholder:50x50:auto)   |