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

  1. Send design ID and customization parameters

  2. Receive generation request ID

  3. Retrieve results via:

    • Webhooks

    • Polling mechanism

Diagram

API documentation

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"
}

This example is for multi format images generation but it works the same way for animated and pdf asynchronous generation

Webhook Configuration

Callback URL Setup

  • Include callback_url parameter in generation request body

  • Specify your webhook endpoint to receive generation notifications

  • Abyssale will send complete generation results to this URL with a JSON payload as a POST 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 assets

  • errors: Formats that failed generation

  • Each 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