Generate image
How to generate image - Abyssale REST API
Images are created by sending data and customisation parameters to the POST /banner-builder/{templateId}/generate endpoint, which will respond synchronously with a payload containing the URL of the generated image
Generating an image synchronously
Properties available for each type of component are available here.
If no parameter is sent, the generated image will correspond to the first format of the template with the default properties.

Get the default payload

To ease the creation of your payload, just go to your Template page and choose API on the left menu. You will find the default associated payload in the console (Feel free to remove unnecessary properties/elements):
You can click on the Copy Code to copy the payload.

Sample request

Do not forget to replace {YOUR-API-KEY} and {templateId}
cURL
Javascript
Python
1
curl -X POST -H "x-api-key:{YOUR-API-KEY}" -H "Content-Type: application/json" \
2
-d '{
3
"template_format_name": "main-crisp",
4
"elements": {
5
"image": {
6
"image_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/9c872731-da6f-4923-b342-7c4250ac94cc/assets/370af020-5e56-445d-bdf7-02e819658a8a.jpeg",
7
"fitting_type": "cover",
8
"alignment": "middle center"
9
},
10
"text_title": {
11
"payload": "Send best wishes to your lovelies with little easter gifts!",
12
"color": "#FFFFFF",
13
"font_size": 48,
14
"font": "61566327-33c5-11ea-9877-92672c1b8195",
15
"font_weight": 700,
16
"line_height": 120,
17
"alignment": "top left"
18
}
19
}
20
}' \
21
https://api.abyssale.com/banner-builder/{templateId}/generate
Copied!
1
const axios = require('axios');
2
3
const payload = {
4
"template_format_name": "main-crisp",
5
"elements": {
6
"image": {
7
"image_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/9c872731-da6f-4923-b342-7c4250ac94cc/assets/370af020-5e56-445d-bdf7-02e819658a8a.jpeg",
8
"fitting_type": "cover",
9
"alignment": "middle center"
10
},
11
"text_title": {
12
"payload": "Send best wishes to your lovelies with little easter gifts!",
13
"color": "#FFFFFF",
14
"font_size": 48,
15
"font": "61566327-33c5-11ea-9877-92672c1b8195",
16
"font_weight": 700,
17
"line_height": 120,
18
"alignment": "top left"
19
}
20
}
21
}
22
23
axios.post("https://api.abyssale.com/banner-builder/{templateId}/generate", payload, {
24
headers: {"x-api-key": "{YOUR-API-KEY}", "Content-Type": "application/json", "timeout": 30000}
25
}).then(response => {
26
console.log(response.data)
27
}a
Copied!
1
import json
2
import requests
3
4
image_generation_payload = {
5
"template_format_name": "main-crisp",
6
"elements": {
7
"image": {
8
"image_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/9c872731-da6f-4923-b342-7c4250ac94cc/assets/370af020-5e56-445d-bdf7-02e819658a8a.jpeg",
9
"fitting_type": "cover",
10
"alignment": "middle center"
11
},
12
"text_title": {
13
"payload": "Send best wishes to your lovelies with little easter gifts!",
14
"color": "#FFFFFF",
15
"font_size": 48,
16
"font": "61566327-33c5-11ea-9877-92672c1b8195",
17
"font_weight": 700,
18
"line_height": 120,
19
"alignment": "top left"
20
}
21
}
22
}
23
24
r = requests.post("https://api.abyssale.com/banner-builder/{templateId}/generate",
25
headers={"x-api-key": "YOUR-API-KEY", "Content-Type": "application/json"},
26
data=json.dumps(image_generation_payload),
27
timeout=30
28
)
29
r.json()
Copied!

Sample response

1
{
2
"id": "5978e8d9-ab34-4735-a2cb-fe95c2c56251",
3
"image": {
4
"type": "jpeg",
5
"url": "https://production-banners.s3.eu-west-1.amazonaws.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
6
"cdn_url": "https://cdn.abyssale.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg"
7
},
8
"format": {
9
"id": "Facebook Feed",
10
"width": 1200,
11
"height": 628
12
},
13
"template": {
14
"id": "46d22c62-d134-44d3-a040-138e4ea9ea08",
15
"name": "Abyssale demo - FB Feed",
16
"created_at": 1602256303,
17
"updated_at": 1602685407
18
}
19
}
Copied!

What are the 2 image URLs?

As you can see in the sample response, 2 images urls are returned:

Errors

The Abyssale Image Generation API can return the following error codes :
Code
Description
400
Bad Request Your request is invalid. Either one of the parameter sent in the request is wrong or the generation failed due to one of the given property.
A payload will be returned in the HTTP response explaining the error.
For instance, here are payloads returned:
  • If a given parameter is invalid (here the given color is invalid):
{"message": "body_validation_errors: {'media': {'text_role': ["The following property is invalid: ({'color': ['Must be an hexadecimal color. i.e. #EAEAEA']})."]}}", "errors": {"media": {"text_role": ["The following property is invalid: ({'color': ['Must be an hexadecimal color. i.e. #EAEAEA']})."]}}}
  • If a text cannot be inserted:
{"id": "cannot_build_banner", "message": "Element text_name error: The text 'Welcome to the Abyssale Developer Hub' cannot fit within the defined space."}
401 403
Unauthorized Ensure your API key is the right one.
404
Not Found The route (or the given template) cannot be found.
405
Method Not Allowed You tried to access Abyssale with an invalid method.
429
API Limits reached All of your image generation API calls are consumed: You should upgrade to a higher plan.
500
Internal Server Error Try again later: Contact us on [email protected] if the error occurs.