Abyssale API Reference — Image, Video & PDF Generation API (v2026-08-17)

A design moved through the approval workflow — submitted for review, approved, rejected, put on hold, or reset. Use it to tell an internal tool that a creative is cleared for use.

Configured in the dashboard, and filterable. Like newBanner, this event has no callback_url on any endpoint: you subscribe once for the workspace. The subscription can be narrowed to specific designs, in which case changes to any other design are not delivered.

The payload is the design plus the status that triggered the event. That status is frozen at the moment of the change, not read at delivery time — if a design is approved and then rejected, you receive two events carrying APPROVED and REJECTED respectively, rather than two copies of the latest value.

Delivery, retries and the event_type convention are described under Webhooks.

Retrieve all designs available in your Abyssale workspace. Each design defines the visual layout, available formats (dimensions), and configurable elements (text, images, shapes, etc.) that can be overridden during image generation. Filter by design type or project using query parameters.

A design lives in a project. Organisation-level master designs are workspace templates, live in a category, and are listed by GET /workspace-templates instead — they never appear here.

Retrieve the full specification of a design: its formats (dimensions and preview URLs), all configurable elements with their properties, and any template variables defined in text layers. Use this endpoint to discover what data to send in a generation request.

For printer designs, each format additionally carries its print settings read-only: dpi (integer render DPI computed at import time, capped at 300), and bleed_size / safe_size (floats in the design's unit). All three are always present on a printer format — a design with no stored print settings, or with a zone disabled, reports the values the renderer itself uses: dpi: 300 and bleed_size / safe_size of 0, where 0 means the zone is off. Read them unconditionally; there is no need to test for the keys.

For animated designs, the response additionally carries the animation model: a top-level animation object (duration — timeline length in seconds; screenshot_at_s — the HTML5 backup-screenshot moment, null on designs created before it was recorded), a per-element animation object (start_at_s, end_at_s, tweens [{id, type, keyframes}] with raw keyframe objects) on elements that carry timing or tweens, and video/audio media attributes (video_url/audio_url, video_duration, video_muted/audio_muted, max_volume) in the standard attribute shape.

Multipage print designs (printer_multipage) return a different shape. A multipage design has no formats — each page is one format row — so the response carries pages and elements_per_page instead of formats, elements and variables. A client coded against formats[] will not work on a multipage design, and because a dynamic image is minted per format, a multipage design has no dynamic_image_url anywhere in the response (it is a static-only feature in any case).

pages[] items are DesignPage objects, not formats: id (page_1 … page_N), width, height, unit and preview_url — no format uid. elements_per_page is an object keyed by page id (not an array), each value being that page's element list.

The print settings are returned once, at the root — dpi, bleed_size and safe_size describe the document, not a page, because a multipage design has a single print setup. That is the same reason the import declares them at the top level. A page does not repeat them.

Group layers require ?i=advanced. By default this endpoint returns its original released shape, in which no group layer appears at all — its children are listed individually and the group itself is invisible. Pass i=advanced to have them injected (into elements, or into each page's list in elements_per_page on a multipage design). Each one carries layer_ids (one list for the whole design — a group holds the same children in every format), a per-format layout, its computed hidden / locked, and, except on animated designs, a per-format group block of auto-layout settings (auto_layout / direction / placement / gap).

A masked group — one whose members are clipped to a shape — is still type: "group" and additionally carries mask, keyed by format. The geometry can differ per format, but a group is masked in all of its formats or in none, so the presence of mask is what distinguishes a masked group from a plain one.

The per-format read GET /designs/{designId}/formats/{formatSpecifier} is always the advanced view and needs no parameter; there layout, mask and group are flattened to the single format.

Retrieve detailed information for a specific format within a design, including dimensions, unit, preview URL, dynamic image URL, element layout, and variables. Useful for inspecting a single format before generating or building dynamic image URLs.

For printer designs the response additionally carries the format's print settings read-only: dpi (integer render DPI computed at import time, capped at 300), and bleed_size / safe_size (floats in the design's unit, 0 when the zone is off). All three are always present on a printer format; a design with no stored print settings reports the renderer's own defaults (dpi: 300, zones 0).

For animated designs the response additionally carries the design's animation object (duration, screenshot_at_s — seconds), per-element animation timing/tween data, and video/audio media attributes — the same read surface as GET /designs/{designId}.

This endpoint is always the advanced view. Unlike GET /designs/{designId}, it needs no i=advanced parameter: it always returns the full property set and always injects the format's group layers, flattened to this single format (layout, the group block, and the computed hidden / locked are plain values, not keyed by format name). A group that does not exist in the requested format is not emitted.

Multipage print designs (printer_multipage): a multipage design is one document — it has no formats, and its pages are not addressable through this endpoint. Any formatSpecifier yields 404 with id: format_not_found. Read the whole document with GET /designs/{designId} or export it with GET /designs/{designId}/as-import.

Synchronously generate a single image from a design. Send your dynamic data (text, images, colors) as element overrides in the request body and receive the generated file URL immediately in the response.

static designs only. An animated, printer or printer_multipage design answers 400 with id: template_not_static — use asynchronous generation instead. This is a property of the endpoint, not of your plan: a video or a print PDF cannot be produced inside a synchronous request, so there is no combination of parameters that makes this work.

Best for: real-time image generation, single-asset workflows, or when you need the result inline without polling. The rendering budget is hard-capped at 10 seconds: the call returns the finished file within that window or fails with 500 internal_server_error (typical renders take tens of milliseconds).

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

AI features and the 10-second cap. text_to_image is not accepted here — an AI generation takes far longer than the budget, so the field exists only on the asynchronous endpoint and sending it answers 400 invalid_payload. Background removal (remove_bg) is accepted but is deprecated on this endpoint: it adds an AI round-trip before the render, so a large or slow source image can push the call past the cap and fail with 500 internal_server_error rather than returning your asset. Existing integrations keep working; new ones should remove backgrounds asynchronously. auto_focus is unaffected and fully supported here — it runs on Abyssale's own detection model and is fast enough that it does not put the budget at risk.

All body fields are optional — omit elements to render the design's saved default content. A template_format_name that does not exist on the design answers 404 with id: format_not_found (the format is addressed as a resource, so this is a 404 by contract, not a 400).

Asynchronously generate multiple formats of an image, video, GIF, HTML5 banner, or PDF in a single API call. Ideal for bulk banner production, multi-channel marketing campaigns, and programmatic ad creative generation at scale.

Specify one or more format IDs to generate, or omit the list to generate all formats defined in the design. Batches are queued and worker-driven, with no hard completion bound — most complete within a couple of minutes; rely on the webhook or polling, never a fixed wait. Provide a callback_url to receive a webhook notification when generation is complete, or poll GET /generation-request/{generationRequestId} for status.

You can find available formats and elements by calling GET /designs/{designId}.

This is where AI image work belongs. Having no completion bound, this endpoint is the only one that accepts text_to_image (AI generation and inpainting), and it is the recommended home for remove_bg too — both add an AI round-trip that the synchronous endpoint's 10-second cap cannot absorb.

All body fields are optional — omit elements to render the design's saved default content, and omit template_format_names to generate every format. A template_format_names entry that does not exist on the design answers 404 with id: format_not_found (the format is addressed as a resource, so this is a 404 by contract, not a 400).

Asynchronously generate a multi-page print-ready PDF from a printer_multipage design. Each page is defined by a pages dictionary entry, allowing different element overrides per page — ideal for brochures, catalogs, and variable data printing.

Provide a callback_url to receive a webhook when the PDF is ready, or poll GET /generation-request/{generationRequestId} for status.

You can find available formats and elements by calling GET /designs/{designId}.

Poll the status of an asynchronous generation request. Use this endpoint to track the progress of a batch generation operation started with the async generate endpoint. The result is available for 7 days after generation.

Check that an API key is usable, and find out which workspace it belongs to.

This is the endpoint to call when you want to confirm a key works — it runs the whole authentication path and answers 200 only if all of the following hold:

• the key exists,
• it is still active (a revoked key answers 401),
• and, for a workspace key, the plan includes API access (401 api_access_denied otherwise).

The plan check is skipped for a user-scoped key, which therefore answers 200 here whatever the plan. That is not a loophole: a user key is confined to the plugin surface, so a 200 from this endpoint means "this key is live", not "this key can generate". If you need to know whether a key can drive the API, call a real endpoint with it.

Every failure is a 401, whether the key is unknown, revoked, or on a plan without API access. This endpoint does not answer 403.

The response carries the workspace name, so a caller holding several keys can tell which one it has. Integration platforms use it to label a connection.

Do not use GET /ready to test a key. It is a service health check and is exempt from authentication, so it answers 200 regardless of the key you send — including one that has been revoked.

Takes no request body. It is a POST for historical reasons; live integrations depend on the current shape, so it will not be changed.

Retrieve all fonts available in your Abyssale workspace, including Google Fonts and any custom fonts you have uploaded. Use a font's id to override the font on text or button elements in a generation request.

An asynchronous banner export has completed. The ZIP archive containing all requested banners is available at the provided archive_url.

Asynchronously package a set of previously generated assets — any output type (JPEG, PNG, WEBP, AVIF, PDF, MP4, GIF, HTML5 bundle) — into a single ZIP archive for download. Provide a callback_url to receive a webhook notification when the export is ready, containing the archive URL.

A new file (image, video, GIF, HTML5 banner, or PDF) has been generated and is ready to download.

Subscribed in the dashboard, not per request. Unlike the other two events, this one has no callback_url field on any endpoint — it is configured once for the workspace and then fires for every file generated, including files produced outside the API.

Delivery, retries and the event_type convention are described under Webhooks.

An asynchronous batch generation request has completed. Contains the full list of generated files and any per-format errors. Triggered by POST /async/banner-builder/{designId}/generate.

Retrieve the metadata and download URLs for a previously generated file (image, video, GIF, HTML5 banner, or PDF). Returns both the S3 storage URL and a CDN-hosted URL suitable for embedding directly in websites or emails.

Retrieve all projects in your workspace. Projects group designs into logical collections. Only designs that belong to a project are accessible via the API.

Create a new project to organize your designs. Assign designs to this project in the Abyssale editor to make them accessible via the API.

Retrieve the organisation-level master designs shared across your workspace.

A workspace template lives in a category (category_id), not a project — it belongs to the organisation until you duplicate it into a project with POST /workspace-templates/{companyTemplateId}/use. Designs, which do live in a project, are listed by GET /designs; the two listings never overlap.

Items have the same shape as a design, except the grouping fields are named category_id / category_name.

The categories that group your workspace templates. Use an id from here as the category_id filter on GET /workspace-templates.

This is the workspace-template counterpart of GET /projects, which groups designs.

Copy a shared workspace template into one of your projects, creating an editable design instance. The duplication is asynchronous — use the returned duplication_request_id to poll for completion via GET /design-duplication-requests/{duplicateRequestId}.

Poll the status of a template duplication request. Use this endpoint to track the progress of an asynchronous duplication operation.

Alpha. This API is in Alpha. The contract may change without notice and imports created with it are not guaranteed to remain compatible. It is not covered by deprecation policy.

List this company's JSON template imports, newest first.

Use this to recover an import whose id you no longer have. Because the flow is POST → upload → PUT, a client that loses the id between those steps leaves behind an import it cannot otherwise resume or inspect; listing is how you find it again.

Rows are summaries. The unbounded warnings[] array and the error object are served by GET /designs/import/json/{importId} — a row carries warning_count instead, and a links.status pointing at that endpoint.

status filters on the effective status, matching what the item endpoint reports: an import whose presigned upload window has closed counts as FAILED, not WAITING_FOR_VALIDATION.

Lists JSON imports exclusively — imports created through other channels are not returned.

No cursor. Results are capped by limit; narrow with created_after / created_before to reach imports beyond the cap.