Generate Single Image

The synchronous generation endpoint generates one image per API call and returns the result immediately in the response body. Use this when you need a single asset on demand and can wait for the response (typically under 3 seconds).

For bulk generation across multiple formats, use the asynchronous endpoint instead.

Endpoint

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

Generation Characteristics

• Supported Design Type: Static
• Response: Synchronous
• Generates a single asset based on provided customization parameters

Output File Types

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

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

File Type Determination

By default, file type is selected automatically based on background transparency:

• Transparent background → PNG
• Opaque background → JPEG

WARNING

When generating a JPEG with transparent elements, those areas will be filled with black. JPEG does not support transparency.

Sample Request

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

curl -X POST \
  -H "x-api-key: {YOUR-API-KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "template_format_name": "main-crisp",
    "elements": {
      "image": {
        "image_url": "https://mycompany.com/image.jpeg",
        "fitting_type": "cover",
        "alignment": "middle center"
      },
      "text_title": {
        "payload": "Send best wishes to your lovelies with little easter gifts!",
        "color": "#FFFFFF",
        "font_size": 48,
        "font_weight": 700,
        "line_height": 120,
        "alignment": "top left"
      }
    }
  }' \
  https://api.abyssale.com/banner-builder/{designId}/generate

API Reference

Path Parameters

Parameter	Type	Required	Description
designId	string (uuid)	Yes	Unique identifier of the design to generate from.

Request Body

Field	Type	Required	Description
elements	object	Yes	Dictionary of element overrides keyed by layer name. See Element Properties.
template_format_name	string	Conditional	Format ID to generate (e.g. "facebook-post"). Required when the design has more than one format.
image_file_type	string	No	Output file type: "png", "jpeg", "webp", "avif", "pdf", or "auto". Defaults to the design's configured type.
file_compression_level	integer	No	Compression level as a percentage. 1 = maximum quality (largest file), 100 = maximum compression (smallest file, lowest quality).

Sample Response

{
  "id": "5978e8d9-ab34-4735-a2cb-fe95c2c56251",
  "version": 1,
  "sharing_id": "5fcec999-2bfb-4dd7-ba38-2d9e16c49149",
  "file": {
    "type": "jpeg",
    "url": "https://production-banners.s3.eu-west-1.amazonaws.com/demo/996739f4-b563-428a-a6e8-dd3cb8bd03d4.jpeg",
    "cdn_url": "https://cdn.abyssale.com/demo/996739f4-b563-428a-a6e8-dd3cb8bd03d4.jpeg",
    "filename": "996739f4-b563-428a-a6e8-dd3cb8bd03d4.jpeg"
  },
  "format": {
    "id": "Facebook Feed",
    "width": 1200,
    "height": 628
  },
  "template": {
    "id": "46d22c62-d134-44d3-a040-138e4ea9ea08",
    "name": "Abyssale demo - FB Feed",
    "created_at": 1602256303,
    "updated_at": 1602685407
  }
}