# 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](#webhook-configuration) * [Polling mechanism](#polling-configuration) ### Diagram
### API documentation {% openapi src="/files/0SWKw14BhWglHZiDdm6e" path="/async/banner-builder/{templateId}/generate" method="post" %} [api.yaml](https://3568284716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHvY8mOYKzvcoxVpCu4FE%2Fuploads%2Fl3JBKAVLulvhrNPtgnPy%2Fapi.yaml?alt=media\&token=81dddadd-2b10-4f3c-9267-158c43dd3a3e) {% endopenapi %} You can find all layers properties in this [section](/rest-api/generation/element-properties.md) ### Sample request ​Do not forget to replace `{YOUR-API-KEY}` and `{design_id}` {% tabs %} {% tab title="cURL" %} ``` 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 ``` {% endtab %} {% tab title="Javascript" %} ```javascript const axios = require('axios'); const payload = { "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" } } } // Replace {id} by your template ID axios.post("https://api.abyssale.com/async/banner-builder/{designId}/generate", payload, { headers: {"x-api-key": "{YOUR-API-KEY}", "Content-Type": "application/json", "timeout": 30000} }).then(response => { console.log(response.data) }j ``` {% endtab %} {% tab title="Python" %} ```python import json import requests image_generation_payload = { "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" } } } # Do not forget to replace {YOUR-API-KEY} and {template_id} r = requests.post("https://api.abyssale.com/async/banner-builder/{design_id}/generate", headers={"x-api-key": "YOUR-API-KEY", "Content-Type": "application/json"}, data=json.dumps(image_generation_payload), timeout=30 ) r.json() ``` {% endtab %} {% endtabs %} ### Sample response ```json { "generation_request_id": "df75afa8-5a77-4e03-aeef-6d1b6dd0580a" } ``` {% hint style="info" %} This example is for multi format images generation but it works the same way for animated and pdf asynchronous generation {% endhint %} ## Webhook Configuration ### Callback URL Setup There are two distinct methods for receiving asynchronous generation results. Only one method is necessary to receive notifications for any given batch job. | Option 1: Job-Specific Callback | Include the `callback_url` parameter in the JSON body of your asynchronous generation request. | Use this if you need a specific, one-time endpoint or want to override your global settings for a particular request. | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | Option 2: Global Webhook Endpoint |

Configure a new webhook endpoint and subscribe to the NEW\_BANNER\_BATCH event via the Abyssale dashboard settings.

Documentation: Webhooks

| Use this if you want all asynchronous generation results for your workspace delivered automatically to a single, persistent endpoint. | * Abyssale will send complete generation results to this URL (callback\_url OR the webhook endpoint) with a `JSON` payload as a `POST` query. ### Notification Mechanism * Automatic notification after asset generation * Includes successful assets and generation errors ### 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", "type": "static", "created_at": 1649942114, "updated_at": 1649942114, "category_name": "Fall campaigns" } } ], "errors": [ { "template_format_name": "string", "reason": "string" } ] } ``` ### Payload Details (same as [NEW\_BANNER\_BATCH](/webhooks/events/banner-events.md#new_banner_batch) event) * `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 * [Generate Mult-Format images](/rest-api/generation/asynchronous-generation/generate-multi-format-images.md) * [Generate Multi-Format PDFs for Printing](/rest-api/generation/asynchronous-generation/generate-multi-format-pdfs-for-printing.md) * [Generate Multi-Page PDF for Printing](/rest-api/generation/asynchronous-generation/generate-multi-page-pdf-for-printing.md) * [Generate Multi-Format Videos](/rest-api/generation/asynchronous-generation/generate-multi-format-videos.md) * [Generate Multi-Format animated GIFs](/rest-api/generation/asynchronous-generation/generate-multi-format-animated-gifs.md) * [Generate HTML5 Banner Ads](/rest-api/generation/asynchronous-generation/generate-html5-banner-ads.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.abyssale.com/rest-api/generation/asynchronous-generation.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.