Developers

Appearance

Generate Multi-Format Animated GIFs ​

Asynchronously generate animated GIFs across multiple formats from a single Animated design. Animated GIFs are widely supported across email clients, social platforms, and display ad networks without requiring video playback support.

The API returns immediately and delivers results via a NEW_BANNER_BATCH webhook event to your callback_url when all formats are ready.

Plan requirement

This feature is available from the Pro plan.

Endpoint ​

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

Generation characteristics ​

  • Supported Design Type: Animated
  • Response: Asynchronous
  • Output: Animated GIF per format
  • Set image_file_type: "gif" — animated designs default to "mp4" when omitted
  • Retrieval methods: Webhooks, Polling

Output customization ​

Use the gif property to customize the output:

Frame Rate (FPS) ​

  • Property: max_fps
  • Default: 9 fps
  • Range: 2–9 fps

Repeat ​

  • Property: repeat
  • Default: -1 — repeats indefinitely
  • 0: Play once
  • 1: Play twice, etc.

Why remove duplicate frames

Duplicate frame removal generates a lighter file without compromising visual quality.

json
{
  "gif": {
    "max_fps": 8,
    "repeat": 3
  }
}

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 "gif" — animated designs default to "mp4" when omitted.
gifobjectNoGIF output options: max_fps (2–9, default 9), repeat (−1–100, default -1 = loop forever).
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": "gif",
    "gif": {
      "max_fps": 9,
      "repeat": -1
    },
    "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: "gif",
  gif: { max_fps: 9, repeat: -1 },
  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": "gif",
        "gif": {"max_fps": 9, "repeat": -1},
        "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" }