Developers

Appearance

Generate HTML5 Banner Ads ​

Asynchronously generate HTML5 banner ads across multiple formats from a single animated design. HTML5 banners are interactive, animation-capable creatives used in programmatic display advertising (Google Display Network, DV360, etc.).

Each format is exported as a self-contained ZIP archive delivered via a NEW_BANNER_BATCH webhook event to your callback_url. Set image_file_type: "html5" in your request body to activate this output type.

Plan requirement

This feature is available from the Suite plan.

Endpoint ​

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

Generation characteristics ​

  • Supported Design Type: Animated
  • Response: Asynchronous
  • Output: ZIP file containing HTML5 assets
  • Set image_file_type: "html5" — animated designs default to "mp4" when omitted
  • Retrieval methods: Webhooks, Polling

Output customization ​

Use the html5 property to customize the output:

click_tag ​

A string used to redirect the user when clicking the ad. Accepts:

  • Direct URL: "https://www.abyssale.com"
  • URL with ad network macro: "[UNENCODED_CLICK_REDIRECT]https://developers.abyssale.com/"

Document properties ​

PropertyDescriptionDefault
page_titleSets the HTML document title
repeat-1 = infinite, 0 = once, positive = N times0
include_backup_imageIncludes backup_image.jpeg in the ZIPfalse

Ad network ​

ad_network optimizes output for a specific platform, applying folder structure, file size limits, and GSAP animation library requirements. It is a free string (max 255) — unknown values are validated downstream; the known values:

ValuePlatform
defaultNo specific constraints
google-adsGoogle Ads
google-marketingFormer DoubleClick
adformAdform
amazon-adsAmazon Ads
adrollAdRoll
json
{
  "image_file_type": "html5",
  "html5": {
    "click_tag": "{MY_CLICK_TAG}",
    "page_title": "My Ad",
    "ad_network": "google-ads",
    "repeat": 0,
    "include_backup_image": false
  }
}

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_typestringNoSet "html5" — animated designs default to "mp4" when omitted.
html5objectNoHTML5 output options: page_title (default "Abyssale page title example"), click_tag (default https://www.abyssale.com), ad_network (default "default"), include_backup_image (default false), repeat (−1–100, default 0).
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",
    "image_file_type": "html5",
    "html5": {
      "click_tag": "{MY_CLICK_TAG}",
      "page_title": "{MY_PAGE_TITLE}",
      "ad_network": "default",
      "repeat": 0,
      "include_backup_image": false
    },
    "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",
  image_file_type: "html5",
  html5: {
    click_tag: "{MY_CLICK_TAG}",
    page_title: "{MY_PAGE_TITLE}",
    ad_network: "default",
    repeat: 0,
    include_backup_image: false
  },
  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",
        "image_file_type": "html5",
        "html5": {
            "click_tag": "{MY_CLICK_TAG}",
            "page_title": "{MY_PAGE_TITLE}",
            "ad_network": "default",
            "repeat": 0,
            "include_backup_image": False,
        },
        "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" }