Developers

Appearance

Asynchronous Generation ​

Endpoint ​

POST/async/banner-builder/{designId}/generateAPI Reference

Path Parameters ​

ParameterTypeRequiredDescription
designIdstring (uuid)YesUnique identifier of the design to generate from.

Request Body ​

FieldTypeRequiredDescription
elementsobjectYesDictionary of element overrides keyed by layer name. See Element Properties.
template_format_namesarrayNoList of format IDs to generate (e.g. ["facebook-feed", "instagram-post"]). Omit or pass an empty array to generate all formats.
callback_urlstring (uri)NoURL that will receive a POST request with the NewBannerBatch payload when generation completes.
image_file_typestringNoOutput file type: "png", "jpeg", "webp", "avif", "gif", "pdf", "html5", "mp4", "webm", or "auto". Defaults to the design's configured type.
file_compression_levelintegerNoCompression level as a percentage (1–100).
html5objectNoHTML5 output options (animated designs only). Fields: page_title, click_tag, ad_network, include_backup_image, repeat.
gifobjectNoGIF output options (animated designs only). Fields: max_fps (2–9), repeat.
videoobjectNoVideo output options (animated designs only). Fields: fps (2–30).
printobjectNoPrint output options (printer designs only). Fields: color_profile (UUID), display_crop_marks.
original_visual_idstring (uuid)NoUUID of the original visual this generation is based on.

Response ​

FieldTypeDescription
generation_request_idstring (uuid)Unique identifier of the batch generation request. Use this to poll for status or match incoming webhook events.

Key Characteristics ​

  • Batch asset creation
  • Supported design types: static, animated, print, print_multipage
  • Asynchronous response
  • Generation tracking via request ID

Generation Process ​

  1. Send design ID and customization parameters
  2. Receive generation_request_id
  3. Retrieve results via:

Async generation flow

Webhook Configuration ​

There are two methods for receiving asynchronous generation results. Only one is required.

MethodHowWhen to use
Job-Specific CallbackInclude callback_url in the request bodyFor a specific, one-time endpoint or to override global settings
Global Webhook EndpointConfigure a webhook in the Abyssale dashboard subscribed to NEW_BANNER_BATCHFor all async results delivered to a single persistent endpoint

Abyssale sends a POST request with a JSON payload to the callback_url (or global endpoint) after generation completes.

Payload Structure ​

json
{
  "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 Configuration ​

Endpoint ​

GET/generation-request/{generationRequestId}API Reference

Notes ​

  • Response is identical to the webhook payload plus an is_finalized boolean. When true, the request is complete and will not change.
  • Generation requests are available for 7 days.
  • The endpoint is rate-limited — do not flood it.
  • A generation request can take up to 10 minutes to complete (Abyssale uses a retry system).

Polling flow

Payload Structure ​

json
{
  "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://...", "filename": "image.jpeg", "cdn_url": "https://..." }
    }
  ],
  "errors": []
}

Sample Request ​

bash
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}/generate

Sample Response ​

json
{ "generation_request_id": "df75afa8-5a77-4e03-aeef-6d1b6dd0580a" }

INFO

This example is for multi-format image generation but works the same way for animated and PDF asynchronous generation.

Next Steps ​