API Setup Guide

Hey there 👋 We heard you need some help setting up the Placid API?

Here's a walkthrough to help you get your automation up and running. If you have any troubles you need extra help with, just ask. We’re always happy to help!


Step 1 - Create a template for your images

You can design templates for your share images with our drag and drop editor.

A template is a bit like cloze text: You define the basic layout, and decide which elements should be filled dynamically with content from your articles or pages later.

Design templates for the type of images you want to create in the Templates tab, and customize them to fit your project’s brand. We'd recommend to give meaningful layer names and to fill your layers with meaningful defaults. The defaults will be the fallbacks we use if there is no other content available.

Per default, every layer in your templates will be set to be dynamic – so you can change it via the API. If you have static layers as well, you can uncheck the Element is dynamic option in the layer options.

Step 2 – Implement your image automation

To use your template to automatically create images, you will have to integrate it in your project.

You can use:

  • ...our URL API to use placid.app-image URLs, hosting your images on our servers
  • ...or you prefer our REST API, which we recommend if you want to pre-generate batches of images and store them in your S3 buckets or elsewhere.

Using the URL API

file

You can assemble placid.app image URLs by appending your template ID, and adding parameters to dynamically change the elements and add different text or images. Use the layer names of the dynamic elements in your template as parameter names. (If a parameter won’t work, please check if the layer in your template is set to dynamic.)

Every parameter is optional. If you don’t use it in your URL, we will use the default values or images from your template.

Check our in-depth guide for using the URL parameters of different element types in our documentation. Click on the Integrate-Button of a template you want to implement and choose the URL API. You'll get some example snippets to see how to add Open Graph and Twitter Card images to your site.

Add an image scraper action

If you embed placid.app image URLs directly in your (web-)projects, your images will be generated when they are called for the first time. This may be when the first user visits your page, or when the first crawler reads your metadata. In any case, it would be best to have them ready beforehand.

So we recommend to create an additional image scraper action in the Actions tab of Placid. There you can add the URL to a sitemap of your project and let us regularly crawl all your sites for placid.app image URLs. We will then call these images once to pre-generate them.

Using the REST API

file

If you'd like to flexibly generate images with our REST API, you'll find everything you need to know in our documentation. We also offer PHP and Laravel wrappers.

To get your API token, go to the API token tab in Placid, or click on the integrate button of your template.

If a field doesn't work, please check if the layer in your template is set to dynamic.


We hope you have everything you need to get all set up now with our API! We're always happy to help - just reach out if you need more guidance ✌️