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 asexample.comfor it over HTTP and HTTPS,*.example.comfor 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:
curl https://your-site.com/wp-json/sleek-pixel/v1/external/templates \
-H "X-Sleek-Key: pk_..."
{
"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:
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"}}'
{
"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:
<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.