NAV
shell

Introduction

Welcome to the DynaPictures Image Generation API.

You can use this REST API to generate images dynamically using predefined templates. You need to sign in and create image template(s) first.

Authentication

Provide an API Key in the Authorization header when accessing the API

curl "api_endpoint_here" \
  -H "Authorization: Bearer API_KEY"

Make sure to replace API_KEY with your API key.

DynaPictures uses API keys to allow access to the API. You can sign in and get your API key on the account page or in the API console for a particular image template.

DynaPictures expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer API_KEY

Images

Image Generation

curl -d '{"params":[{"name":"text1","text":"Suspendisse tempus odio","color":"#333","backgroundColor":"#f9f9f9","borderColor":"#ddd","borderWidth":"1px","borderRadius":"5px","opacity":1}]}' \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -X POST https://api.dynapictures.com/designs/<UID>

The above command returns JSON structured like this:

{
  "id": "c13bd141c7",
  "templateId": "debcaw6f99",
  "imageUrl": "https://api.dynapictures.com/images/d12fb6f526/e26ca071c7.png",
  "thumbnailUrl": "https://api.dynapictures.com/images/d12fb6f526/e26ca071c7-thumb.png",
  "retinaThumbnailUrl": "https://api.dynapictures.com/images/d12fb6f526/e26ca071c7-thumb-2x.png",
  "metadata": "",
  "width": 1000,
  "height": 1500
}

Once an image template is designed in DynaPictures, it can be used to generate custom images via the REST API. This endpoint can also be explored interactively, when clicking the "API Console" button for a particular image template.

HTTP Request

POST https://api.dynapictures.com/designs/{UID}

URL Parameters

Parameter Description
UID The ID of an image template to use.

The UID of an image template can be found on the image template page in the top left corner.

Request Body

{  
  "format" : "jpeg",
  "metadata" : "Custom data",
  "params": [
    {
      "name": "canvas",
      "backgroundColor": "#fff"
    },
    {
      "name": "title",
      "text": "Suspe tempus odio",
      "color": "#333",
      "backgroundColor": "#f9f9f9",
      "borderColor": "#ddd",
      "borderWidth": "1px",
      "borderRadius": "5px",
      "opacity": 1
    },
    {
      "name": "text",
      "text": "Morbi nec sit amet",
      "color": "#333",
      "backgroundColor": "#f9f9f9",
      "borderColor": "#ddd",
      "borderWidth": "1px",
      "borderRadius": "5px",
      "opacity": 1
    },
    {
      "name": "image1",
      "imageUrl": "https://dynapictures.com/images/banners/cat1.jpeg",
      "imagePosition": "align",
      "imageAlignH" : "full",
      "imageAlignV" : "top",
      "borderColor": "#ddd",
      "borderWidth": "2px",
      "borderRadius": "5px",
      "opacity": 1
    }    
  ]
}

It is possible to create a new image by customizing image template and providing specific parameters for the image layers as a JSON document in the request body.

The request body must be a JSON document containing the fields below. All properties are optional.

Property Type Description
format String The image format to be used when generating a new image. Can be one of png, jpeg, webp or avif.
metadata String Custom data that can be stored in the generated image object. Can be useful to pass data to the next action when using No-Code tools. For example, the text of the message to be published on the social network along with the image.
params Array of Objects List of custom parameters, specifying new values for the image layers. It's possible to replace text and images, adjust styling, etc. See details below.

There are different parameters available for customization, depending on the layer type. E.g. new texts can be provided for the text layers, new images for the images. Almost all shapes support custom styles for the background, border and opacity.

Each object in the params array corresponds to the image layer we want to customize. The param object may have the following fields:

Parameter Type Description
name String The name of the layer to be customized. It can be found in the settings panel when a layer is selected.
text String The text to be rendered in the text layer.
color String The color of the text. E.g. #000000, rgb(0,0,0) or rgba(0,0,0,0.5).
backgroundColor String The background color of the layer. E.g. #fff, rgb(255,255,255) or rgba(0,0,0,0.5).
borderColor String The border color of the layer. E.g. #000000, rgb(0,0,0) or rgba(0,0,0,0.5). When defining this field, it's a good idea to specify a borderWidth property as well.
borderWidth String The border width of the layer. E.g. 1px.
borderRadius String The border radius of the layer. E.g. 5px or 50%.
imageUrl String The image to be used when rendering an image layer.
imagePosition String The image position inside its container. Possible values:
  • If empty or missing, the image will be centered by default.
  • cro - Crop the image to fill the container leaving no empty space. This option is useful when the image size and aspect ratio is not much different from its container and you need to cut automatically a bit of space on the side(s).
  • ai_face - detect face(s) on the image and crop intelligently so that faces are always visible.
  • cov - cover container by scaling the image to the smallest possible size to fill the container, leaving no empty space. If the proportions of the background differ from the element, the image is cropped either vertically or horizontally.
  • align - Align image inside its container. Provide this parameter and then use the imageAlignH and imageAlignV for exact positioning horizontally and vertically
