Images

To generate an image with the Placid REST API:

  1. Create an API project or add the API integration to your project in Placid
  2. Create and design your template
  3. Send your data and customizations to the API
  4. Poll the GET endpoint for status updates or use a webhook to get the generated image

{info} 1 image = 1 credit

Switch to test mode for free watermarked previews!

Example Call

// - POST to endpoint `https://api.placid.app/api/rest/images`)

{
    ...

    "template_uuid": "ospo24ysn",
    "layers": {
        "img": {
            "image": "https://faywoodwildlife.com/images/lion-singh.jpg"
        },
        "subline": {
            "text": "Employee of the month"
        },
        "title": {
            "text": "Meet Singh"
        }
    },

    ...

    // Options for filename, size modifications, export,..
}

The image object

Properties

{
    "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

Create an image

Create a new image by using the following endpoint and request structure:

Endpoint

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

  "webhook_success": "https://webhook.url",
  "create_now": false,
  "passthrough": null,
  "errors": [],
  "layers": {
      "img": {
          "image": "https://imageurl.jpg"
      },
      "subtitle": {
          "hide": true
      },
      "title": {
          "text": "Lorem Ipsum"
      }
      ...
  },
  "modifications": {
     "width": "<width>",
     "height": "<height>",
     "filename": "<filename>"
  },
  "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
template_uuid Template UUID Template UUID to be used for image creation
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

Image content

The content of your image will be defined by the data in the layers object. See layer properties for possible modifications.

Export / transfer

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!)

File modifications

To modify the generated image use the modifications object.

Field Values
modifications.width Image width
Aspect ratio of template will always be kept to fit into your modifications
modifications.height Image height
Aspect ratio of template will always be kept to fit into your modifications
modifications.filename Filename for the generated image
modifications.image_format Specify the output image format. Allowed values: auto (default; Dynamically selects jpg or png based on canvas transparency), jpg, png, webp
modifications.dpi Define the output DPI of the PDF. Allowed values are 72(default), 150, 300
modifications.color_mode Set to rgb (default) or cmyk

Retrieve an image

This endpoint allows you to retrieve an image by providing their unique id. Refer to the object at the top of this page to see which properties are included with image objects.

Endpoint

Method URI
GET https://api.placid.app/api/rest/images/{id}