# Other sites

Other websites and services, built with WordPress or not, can generate images
from your designs through an API. A public key lists the designs it may use,
the templates, and creates images of them with the values their placeholders
show. Each image is a signed URL that works in an `img` tag and in `og:image`
without a key, so a page can show it and a social network can fetch it.

## Create a key

A public key decides which templates a site or service may use and which
addresses may call the API with it. Keys are created in the workspace's
**Settings**, in the **Public keys** section:

- **New key for**: `sleek-pixel/template`.
- **Item id (optional)**: the id of the one design the key may use. Left
  empty, the key may use every published design.
- **Name**: what the key is called in the list.
- **Allowed origins**: the addresses allowed to call the API with the key,
  separated by commas: an origin such as `https://shop.example.com`, a domain
  such as `example.com` for it over HTTP and HTTPS, `*.example.com` for its
  subdomains, or `*` for any. A server that calls the API sends no address, so
  its key needs `*`; keep such a key on that server.

Saving creates the key, a `pk_` followed by forty characters, and shows it
under **Created key**. Its **Revoke** switch, saved, stops the key from
listing templates and creating images. The URLs it already created keep
showing their images.

## List the templates

The templates are your published designs. Send the key in the `X-Sleek-Key`
header:

```bash
curl https://your-site.com/wp-json/sleek-pixel/v1/external/templates \
  -H "X-Sleek-Key: pk_..."
```

```json
{
  "items": [
    {
      "id": 12,
      "name": "Blog card",
      "width": 1200,
      "height": 630,
      "parameters": ["custom.subtitle", "post.title", "site.title"]
    }
  ]
}
```

A template's `parameters` are the placeholders its elements read, such as
`{post.title}` in a text, and the [dynamic data](/docs/pixel/dynamic-data.md) its
texts and images are bound to. A key for one design lists only that one.

## Create an image

Post the template's id and a value for any of its parameters:

```bash
curl https://your-site.com/wp-json/sleek-pixel/v1/external/images \
  -H "X-Sleek-Key: pk_..." \
  -H "Content-Type: application/json" \
  -d '{"template": 12, "parameters": {"post.title": "Spring sale", "custom.subtitle": "Until Sunday"}}'
```

```json
{
  "url": "https://your-site.com/wp-json/sleek-pixel/v1/external/image?template=12&values=eyJj...&keyId=3&signature=5f0c...",
  "template": 12,
  "width": 1200,
  "height": 630
}
```

Pixel renders the image at once and answers its `url`. A value is text of at
most 100 characters and takes the place of what your site gives for that
placeholder; a placeholder without a value shows what it shows on your site
with no post, such as the site's title, or nothing for a post's fields. A
`custom.<value>` parameter fills that entry of the
[custom data](/docs/pixel/custom-data.md), whether or not your site adds one, and
the value of an image's source is fetched as its address.

## Show the image

Use the URL wherever an image goes:

```html
<img
  src="https://your-site.com/wp-json/sleek-pixel/v1/external/image?..."
  width="1200"
  height="630"
  alt=""
/>
<meta
  property="og:image"
  content="https://your-site.com/wp-json/sleek-pixel/v1/external/image?..."
/>
```

The URL carries the template, the values and the key's id, signed by your
site, so it needs no key and cannot be changed into another image: a URL
whose values or template were edited answers 404. Changing your site's auth
salt ends every URL's signature. The image comes in the file format of
[the settings](/docs/pixel/settings/options.md).

## Caching

An image is rendered once and kept with the site's other images in
`uploads/sleek-pixel/images`; its URL serves that file afterwards, and
browsers and shared caches keep it for an hour. Saving the design renders it
again on the next request, under the same URL. A design keeps the files of
at most 50 sets of values from other sites, the oldest going first; a URL
whose file has gone renders it again.

## Limits

- Listing templates: 600 requests a minute with one key, 120 from one address.
- Creating images: 120 a minute with one key, 60 from one address.
- Image URLs: 600 requests a minute from one address, of which 30 may render
  an image that is not cached, and 120 renders a minute for the URLs of one
  key.

A request past a limit is answered 429 until the minute ends, with the seconds
to wait as `retry_after`.

## Errors

Each refusal answers JSON with a `code`, a `message` and its status:

| Status | When                                                                                              |
| ------ | ------------------------------------------------------------------------------------------------- |
| 400    | A parameter the template does not read, or a value that is not text of at most 100 characters.    |
| 401    | No key, a key that is not a template key, or a revoked one.                                       |
| 403    | An address the key does not allow, or a design the key is not for.                                |
| 404    | A design that is not published, or an image URL whose template, values or signature were changed. |
| 429    | Past a limit; `retry_after` says how many seconds to wait.                                        |
| 500    | The image could not be rendered.                                                                  |

The operations are listed in the [REST reference](/docs/pixel/reference/rest.md).