imageAlignH String Horizontal alignment of an image. Takes effect only if imagePosition parameter is specified and equels to align. Possible values are left, center,right and full. If full is specified, the image will take 100% of the container width.
imageAlignV String Vertical alignment of an image. Takes effect only if imagePosition parameter is specified and equels to align. Possible values are top, center,bottom and full. If full is specified, the image will take 100% of the container height.
imageEffect String Applies graphical effects and adjust rendering of an image. CSS filter value can be applied to an image with the help of this parameter . E.g. grayscale(100%) to convert color photo to black and white image, blur image with blur(4px), drop shadow with drop-shadow(16px 16px 20px red), add sepia filter with sepia(100%), etc.
opacity String Floating-point number representing the transperency of the layer. The 0 makes a layer fully transparent (hidden) and the 1 leaves it as is.
chartColor String The color of the chart. E.g. #000000, rgb(0,0,0) or rgba(0,0,0,0.5).
chartLabelColor Strings The color of the chart labels on the X and Y axis. E.g. #000000, rgb(0,0,0) or rgba(0,0,0,0.5).
chartDataLabels Array of Strings List of labels to be shown on the X axis. E.g. ['2021-01-01', '2021-02-01', '2021-03-01', '2021-04-01']. The values are in the datetime format and also can be provided in the form like 11 Feb 2017 GMT, 9 October 2019 07:37:30 UTC or 2020-04-01 10:35.
chartDataValues Array of Numbers Data series of the chart. E.g. [8.1, 13.57, 15.75, 17.1].

Custom Metadata

Request:

{
  "metadata" : "Custom Value like Username",
  "params": [
    {
      "name": "canvas",
      "backgroundColor": "#fff"
    },
    ...
  ]
}

Response:

{
  "id": "c13bd141c7",
  "templateId": "debcaw6f99",
  "imageUrl": "https://api.dynapictures.com/images/d12fb6f526/e26ca071c7.png",
  "thumbnailUrl": "https://api.dynapictures.com/images/d12fb6f526/e26ca071c7-thumb.png",
  "retinaThumbnailUrl": "https://api.dynapictures.com/images/d12fb6f526/e26ca071c7-thumb-2x.png",
  "metadata" : "Custom Value like Username",
  "width": 1000,
  "height": 1500
}

Custom metadata can be saved in the image object. It can be passed in the metadata field in request JSON. The response object will contain this metadata field and the passed value then.

Response

Parameter Description
templateUid The UID of an image template.
imageUrl The URL of a generated image in PNG format.
thumbnailUrl Thumbnail URL of the generated image, fitting into 300x300px square.
retinaThumbnailUrl Thumbnail URL for retina displays, fitting into 600x600px square.
metadata Custom metadata provided for an image.
width The width of an image.
height The height of an image.

Image Templates

Template List

HTTP Response:

[
  {
    "id": "000d61e4f7",
    "name": "Twitter Template",
    "thumbnail": "https://dynapictures.com/rest/public/designs/000d61e4f7/thumb.png",
    "dateCreated": "2021-05-09T11:54:04.000Z",
    "dateUpdated": "2021-05-09T11:54:26.000Z",
    "layers": [
      {
        "type": "canvas",
        "name": "canvas",
        "width": "650",
        "height": "500",
        "text": null
      },
      {
        "type": "image",
        "name": "image1",
        "width": "304.40606689453125",
        "height": "246.054931640625",
        "text": null
      }
    ]
  },
  {
    "id": "b528e7be1d",
    "name": "Instagram Template",
    "thumbnail": "https://dynapictures.com/rest/public/designs/b528e7be1d/thumb.png",
    "dateCreated": "2021-05-06T20:20:20.000Z",
    "dateUpdated": "2021-05-13T17:24:06.000Z",
    "layers": [
      {
        "type": "canvas",
        "name": "canvas",
        "width": "650",
        "height": "500",
        "text": null
      }
    ]
  }
]

