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

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

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

Ok

application/json

post

HTTPcURLJavaScriptPython

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

Ok

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

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

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

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

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

• Generate Mult-Format images
• Generate Multi-Format PDFs for Printing
• Generate Multi-Page PDF for Printing
• Generate Multi-Format Videos
• Generate Multi-Format animated GIFs
• Generate HTML5 Banner Ads