Asynchronous Generation
Asynchronously generate multiple formats of images, videos, GIFs, HTML5 banners, or PDFs in a single API call. The endpoint returns immediately with a generation_request_id — results are delivered via webhook or polling once generation is complete.
Use this endpoint when you need to produce assets across many formats at once, or when the output type requires longer processing time (animated GIFs, videos, print PDFs). For a single on-demand image, use the synchronous endpoint instead.
How it works
- Send a request with your design ID and customization parameters
- Receive a
generation_request_idimmediately - Retrieve results once generation is complete — via webhook or polling
Endpoint
INFO
Multi-page PDF generation uses a different endpoint: POST /async/banner-builder/{designId}/generate-multipage-pdf. See Generate Multi-Page PDF for Printing.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
designId | string (uuid) | Yes | Unique identifier of the design to generate from. |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
elements | object | Yes | Dictionary of element overrides keyed by layer name. See Element Properties. |
template_format_names | array | No | List of format IDs to generate (e.g. ["facebook-feed", "instagram-post"]). Omit or pass an empty array to generate all formats. |
callback_url | string (uri) | No | URL that will receive a POST request with the NewBannerBatch payload when generation completes. |
image_file_type | string | No | Output file type: "png", "jpeg", "webp", "avif", "gif", "pdf", "html5", "mp4", "webm", or "auto". Defaults to the design's configured type. |
file_compression_level | integer | No | Compression level as a percentage (1–100). |
html5 | object | No | HTML5 output options (animated designs only). Fields: page_title, click_tag, ad_network, include_backup_image, repeat. |
gif | object | No | GIF output options (animated designs only). Fields: max_fps (2–9), repeat. |
video | object | No | Video output options (animated designs only). Fields: fps (2–30). |
print | object | No | Print output options (printer designs only). Fields: color_profile (UUID), display_crop_marks. |
original_visual_id | string (uuid) | No | UUID of the original visual this generation is based on. |
Response
| Field | Type | Description |
|---|---|---|
generation_request_id | string (uuid) | Unique identifier of the batch generation request. Use this to poll for status or match incoming webhook events. |
Receiving results
Once generation is complete, Abyssale delivers results in one of three ways:
| Method | How | When to use |
|---|---|---|
| Job-Specific Callback | Include callback_url in the request body | One-time endpoint, or to override the global webhook |
| Global Webhook | Configure a webhook in the Abyssale dashboard subscribed to NEW_BANNER_BATCH | All async results delivered to a single persistent endpoint |
| Polling | Poll GET /generation-request/{generationRequestId} | When you can't receive inbound webhooks |
Webhook payload
Abyssale sends a POST request to the callback URL with the following JSON body:
{
"generation_request_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",
"created_at": 1649942114,
"updated_at": 1649942114
}
}
],
"errors": [
{ "template_format_name": "some-format", "reason": "..." }
]
}Polling
The response is identical to the webhook payload with one addition — an is_finalized boolean. When true, the request is complete and will not change.
- Generation requests are available for 7 days.
- A generation request can take up to 10 minutes to complete.
- The endpoint is rate-limited — do not poll aggressively.
Sample Request
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/{designId}/generateSample Response
{ "generation_request_id": "df75afa8-5a77-4e03-aeef-6d1b6dd0580a" }