HTTP Request

Get all templates that are ready (the "Sync to Zapier" checkbox is enabled).

GET https://api.dynapictures.com/templates

HTTP Response

The response contains a list of template objects with the following fields:

Parameter Description
id The ID of an image template.
name The name of the template.
thumbnail Thumbnail URL of the template, fitting into 300x300px square.
dateCreated Creation date of the template.
dateUpdated Last modification date of the template.
layers The list of template layers containing type, name and width, height fields.

Template Details

GET https://api.dynapictures.com/templates/{UID}

URL Parameters

Parameter Description
UID The ID of an image template to use.

HTTP Response:

{
  "id": "000d61e4f7",
  "name": "Twitter Template",
  "thumbnail": "https://dynapictures.com/rest/public/designs/000d61e4f7/thumb.png",
  "dateCreated": "2021-05-09T11:54:04.000Z",
  "dateUpdated": "2021-05-09T11:54:26.000Z",
  "layers": [
    {
      "type": "canvas",
      "name": "canvas",
      "width": "650",
      "height": "500",
      "text": null
    },
    {
      "type": "image",
      "name": "image1",
      "width": "304.40606689453125",
      "height": "246.054931640625",
      "text": null
    }
  ]
}

Get details of a single template.

HTTP Response

The response contains template object with the following fields:

Parameter Description
id The ID of an image template.
name The name of the template.
thumbnail Thumbnail URL of the template, fitting into 300x300px square.
dateCreated Creation date of the template.
dateUpdated Last modification date of the template.
layers The list of template layers containing type, name and width, height fields.

Delete Image

Any previously generated image can be deleted via an API endpoint below.

Delete Generated Image

HTTP Request:

DELETE https://api.dynapictures.com/images/ff01d10f8d/9be4738250.png

HTTP Response: 200 OK

No body returned with response

HTTP Request

Send a delete request to remove previously generated image.

DELETE https://api.dynapictures.com/images/{IMAGE_PATH}

Parameters

Parameter Description
IMAGE_PATH The subpath of the image on the server that was provided in the response during image generation. E.g. if the full image URL was https://edge.dynapictures.com/ff01d10f8d/9be4738250.png then IMAGE_PATH is ff01d10f8d/9be4738250.png and the full deletion request will look like DELETE https://api.dynapictures.com/images/ff01d10f8d/9be4738250.png

HTTP Response

Upon successful request completion, the response contains no body. Only the 200/OK code is returned along with the standard headers.

Webhooks

Webhooks enable subscriptions and event-driven processing of the information. It's possible to subscribe to an event like creation of a new template or generation of a new image, so that DynaPictures calls the specified URL when this event occurs and attaches needed data to that request.

Subscribe Webhook

HTTP Request

Sample Request

{    
  "targetUrl" : "https://mycompany.com/webhooks/my-endpoint",
  "eventType" : "NEW_IMAGE",
  "templateId" : "000d61e4f7"  
}

Sample Response

{
  "uid": "610cf03c73",
  "eventType": "NEW_IMAGE",
  "targetUrl": "https://myhooks.com",
  "designUid": "000d61e4f7",
  "dateCreated": "2021-05-25T20:17:36.850Z",
}

POST https://api.dynapictures.com/hooks

Request Body

All fields are required

Field Description
targetUrl The URL of the REST endpoint that will receieve notifications.
eventType Type of the event to subscribe for. Allowed value is NEW_IMAGE.
templateId The UID of the image template, so that this webhook will receieve notifications for new images for this particular template only.

Unsubscribe Webhook

HTTP Request

Sample Request

{    
  "targetUrl" : "https://mycompany.com/webhooks/my-endpoint",
  "eventType" : "NEW_IMAGE",
  "templateId" : "000d61e4f7"  
}

Sample Response

{
  "error": false,
  "message": ""
}

DELETE https://api.dynapictures.com/hooks

Request Body

All fields are required

Field Description
targetUrl The URL of the REST endpoint that will receieve notifications.
eventType Type of the event to subscribe for, the value that was passed when subscribing this webhook.
templateId The UID of the image template, the value that was passed when subscribing this webhook.

Errors

The aikontent API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- Not enough privileges to perform this request.
404 Not Found -- The specified object could not be found.
405 Method Not Allowed -- You tried to access an endpoint with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- You're sending too many requests, slow down.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.