Table of Contents
1. Overview
2. How to Create a Dynamic Image URL
3. Customizable Parameters
4. Security Aspects
5. Coming Features
1. Overview
On this page, you will learn how to generate dynamic images from image templates in DynaPictures by directly linking to them from your pages. Please read about URLs if you are not familiar with this concept yet.
2. How to Create a Dynamic Image URL
With URL parameters you can generate images on the fly just by changing parameters in the image link.
The dynamic image URL is built using the following schema:
https://api.dynapictures.com/links/{TEMPLATE_UID}.png?params={PARAMS}&metadata={METADATA}
You need to replace {TEMPLATE_UID}, {PARAMS} and {METADATA} with your own values. Let's go over each parameter in detail.
TEMPLATE_UID
This is an UID of your image template. you can find it in the upper left corner of the template editor:
PARAMS
The parameter list with custom values for the layers in the image template. The list elements are separated by <> string (two symbols, the < and the >). The individual elements of the string a represented as a trinity of layer name, parameter name, and parameter value. So we can specify the layer we want to customize the parameters for, for instance, an image, and then parameter of this layer, for instance, an imageUrl and then finally we provide the value of the image URL as a last piece. This trinity is written in the following way:
{LAYER_NAME}---{PARAMETER_NAME}___{PARAMETER_VALUE}
The layer name can be found in the list of layers on the left or in the settings panel of a layer when it's selected:
For example, if we want to personalize an image URL of the image layer with the image5 name:
image5---imageUrl___https://dynapictures.com/images/banners/cat1.jpeg
And if we need to personalize text content of the text layer with the text3 name:
text3---text___Hello John!
Finally, here is how the final URL will look like, if we want to customize both image5 and text3 for the image template with UID e26cd0daf7:
https://api.dynapictures.com/links/e26cd0daf7.png?params=text3---text___Hello John!<>image5---imageUrl___https://dynapictures.com/images/banners/cat1.jpeg
METADATA
Custom information can be saved within the generated image and used in the following processing steps of the image workflow. You can specify it in this optional metadata parameter:
https://api.dynapictures.com/links/{TEMPLATE_UID}.png?metadata={METADATA}
For example:
https://api.dynapictures.com/links/e26cd0daf7.png?metadata=John Doe
3. Customizable Parameters
Similar to our REST API, you can pass the following parameters for customization via URL parameters (The parameter name is the second item in the trinity LAYER---PARAM___VALUE):
| text | The text to be rendered in the text layer. |
| color | The color of the text. E.g. #000000, rgb(0,0,0) or rgba(0,0,0,0.5). |
| backgroundColor | The background color of the layer. E.g. #fff, rgb(255,255,255) or rgba(0,0,0,0.5). |
| borderColor | 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 | The border width of the layer. E.g. 1px. |
| borderRadius | The border radius of the layer. E.g. 5px or 50%. |
| imageUrl | The image to be used when rendering an image layer. |
| opacity | Floating-point number representing the transperency of the layer. The 0 makes a layer fully transparent and the 1 leaves it as is. |
| chartColor | The color of the chart. E.g. #000000, rgb(0,0,0) or rgba(0,0,0,0.5). |
| chartLabelColor | 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 | 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 | Data series of the chart. E.g. [8.1, 13.57, 15.75, 17.1]. |
4. Security Aspects
When you embed the image on the page, someone else may look into the code of your page, take the image URL, and then place it on her own website. This will consume your credits. We work on the protection for this case, and will add the URL signature parameter soon. You will need to calculate the signature and sign the request each time when building a URL. This will ensure that only those having a singature key can use your URL parameters.
5. Coming Features
We are going to include a cache parameter, that will allow you to control when the actual image is generated, when the credits are actually consumed, and when the already generated image is cached and returned in the response. Check this page later for updates.