
Bannerly provides you with APIs for [converting HTML/CSS/JS to images](/docs/api/create-image-from-html-template/), [creating images from templates and JSON data](/docs/api/create-image/) and for [taking screenshots](/docs/api/take-screenshots/).
Every request to Bannerly API requires an account and API Key.

## Authorization

Every request which needs to be authorized and have `X-API-KEY` header with API Key.
The API Key is available in the account section in the 'API Keys' tab.
 
![Where to find an API Key for Bannerly?](/docs/where-to-find-an-api-key.png)



Get started


**Bannerly is a simple and user-friendly automation & design tool** that lets you create templates and create images based on that with custom images, texts, QR codes, and more.
It doesn't matter if you are a marketing professional, graphic designer, web developer, or just looking a way to promote your blog - Bannerly can help you 
with sketching and automating your design creation.

Happy designing!

![web-based template editor for image generation](/docs/image-template-designer.png)



Introduction


Bannerly is an easy way to create engaging banners using a drag & drop web-based editor. We put great effort to make it very easy to use. Bannerly focuses on templates' creation,
which allows you to reuse those templates later for other purposes. It allows you to quickly generate banners with different,
texts and images keeping style of your blog or business. 

![Drag & Drop Template Editor for Image Generation](/docs/image-template-designer.png)

## Basics

### Toolset and component list
On the left side there is your toolset. There you will find the list of all available components, components used in your template and an option to save your template.

![Designer toolset and components list](/docs/designer-tools-and-component-list.png)

Blue arrows next to the components list allow you to bring a component forward or backward on canvas.

### Canvas
The most important part of the editor is its center, the canvas on which you can create and edit your templates.

![Bannerly artboard and canvas](/docs/designer-canvas.png)

### Inspector

On the right side there is Inspector. It adjusts for you depending on the selected element of your template. For example, if you click on the image, you will see an option to change image and image styling. When you select text, you will be able to change text and text styling.

![Bannerly inspector](/docs/designer-inspector.png)

Play with the designer, you can't break it, it's in the cloud! We will take care of everything!


Template editor


Here you can find all possible properties for [Template Editor](/docs/general/template-editor/) components.

## What is a component?

