Generate Images


The process of generating an image via the REST API is straightforward:

  • Create an API project in Placid
  • Create and design your template
  • Send your data and customizations of layers to the API
  • Get your generated image. The Placid API will send back the URL of the image in the response.

We recommend storing the image on your servers afterwards, as we only store them for a limited time. You can configure the API call to directly send your image to your S3 compatible bucket as well.

Endpoint

Method URI
POST https://api.placid.app/api/rest/{template_uuid}

Get your {template_uuid} from the template overview in the Templates tab of your Placid API project.

https://placid.app/images/placid-template-id.jpg

Request

Generate an image with a simple request that contains your data and customizations in the layers object. By default all images are created async, which means you have to define a webhook_success URL or poll the polling_url of the response until the status of the response is finished.

{
  "webhook_success": "https://webhook.url",
  "create_now": false,
  "passthrough": null,
  "layers": {
      "img": {
          "image": "https://imageurl.jpg"
      },
      "subtitle": {
          "hide": true
      },
      "title": {
          "text": "Lorem Ipsum"
      }
      ...
  }
  "transfer": {
     "to": "s3",
     "key": "<your key>",
     "secret": "<your secret>",
     "region": "<region name>",
     "bucket": "<bucket name>",
     "visibility": "public",
     "path": "images/image.jpg",
     "endpoint": "https://exampleendpoint.com"
  }
}
Field Values Description
webhook_success Webhook URL After the image is created Placid will POST the response to this Webhook URL
create_now true or false Process the image instantly instead of queueing it. This might fail if your worker is too busy or if you start too many simultaneous requests (check the rate limit)
passthrough string or array Any data added to this parameter will be saved and sent in any subsequent webhooks and requests for this image (max-length is 1024 characters)
layers View Layer Properties Dynamically change the content and properties of your image layers
transfer Additionally transfer the generated image to your storage

To transfer the generated image to your storage use the transfer object.

Field Values
transfer.to s3
transfer.key, transfer.secret Your credentials (Placid never stores them)
transfer.bucket Your bucket name
transfer.visibility public or private
transfer.path File path (Define the full image path starting from the root directory of your bucket, including filename and file extension. Placid will overwrite existing files in the specified directory!)

Response

{
    "id": 1,
    "status": "queued",
    "image_url": null,
    "polling_url": null
}
Field Values
id Unique image id for internal reference
status queued The request has been put into the queue.
finished The image has been created successfully.
error There was an error.
image_url URL to created image or null
polling_url Endpoint that you can GET poll for status updates