Comment on page
Generate a single image
How to generate synchronously a single image - Abyssale REST API
A single image is 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 a JPEG image synchronously
- Supported template type: Static
- Generation response type: Synchronous
post
https://api.abyssale.com
/banner-builder/{templateId}/generate
Generate image
If no parameter is sent, the generated image will correspond to the first format of the template with the default properties.
Only 2 image filetypes are supported (
jpeg
& png
).By default, Abyssale automatically determine the filetype from the format background color:
- If the background color contains transparency (alpha < 100), the generated image will be a PNG.
- Otherwise, the generated image will be a JPEG.
The default behavior can be overriden by using the
image_file_type
property (accepted values: png or jpeg). Note that if you use jpeg for a template that contains transparency, it will be generated using a black opaque colour (as jpeg does not support transparency).
To ease the creation of your payload, just go to one of your
Template
and choose Abyssale Rest API
in the Generation Methods list. You will find the default associated payload in the console (Feel free to remove unnecessary properties/elements):
To copy the payload to your clipboard, click the Copy Code button.
Do not forget to replace
{YOUR-API-KEY}
and {templateId}
cURL
Javascript
Python
curl -X POST -H "x-api-key:{YOUR-API-KEY}" -H "Content-Type: application/json" \
-d '{
"template_format_name": "main-crisp",
"elements": {
"image": {
"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",
"fitting_type": "cover",
"alignment": "middle center"
},
"text_title": {
"payload": "Send best wishes to your lovelies with little easter gifts!",
"color": "#FFFFFF",
"font_size": 48,
"font": "61566327-33c5-11ea-9877-92672c1b8195",
"font_weight": 700,
"line_height": 120,
"alignment": "top left"
}
}
}' \
https://api.abyssale.com/banner-builder/{templateId}/generate
const axios = require('axios');
const payload = {
"template_format_name": "main-crisp",
"elements": {
"image": {
"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",
"fitting_type": "cover",
"alignment": "middle center"
},
"text_title": {
"payload": "Send best wishes to your lovelies with little easter gifts!",
"color": "#FFFFFF",
"font_size": 48,
"font": "61566327-33c5-11ea-9877-92672c1b8195",
"font_weight": 700,
"line_height": 120,
"alignment": "top left"
}
}
}
axios.post("https://api.abyssale.com/banner-builder/{templateId}/generate", payload, {
headers: {"x-api-key": "{YOUR-API-KEY}", "Content-Type": "application/json", "timeout": 30000}
}).then(response => {
console.log(response.data)
})
import json
import requests
image_generation_payload = {
"template_format_name": "main-crisp",
"elements": {
"image": {
"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",
"fitting_type": "cover",
"alignment": "middle center"
},
"text_title": {
"payload": "Send best wishes to your lovelies with little easter gifts!",
"color": "#FFFFFF",
"font_size": 48,
"font": "61566327-33c5-11ea-9877-92672c1b8195",
"font_weight": 700,
"line_height": 120,
"alignment": "top left"
}
}
}
r = requests.post("https://api.abyssale.com/banner-builder/{templateId}/generate",
headers={"x-api-key": "YOUR-API-KEY", "Content-Type": "application/json"},
data=json.dumps(image_generation_payload),
timeout=30
)
r.json()
{
"id": "5978e8d9-ab34-4735-a2cb-fe95c2c56251",
"file": {
"type": "jpeg",
"url": "https://production-banners.s3.eu-west-1.amazonaws.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
"cdn_url": "https://cdn.abyssale.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
"filename": "996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg"
},
"format": {
"id": "Facebook Feed",
"width": 1200,
"height": 628
},
"template": {
"id": "46d22c62-d134-44d3-a040-138e4ea9ea08",
"name": "Abyssale demo - FB Feed",
"created_at": 1602256303,
"updated_at": 1602685407
}
}
As you can see in the sample response, 2 image urls are returned:
- A link (the
url
property) pointing directly to the Abyssale object storage service (S3).- Hotlinking is allowed (a fair usage policy applies) but is not recommended as those URLs are not designed to have low latency and high transfer speeds features.
- A CDN link (the
cdn_url
property):- Those URL are designed for high-speed & low-latency performance. A limited bandwidth applies to all plans (see the pricing table).
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:
{"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']})."]}}}
{"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. |
Last modified 3mo ago