Asynchronous generation
Endpoint
POST /async/banner-builder/{design_id}/generate
Key Characteristics
Batch asset creation
Supports design:
static
animated
print
print_multipage
Asynchronous response
Generation tracking via request ID
Generation Process
Send design ID and customization parameters
Receive generation request ID
Retrieve results via:
Webhooks
Polling mechanism
Diagram

API documentation
Generate multiple formats of an image/video/pdf at once from a template designed in Abyssale. This method is asynchronous and allows to generate several media (images/videos/pdf/gif) with one API call. Of course, it can also be used for single image generation (because of time-constraints for instance).
You can find available formats & elements of a template by calling the GET /templates/{templateId} route.
Unique identifier (UUID) of the template
Format IDs you would like to generate.
The array can be empty or not provided if you want to generate all formats of this template.
["facebook-feed","instagram-post","iab-medium"]
The url that will be called once generation of your images is done.
We will do a POST
request of the NewBannerBatch event on this URL with a JSON payload.
POST /async/banner-builder/{templateId}/generate HTTP/1.1
Host: api.abyssale.com
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 180
{
"elements": {
"ANY_ADDITIONAL_PROPERTY": {
"background_color": "#FF0000"
}
},
"template_format_names": [
"facebook-feed",
"instagram-post",
"iab-medium"
],
"callback_url": "https://example.com"
}
Ok
{
"generation_request_id": "123e4567-e89b-12d3-a456-426614174000"
}
You can find all layers properties in this section
Sample request
​Do not forget to replace {YOUR-API-KEY}
and {design_id}
curl -X POST -H "x-api-key:{YOUR-API-KEY}" -H "Content-Type: application/json" \
-d '{
"callback_url": "https://webhook.mycompany.com/images",
"template_format_names": ["facebook-feed", "instagram-post", "iab-medium"],
"elements": {
"primary_text": {
"payload": "New branding available.",
"color": "#FF0000"
}
}
}' \
https://api.abyssale.com/async/banner-builder/{design_id}/generate
Sample response
{
"generation_request_id": "df75afa8-5a77-4e03-aeef-6d1b6dd0580a"
}
Webhook Configuration
Callback URL Setup
Include
callback_url
parameter in generation request bodySpecify your webhook endpoint to receive generation notifications
Abyssale will send complete generation results to this URL with a
JSON
payload as aPOST
query.
Notification Mechanism
Automatic notification after asset generation
Includes successful assets and generation errors
Payload structure
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"banners": [
{
"id": "64238d01-d402-474b-8c2d-fbc957e9d290",
"file": {
"type": "jpeg",
"url": "https://production-banners.s3.eu-west-1.amazonaws.com/demo/ee6739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
"cdn_url": "https://cdn.abyssale.com/demo/ee6739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
"filename": "ee6739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg"
},
"format": {
"id": "facebook-post",
"width": 1200,
"height": 1200
},
"template": {
"id": "64238d01-d402-474b-8c2d-fbc957e9d290",
"name": "Ad campaign fall 2022",
"type": "static",
"created_at": 1649942114,
"updated_at": 1649942114,
"category_name": "Fall campaigns"
}
}
],
"errors": [
{
"template_format_name": "string",
"reason": "string"
}
]
}
Payload Details
banners
: Successfully generated assetserrors
: Formats that failed generationEach successful banner includes file URLs, design details
Polling configuration
Progress Check Endpoint
GET /generation-request/{generation_request_id}
Response Details
Identical to webhook payload except it contains an additional
is_finalized
boolean property. Once this property is true, the generation request is completed and will never change in the future.
Additionnal information
A generation request will become unavailable after 7 days.
The endpoint is rate limited. Make sure you do not flood it or you will be blocked.
Abyssale uses a retry system, so a generation request can take a maximum of 10 minutes before being completed.
Payload structure
{
"is_finalized": true,
"id": "e38c8e09-5b0e-43ff-b5da-25be6b6e96ae",
"banners": [
{
"id": "28e973cf-1514-4d9b-9db6-cbaca229b040",
"format": {
"id": "half-page",
"width": 300,
"height": 600
},
"template": {
"id": "840420c2-7bd9-45c4-a7cb-c741b16edfcf",
"name": "Test demo",
"created_at": 1692800820,
"updated_at": 1692867258
},
"file": {
"type": "jpeg",
"url": "https://s3abyssale/.../image.jpeg",
"filename": "image.jpeg",
"cdn_url": "https://cdnabyssale/.../image.jpeg"
}
},
{
"id": "660bfd64-9715-47c7-a152-9058da61b562",
"format": {
"id": "facebook-post",
"width": 1200,
"height": 1200
},
"template": {
"id": "840420c2-7bd9-45c4-a7cb-c741b16edfcf",
"name": "Test demo",
"created_at": 1692800820,
"updated_at": 1692867258
},
"file": {
"type": "jpeg",
"url": "https://s3abyssale/.../image2.jpeg",
"filename": "image2.jpeg",
"cdn_url": "https://cdnabyssale/.../image2.jpeg"
}
}
],
"errors": []
}
Diagram

Progress your design generation journey by diving deeper into configuration
Last updated