Generation

Generation is the core job of the Abyssale API: take a design, override any layer values you want (text, images, colors, visibility…), and get back finished files. Everything you don't override renders exactly as designed — a valid generation request can be as small as a design ID and an empty body.

The flow at a glance

1

Discover the designGET /designs/{designId}

One call returns the design's type, its formats, and every element with its current default values — exactly the names you will target in your request.

2

GeneratePOST /banner-builder/{designId}/generatePOST /async/banner-builder/{designId}/generate

Send your element overrides and output options — synchronously or asynchronously depending on what you produce.

3

Receive the filesinline · webhook · polling

Synchronous responses carry the file URL directly; asynchronous batches arrive on your webhook or by polling the generation request.

Choose your mode

	Synchronous	Asynchronous
Endpoint	POST /banner-builder/{designId}/generate	POST /async/banner-builder/{designId}/generate (+ …/generate-multipage-pdf)
Design types	static only	all four types
Output types	jpeg, png, webp, avif, pdf	those plus mp4, gif, html5, print PDFs
Formats per call	one	one, several, or every format of the design
Response	the generated file, inline	a generation_request_id, immediately
Timing	bounded: ≤ 10 s, typically well under a second	no hard bound — most batches complete within ~2 minutes
Best for	real-time, single-asset flows	batches, video/GIF/HTML5/print, campaign fan-out

Rule of thumb: need one static image right now → synchronous; anything else → asynchronous.

What a design can produce

The design's type decides the possible outputs — request one with image_file_type, or omit it for the default (bold below):

Design type	Output file types
static	jpeg by default — png when the format's background color is transparent — plus webp, avif, pdf
animated	mp4, gif, html5 (ZIP)
printer / printer_multipage	pdf (always)

Asking a type for an output outside its row fails — see the design-type table for the model behind this.

Anatomy of a request

Every body field is optional — omit everything to regenerate the design as designed:

Field	What it does
elements	Per-layer overrides, keyed by layer name: {"title": {"payload": "Hello", "color": "#FF0000"}}. Every overridable property, per layer type, is on Element Properties.
template_format_name (sync) / template_format_names (async)	Which format(s) to generate. Omitted: sync generates the design's first format; async generates every format. An unknown name answers 404 format_not_found.
image_file_type	Output type, within the design type's row above. When omitted: static designs produce jpeg (png when the format's background color is transparent); animated designs default to mp4; print designs always produce pdf.
file_compression_level	Output quality, 1–100 — 100 is the best quality (least compression), 1 the smallest file. Despite the name, higher = better.
html5 / gif / video / print	Output-type-specific options (e.g. html5.click_tag, print.color_profile, gif.repeat) — documented on each asynchronous generation page.
callback_url (async)	Webhook URL that receives the batch when it completes.
original_visual_id	Regenerate an existing visual in place, keeping its share URL (both modes) — see Visual Versioning.

Colors follow the design's space

Color overrides use the same token grammar as everywhere else — hex on static/animated, CMYK on print designs. See Colors & Gradients.

Getting the result

Synchronous — the response body is the finished asset: a file object (url, cdn_url, type, filename) plus the visual's id and sharing_id. See the sample response.

Asynchronous — the immediate response carries only a generation_request_id. Then either:

• Webhook (recommended): the NEW_BANNER_BATCH event delivers every generated file's URL to your callback_url when the batch completes.
• Polling: GET /generation-request/{generationRequestId} answers 202 with {"is_finalized": false, "banners": [], "errors": []} while the batch runs, and 200 with the filled banners[] once finalized. An unknown id is 404 generation_request_not_found; requests expire after 7 days (410 generation_request_gone).

Per-format failures land in the request's errors[] without failing the whole batch.

Costs & limits

• Only successful visual creations count against your plan's credits.
• 429 has three meanings, told apart by id, never by the message text: request_rate_limited (too fast for the endpoint's tier), rate_limit_exceeded (out of credits, or the global 10 requests/second ceiling) and feature_not_in_plan (the design type is not in your plan). See Three different 429s.
• Validation failures answer 400 invalid_payload with a flat errors: [{path, code, message}] array; generation-time failures use machine-readable ids (template_not_found, format_not_found, cannot_build_banner, …) — all on Errors.

After generation

• Visual Versioning — regenerate a visual under its existing share URL instead of minting a new asset.
• Asset Export — bundle generated assets (any output type) into a ZIP, delivered via webhook.
• Dynamic Images — the no-code sibling: one API call mints a public URL, then each personalized variant is just a query string.

Related

• Design Information — find your design ID, formats and element names
• Element Properties — every overridable property per layer type
• Errors — the full error catalogue
• Fonts — font IDs for text overrides
• Full API reference →