Skip to content

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:

Shell
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 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:

Shell
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, 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.

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.

Stay in the Loop!  

Be the first to hear about new updates, special offers, and helpful tips, delivered straight to your inbox.

We respect your inbox (and your privacy). Read our privacy policy.