A component is an object which can be added to a template canvas [Template Editor](/docs/general/template-editor/).
Every component can be modified using controls in the [Inspector](/docs/general/template-editor/#inspector) or via other integration like REST API, [Zapier](https://zapier.com) or [Make.com](https://make.com).

## What are the component properties?

Property is a value which defines how the component looks or how it behaves on a template. For example: 
- `opacity=0.2` - makes a component nearly visible,
- `opacity=0.0` - makes a component invisible, 
- `rotation=45` - rotates a component by 45 degrees (clock-wise), 
- `src=https://example.com/my-image.png` - changes image source on Image component,
- `text=Hello World` - changes text on Text component,
- `effectName=blur` - sets blur on Image component.

## Common component properties

These properties can be used with every component.

- `y` - y position in pixels
- `x` - x position in pixels
- `rotation` - rotation in degrees 0 - 360
- `opacity` - opacity, eg: `1`, `0`, `0.5`

## Rectangle Component

![rectangle component](/docs/rectangle-component.png)

Properties:
- `color` - rectangle fill color (eg: `rgba(255,255,255, 1)` or `#efefef`)
- `borderColor` - rectangle stroke color (eg: `rgba(255,255,255, 1)` or `#efefef`)
- `radius` - rectangle radius of all corners

## Circle Component

![circle component](/docs/circle-component.png)

Properties:
- `color` - circle fill color (eg: `rgba(255,255,255, 1)` or `#efefef`)
- `borderColor` - circle stroke color (eg: `rgba(255,255,255, 1)` or `#efefef`)
- `borderWidth` - circle stroke width (eg: `5`)

## Text Component

![text component](/docs/text-component.png)

Properties:
- `text` - text value
- `color` - text color (eg: `rgba(255,255,255, 1)` or `#efefef`)
- `borderColor` - text border color (eg: `rgba(255,255,255, 1)` or `#efefef`)
- `borderWidth` - text border width (eg: `5`)
- `textBackgroundColor` - text background color

## QR Code Component

![qr code component](/docs/qr-code-component.png)

Properties:
- `value` - QR code text, URL or anything else to encode
- `color` - QR code color, eg: `rgba(255,255,255, 1)` or `#efefef`

## Image Component

![image component](/docs/image-component.png)

Properties:
- `src` - image URL or base64,
- `objectFit` - cover or contain,
- `effectName` - kodachrome,
- `borderColor` - border color, eg: `rgba(255,255,255, 1)` or `#efefef`,
- `borderWidth` - border width in pixels (eg: `5`)

## Rating Component

![rating component](/docs/rating-component.png)

Properties:
- `value` - active rating value

## SVG Component

![svg component](/docs/svg-component.png)

No additional properties


Component properties


HTML Editor is an advanced way of creating engaging images, banners, charts and more!
You don't have to be a designer, but you need to know HTML and CSS basics
to create a layout for your images.

![HTML Template Editor for Image Generation](/docs/html-template-for-image-generation-merge-fields-output.png)

## Usage

Use merge tags in HTML or CSS tab with the following format
``{{yourMergeTagName}}``

[![Example usage of merge tags in HTML Template Editor](/docs/html-template-for-image-generation-merge-tags.png)](/docs/html-template-for-image-generation-merge-tags.png)

Put sample data 

[![Example usage of merge tags in HTML Template Editor](/docs/html-template-for-image-generation-sample-data.png)](/docs/html-template-for-image-generation-sample-data.png)

Click 'Generate Image' on the right side to see an example output. Bannerly will merge your HTML template and CSS file with Sample Data.

[![Example usage of merge fields in HTML Template Editor](/docs/html-template-for-image-generation-merge-fields-output.png)](/docs/html-template-for-image-generation-merge-fields-output.png)

Read more about [creating images from HTML Templates with API](/docs/api/create-image-from-html-template/).

## What is a merge tag and merge field?

**Merge tag** is a variable name which can be used in HTML Templates in HTML code or in CSS file.

**Merge field** is a mapping dictionary, it is used for mapping specific value into merge tags.

### Example
```json
{
  "mergeTag": "mergeFieldValue"
}
```

Merge tags and merge fields can be used only in [HTML Template Editor](/docs/general/html-template-editor/)


## Working with Arrays

Sample data

```json
{
  "myTitles": [
    "title one",
    "title two"
  ]
}
```

HTML Code

```html
{{#each myTitles}}
  <h1>{{this}}</h1>
{{/each}}
```

## Advanced templating engine usage

Bannerly under the hood uses [Handlebars](https://handlebarsjs.com) library to merge your tags with values. You can read [Handlebars Guide](https://handlebarsjs.com/guide/) to learn more 
about the syntax.


HTML template editor


QR codes are a type of two-dimensional barcode. They are often used for storing URLs to mobile apps or websites, but they can 
do much more! You can create QR codes which stores information about: 

- Contact information (vCards)
- Phone number
- SMS with prefilled text message and phone number
- WiFi password
- Calendar event (iCalc)
- Email with prefilled address, text, and subject

![qr code component](/docs/qr-code-component.png)

## Available formats

### Phone Number

Open phone dialing screen with phone number.

Format
```shell
tel:<PHONE_NUMBER>;
```

Example
```shell
tel:+48111111111;
```

### Text Message

Open SMS application with prefilled phone number and text message.

Example
```shell
smsto:555-555-5555:QR Code Generator by Bannerly
```

### Contact details (vCard)

vCards are used to share whole contact details using QR Codes.

Example
```shell
BEGIN:VCARD
VERSION:2.1
N:John Doe
TEL;HOME;VOICE:555-555-5555
TEL;WORK;VOICE:666-666-6666
EMAIL:jakub@bannerly.io
ORG:Bannerly
URL:https://bannerly.io
END:VCARD
```

### Calendar event (iCal)

Open a calendar with prefilled event details.

Example
```shell
BEGIN:VEVENT
SUMMARY:My Event
DESCRIPTION:Description
LOCATION:Location
DTSTART:20211021T115429Z
END:VEVENT
``` 

### WiFi name and password

Share WiFi name and password with others using QR Code.

Format
```shell
WIFI:S:<SSID>;T:<WEP|WPA|blank>;P:<PASSWORD>;H:<true|false|blank>;
```

Example
```shell
WIFI:S:BannerlyHQ;T:WPA;P:SecretPassword;;
```


### Email with text

Open email client with prefilled email, subject and text body.

Format
```shell
mailto:<EMAIL>?subject=<SUBJECT>&body=<TEXT>
```

Example
```shell
mailto:jakub@bannerly.io?subject=Subject&body=Body
```


## How to add logo to QR code?

To add a logo to your QR code, you can simply put an image on it. Thanks to error correction, your QR code will be still 
readable. The image cannot be too big because error correction won't be able to recover missing data. **Remember to always test your QR code if it's readable by smartphone camera.**




QR code formats



To add a new custom font, open your account settings and go to 'Custom fonts' section.

![Bannerly - custom fonts uploader](/docs/custom-fonts-section.png)


Choose a font file with `.ttf` extension and click 'Upload font'. After successful upload, your font will be ready to use.

To use the uploaded font, open [template editor](/docs/general/template-editor/), add a text component and pick your font from the font selector on the right side. Your custom font should be available on top of the list.

![Example usage of custom font in image template editor](/docs/example-usage-of-custom-font-in-template-editor.png)


Custom fonts

Meta Link is a way of accessing and generating images on demand without using any fancy tools. You only need to 
edit your HTML code. Adjust your `og:image` and `twitter:image` meta links in `<head/>`, and you are good to go. 

![Automatic blog post generation for social media](/docs/automatic-cover-generation-for-blog-posts.jpg)

## How to use?

Go to 'Domains' section in your account and add domain of your blog or website.


Create a meta link according to the following format:
```html
https://get.bannerly.io/og/<MY_TEMPLATE_ID>.jpg?url=<BLOG_POST_URL>
```

Change values: 
- `<MY_TEMPLATE_ID>` - with your template identifier,
- `<BLOG_POST_URL>` - with link to your blog post.

You can use this link in open graph tags to generate an image automatically whenever your blog article is posted on a social media platform like Facebook, Twitter, or other.

### Adjust `meta` tags 

Add or modify your `<meta/>` tags in `<head/>` your blog HTML code.  

```html
<head>
  <meta 
    property="thumbnail" 
    content="https://get.bannerly.io/og/<TEMPLATE_ID>.jpg?url=<BLOG_POST_URL>"/>
  <meta 
    property="og:image" 
    content="https://get.bannerly.io/og/<TEMPLATE_ID>.jpg?url=<BLOG_POST_URL>"/>
  <meta 
    name="twitter:image" 
    content="https://get.bannerly.io/og/<TEMPLATE_ID>.jpg?url=<BLOG_POST_URL>"/>
  <meta 
    name="twitter:card" 
    content="summary_large_image" />  
    
</head>
```

Bannerly will take your page title, description, and image and put it into corresponding components. Correct component naming is very important. Otherwise, Bannerly won't know into which component changes should be applied. 

## Adjust your template component identifiers

Bannerly will automatically pull data from your blog content and put into template. To know which value put into which component you need to adjust your component identifiers to make
sure the website title will show up in the right place on your template.

![Example blog post cover template for automatic article cover generation](/docs/blog-post-cover-for-meta-link-example.png)


### Title

Will be automatically pulled from first `h1` tag in `article` tag.

Component ID: `title`

### Image

Will be automatically pulled from first `img` in `article` tag.

Component ID: `image`

### Author name

Will be automatically pulled from `<meta name="author">` or from HTML tag with the `rel="author"`.

Component ID: `author_name`

### Author photo

Will be pulled automatically from `<img class="author">` or from `<img class="avatar">`.

Component ID: `author_photo`

### Reading time

Will be automatically calculated from text in `<article>` tag and put as `text` property with format `X min read`.

Component ID: `reading_time`

### Description

Will be automatically pulled from `<meta name="description">`.

Component ID: `description`

### Domain

Domain will be automatically generated from your blog post link.

Component ID: `domain`


## HTML Templates

If you created your template in [HTML Template Editor](/docs/general/html-template-editor/), please use merge tags, which are the same as Component IDs above.

Dynamic og:images


By default, [contact@bannerly.io](mailto:contact@bannerly.io) is the best way of contacting support. 
An additional way of getting support is by using a live chat icon available in the bottom right corner. 
If you use live chat you don't have to be always online, the response will be sent to your e-mail address.

**Contacting support - tips & tricks**
- If the problem is connected with the specific template, please always add the template id, template name or anything what allow me to identify the template.
- If you are using live chat, please also provide the e-mail which you used during the Bannerly registration, it helps to identify you and make changes if needed much faster.
- If you just want to chat, then you are also welcomed! 😊

## Changelog

Product updates and changelog can be found [here](https://bannerly.io/changelog/).

## Feature requests

You can submit new feature requests by sending the details at [contact@bannerly.io](mailto:contact@bannerly.io)!

Sincerely, Jakub Pomykała


Support


This endpoint allows you to generate images based on a template created in [Template Editor](/docs/general/template-editor).

## <span class="badge badge-success">POST</span> Endpoint

```html
https://api.bannerly.io/api/v1/render
```

### Sample request

```shell
curl 
    --location 
    --request POST 'https://api.bannerly.io/api/v1/render' \
    --header 'X-API-KEY: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "template": "<TEMPLATE_ID>",
        "changes": [
            {
              "id": "text_1f",
              "color": "#eeeeee",
              "text": "Hello There!",
            },
            {
              "id": "image_6g",
              "src": "https://jpomykala.com/assets/me-2019.jpeg"
            }
        ],
        "metadata": {
          "my-key": "my value"
        }
    }'
```

### Request body

- `template` (required) - template identifier,
- `changes` (optional) - override [component properties](/docs/general/components/) for given template,
- `expires` (optional) - link expiration time in seconds, available values from `1` to `604800`
- `webhookUrl` (optional) - send response to the given URL as a POST request.
- `metadata` (optional) - any JSON object, can be used as metadata container

Read more about [webhooks](/docs/api/webhooks/).

### Successful response
```json
{
  "requestId": "febbd34c-cadf-43e6-926c-5942016aea4e",
  "href": "https://cdn.bannerly.io/.../febbd34c-cadf-43e6-926c-5942016aea4e.jpg"
}
```

### Format options 

You can use a different formats to apply changes in  to create your image from template. 

#### Array 

Changes in `changes` request body field must be formatted as array.

Every array object must contain properties: 
- `id` - component id set it template editor, 
- `property` - component property (eg: `text`),
- `value` - component property value

```shell
"template": "my-template-id",
"changes": [
    {
        "id": "my-component-id",
        "property": "text",
        "value": "This is my text"
    },
    {
        "id": "my-component-id",
        "property": "src",
        "value": "https://my-website.com/image.jpg"
    }
]
```

#### Dictionary

Some integrations (eg: Zapier) doesn't allow providing arrays of objects, for such cases applying changes as dictionary may be a better way of integration.

Changes in `changesDictionary` request body field must be formatted as key-value object.

```shell
"template": "my-template-id",
"changesDictionary": {
  "my-component-id.text": "This is my text", 
  "my-component-id.src": "https://my-website.com/image.jpg", 
}
```

Please note that in dictionary format, your component id cannot contain a dot `.` because Bannerly won't be able to process your request correctly.

## <span class="badge badge-primary">GET</span> Endpoint

```html
https://api.bannerly.io/direct/MY_TEMPLATE_ID.jpg?componentId.property=value
```
Use [Query String](https://en.wikipedia.org/wiki/Query_string) notation in order to provide changes. 

### Sample request
```html
https://api.bannerly.io/direct/MY_TEMPLATE_ID.jpg?title.text=Hello!&avatar.src=example.com/me.jpg
```

Please note that only the first change element is separated with `?` (question mark) and all 
other changes must be separated with `&` (ampersand).


Create image


This endpoint allows you to create images based on a template designed in [HTML Template Editor](/docs/general/html-template-editor).

## <span class="badge badge-success">POST</span> Endpoint

```html
https://api.bannerly.io/api/v1/render
```

### Example request

```shell
curl 
    --location 
    --request POST 'https://api.bannerly.io/api/v1/render' \
    --header 'X-API-KEY: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "template": "<TEMPLATE_ID>",
        "mergeFields": {
            "myMergeTag": "My HTML Editor Value"
            "myArray": [
                "First",
                "Second"
            ]
        }
    }'
```

### Request body

- `template` (required) - template identifier,
- `mergeFields` (optional) - values for merge fields for given template, 
- `expires` (optional) - link expiration time in seconds, available values from `1` to `604800`,
- `webhookUrl` (optional) - send response to the given URL as a POST request
- `metadata` (optional) - any JSON object, can be used as metadata container

### Successful response
```json
{
  "requestId": "febbd34c-cadf-43e6-926c-5942016aea4e",
  "href": "https://cdn.bannerly.io/.../febbd34c-cadf-43e6-926c-5942016aea4e.jpg"
}
```



Create image from HTML


This endpoint allows you to get a list of all your templates with metadata and preview links.

## <span class="badge badge-success">GET</span> Endpoint

```shell
https://api.bannerly.io/api/v1/my-templates
```

### Example request

```shell
curl 
    --location 
    --request GET 'https://api.bannerly.io/api/v1/my-templates' \
    --header 'X-API-KEY: <API_KEY>' \
    --header 'Content-Type: application/json'
```

### Example response
```json
[
  {
    "identifier": "K0iqvG3BvLN83EfDOI2MrTpoK4Q",
    "href": "https://cdn.bannerly.io/previews/07aqN5tGIQ91Exo0wyk48D2QXpsWc3gNN.jpg",
    "name": "My Template",
    "width": 1000,
    "height": 1400,
    "createdBy": "Jakub Pomykała",
    "isPublic": false
  }
]
```




List templates


This endpoint allows you to list all of your paid requests. It returns records of taken screenshots, and generated images.

## <span class="badge badge-success">GET</span> Endpoint

```shell
https://api.bannerly.io/api/v1/requests
```

### Example request

```shell
curl 
    --location 
    --request GET 'https://api.bannerly.io/api/v1/requests' \
    --header 'X-API-KEY: <API_KEY>' \
    --header 'Content-Type: application/json'
```

### Example response

The response contains two entries. The first entry is a screenshot type and the second entry is an image generated based on the template.

```json
[
    {
        "identifier": "1dDefKaC-58XFhX81sPus1v41SM",
        "href": "https://cdn.bannerly.io/.../febbd34c-cadf-43e6-926c-5942016aea4e.jpg",
        "executeUrl": "https://bannerly.io",
        "status": "200",
        "width": 1366,
        "height": 768,
        "type": "screenshot",
        "createdAt": "2019-09-30T14:00:42"
    },
    {
        "identifier": "old54T8w2TERyZZQSzIcRmiWF4",
        "href": "https://cdn.bannerly.io/.../78f50cb2-e3ce-4016-a292-0d1c9dae81cb.jpg",
        "status": "200",
        "width": 1080,
        "height": 1080,
        "type": "image",
        "template": "OvS9eNpSyXpnIo8rxG7oBndtyWs",
        "templateName": "My Template",
        "changes": "<CHANGES_ARRAY>",
        "createdAt": "2019-09-27T19:44:03"
    }
]
```


List requests


This endpoint allows you to take a screenshot of any website. The screenshot image will be automatically uploaded to S3 bucket, and you will receive a link which could be used anywhere.

## <span class="badge badge-success">POST</span> Endpoint

```shell
https://api.bannerly.io/api/v1/screenshots
```

## Example request

```shell
curl 
    --location 
    --request POST 'https://api.bannerly.io/api/v1/screenshots' \
    --header 'X-API-KEY: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "url": "https://bannerly.io"
        "width": 1366,
        "height": 768,
    }'
```

### Request body

- `url` (required) - website URL of which Bannerly should take a screenshot,
- `height` (required) - screenshot height,
- `width` (required) - screenshot width,
- `expires` (optional) - add expiration time in seconds for the image, (`1` to `604800`),
- `waitTime` (optional) - wait time in milliseconds before taking a screenshot (`500` to `5000`).

## Example response
```json
{
  "requestId": "ed39c85ac41f4c54b95e4caaad4ebff8",
  "href": "https://cdn.bannerly.io/.../image.png",
  "request": {
    "width": 1366,
    "height": 768,
    "url": "https://bannerly.io"
  }
}
```


Take screenshot


Webhooks allow you to notify external services when your image is ready to download. To use webhooks with Bannerly, you need to add a `webhookUrl` field to your image request.

## Render an image and invoke endpoint

```shell
curl 
    --location 
    --request POST 'https://api.bannerly.io/api/v1/render' \
    --header 'X-API-KEY: <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "template": "<TEMPLATE_ID>",
        "webhookUrl": "https://my-service.com/webhook-receiver"
        "changes": [
            {
              "id": "text_1f",
              "text": "Hello There!",
            }
            ...
        ],
    }'
```

### Response returned to client

Bannerly will respond immediately with `requestId` and a link where the rendered image will be saved on.

```shell
{
    "requestId": "febbd34c-cadf-43e6-926c-5942016aea4e"
    "href": "https://cdn.bannerly.io/8af2cacf-a328-4a8f-a4a7-fc6419b5b805/results/febbd34c-cadf-43e6-926c-5942016aea4e.jpg"
}
```

### Request sent to webhook endpoint

After a successful render, Bannerly will send a request to the given `webhookUrl` with `requestId`, `href` and request which has been sent to render the image.

```shell
{
    "requestId": "febbd34c-cadf-43e6-926c-5942016aea4e"
    "href": "https://cdn.bannerly.io/8af2cacf-a328-4a8f-a4a7-fc6419b5b805/results/febbd34c-cadf-43e6-926c-5942016aea4e.jpg"
    "request": {
      //your request
    }
}
```


Zapier

Make (Integromat)

Mailchimp

Wordpress

REST API

HTML to Image

Table of content

Get started

Authorization