# 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

<figure><img src="https://3568284716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHvY8mOYKzvcoxVpCu4FE%2Fuploads%2FswuEESpeAr6KobJStbzL%2Fasync.jpg?alt=media&#x26;token=432b04b3-1628-40e1-a169-2d6c20d8d19a" alt=""><figcaption></figcaption></figure>

### API documentation

{% openapi src="<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>" 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](https://developers.abyssale.com/rest-api/generation/element-properties)

### Sample request <a href="#sample-request" id="sample-request"></a>

​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 <a href="#sample-response" id="sample-response"></a>

```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 | <p>Configure a new webhook endpoint and subscribe to the <code>NEW\_BANNER\_BATCH</code> event via the Abyssale dashboard settings.<br><br><a href="../../webhooks/overview-webhooks">Documentation: Webhooks</a></p> | 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](https://developers.abyssale.com/webhooks/events/banner-events#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

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "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": []
}
</code></pre>

#### Diagram

<figure><img src="https://3568284716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHvY8mOYKzvcoxVpCu4FE%2Fuploads%2Fza57igW0SwmNOzFvooXl%2Fpolling.webp?alt=media&#x26;token=8a485a12-f3d0-4f1d-bc99-6e624ada9445" alt=""><figcaption></figcaption></figure>

### Progress your design generation journey by diving deeper into configuration

* [Generate Mult-Format images](https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-format-images)
* [Generate Multi-Format PDFs for Printing](https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-format-pdfs-for-printing)
* [Generate Multi-Page PDF for Printing](https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-page-pdf-for-printing)
* [Generate Multi-Format Videos](https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-format-videos)
* [Generate Multi-Format animated GIFs](https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-format-animated-gifs)
* [Generate HTML5 Banner Ads](https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-html5-banner-ads)