Developers

Appearance

Generate Multi-Format Images ​

Asynchronously generate static images across multiple formats in a single API call. Ideal for multi-channel campaigns where the same design needs to be exported at different dimensions (e.g. Facebook Feed, Instagram Story, LinkedIn Banner) simultaneously.

The API returns a generation_request_id immediately. When generation is complete, Abyssale sends a NEW_BANNER_BATCH webhook event to your callback_url containing the URLs of all generated files. You can also retrieve results by polling using the returned ID.

Endpoint ​

POST/async/banner-builder/{designId}/generateAPI Reference

Generation characteristics ​

  • Supported Design Type: Static
  • Response: Asynchronous
  • Enables batch generation of multiple assets
  • Retrieval methods: Webhooks, Polling

Output file types ​

Supported: JPEG, PNG, WEBP, AVIF, Web PDF

Override the default with the image_file_type parameter: png, jpeg, webp, avif, or pdf.

Key points ​

  • Initial request returns a generation_request_id
  • Retrieve results via webhook or polling
  • Generate all formats of a design by omitting the template_format_names property
  • Provide a callback_url parameter to receive results via webhook

Request body fields ​

All body fields are optional.

FieldTypeRequiredDescription
elementsobjectNoDictionary of element overrides keyed by layer name. See Element Properties. Omit to render the design's saved default content.
template_format_namesarray<string>NoFormat IDs to generate. Omit to generate every format of the design. An entry that doesn't exist on the design answers 404 with id: format_not_found.
callback_urlstring (url)NoWebhook URL notified when the batch completes. Omit to retrieve results by polling.
image_file_typestringNo"png", "jpeg", "webp", "avif" or "pdf". When omitted: jpeg, or png when the format's background color is transparent. pdf (Web PDF) is plan-dependent.
file_compression_levelintegerNoOutput quality, 1–100 — 100 is the best quality (least compression), 1 the smallest file.
original_visual_idstring (uuid)NoRegenerate an existing visual in place — see Visual Versioning. Must target exactly one format.

Sample request ​

Replace {YOUR-API-KEY} and {designId} before running.

bash
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/{designId}/generate
javascript
import abyssale from '@abyssale/sdk';
// Set ABYSSALE_API_KEY env var before running

const { data, error } = await abyssale.generateMultiFormatMedia('{designId}', {
  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" }
  }
});

if (error) console.error(error);
else console.log(data.generation_request_id);
python
from abyssale import Abyssale
# Set ABYSSALE_API_KEY env var before running

with Abyssale() as client:
    accepted = client.generate_multi_format_media("{designId}", {
        "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"},
        },
    })

print(accepted.generation_request_id)

Sample response ​

json
{ "generation_request_id": "df75afa8-5a77-4e03-aeef-6d1b6dd0580a" }