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

Send design ID and customization parameters
Receive generation request ID
Retrieve results via:
- Webhooks
- Polling mechanism

Diagram

API documentation

Generate Multi-Format Images/Videos/Pdf

post

Generate multiple formats of an image/video/pdf at once from a template designed in Abyssale. This method is asynchronous and allows to generate several media (images/videos/pdf/gif) with one API call. Of course, it can also be used for single image generation (because of time-constraints for instance).

You can find available formats & elements of a template by calling the GET /templates/{templateId} route.

Authorizations

x-api-keystringRequired

All of your Abyssale requests must contain a x-api-key header with your API Key.

Path parameters

templateIdstring · uuidRequired

Unique identifier (UUID) of the template

Body

template_format_namesstring[]Optional

Format IDs you would like to generate.

The array can be empty or not provided if you want to generate all formats of this template.

Example: ["facebook-feed","instagram-post","iab-medium"]

callback_urlstring · uriOptional

The url that will be called once generation of your images is done.

We will do a POST request of the NewBannerBatch event on this URL with a JSON payload.

Responses

200

application/json

post

/async/banner-builder/{templateId}/generate

POST /async/banner-builder/{templateId}/generate HTTP/1.1
Host: api.abyssale.com
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 180

{
  "elements": {
    "ANY_ADDITIONAL_PROPERTY": {
      "background_color": "#FF0000"
    }
  },
  "template_format_names": [
    "facebook-feed",
    "instagram-post",
    "iab-medium"
  ],
  "callback_url": "https://example.com"
}

200

{
  "generation_request_id": "123e4567-e89b-12d3-a456-426614174000"
}

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

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

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()

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

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

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

PreviousGenerate single image NextGenerate Multi-Format images

Last updated 1 day ago