Abyssale logo
API docs by Redocly

API Reference - Abyssale (1.0.0)

Download OpenAPI specification:

License: Proprietary

Abyssale API Reference

Abyssale is a programmatic creative asset generation API for creating marketing visuals, ad creatives, videos, and print-ready PDFs at scale. Design once in Abyssale, then generate thousands of personalized variations — across every format, channel, and language — via a single REST API call.

This documentation is about the Abyssale Rest API. If you would like to discover other Abyssale features or to have a comprehensive understanding on how everything works, go to the Abyssale developers hub.

Base URL: https://api.abyssale.com

General Rest API information:

  • Data exchange format: JSON. All API calls must contain the Content-Type: application/json header.
  • Rate limits: 10 requests/second
  • Only successful generated assets are counted in your API usage.
  • Trial plan: 30 requests are included.
  • Available Integrations: Zapier, Make (ex Integromat), Airtable & n8n (if you prefer using nocode)

Which approach should I use?

Use case Recommended approach
Personalized images in emails (rendered on open) Static design → Dynamic image URL
Embed a live, customizable image on a website Static design → Dynamic image URL
Single image on demand (synchronous response) Synchronous generation
Bulk campaign creatives across multiple formats Async generation
Animated GIF or video for social/ads Animated design → Async generation with gif or video options
HTML5 banner ads for ad networks Animated design → Async generation with html5 options
Print-ready PDF (single page) Printer design → Async generation with print options
Multi-page print document (brochure, catalog) Printer multipage design → Multi-page PDF

Authentication

Abyssale uses API Key Authentication. Your API key is passed along with every API call, allowing Abyssale to identify your company account and access your data.

How to get your API Key?

api_key

All of your Abyssale requests must contain a x-api-key header with your API Key.

Security Scheme Type: API Key
Header parameter name: x-api-key

Common error responses (applicable to all endpoints):

  • 401 Unauthorized — missing or invalid API key
  • 429 Too Many Requests — rate limit exceeded (10 req/s) or insufficient credits
  • 500 Internal Server Error — unexpected server-side failure

Designs

A design is a layout including at least:

  • one format (dimension, i.e. Facebook feed 1200x628 or IAB 300x250)
  • one element (text, button, image, shape...)

All elements have their own properties that can be customized (color, text payload, image...).

Once designed, all properties of the design will act as a reference for subsequent image generation. Obviously, those properties can be overridden by sending new parameters in the generation API call.

Abyssale provides a list of free template designs in the Template Library page. Feel free to use one to start designing your design instead of doing it from scratch.

All of your designs are listed in the different project pages, only those are accessible via API.

List all designs

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 category using query parameters.

Authorizations:
api_key
query Parameters
project_id
string <uuid>

Unique identifier (UUID) of a project. Filter designs by project.

type
string
Enum: "static" "animated" "printer" "printer_multipage"

Filter designs by one of these types static, animated, printer, printer_multipage

Responses

Response samples

Content type
application/json
[]

Get design details

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.

Authorizations:
api_key
path Parameters
designId
required
string <uuid>

Unique identifier (UUID) of the design

Responses

Response samples

Content type
application/json
{}

Get format details

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.

Authorizations:
api_key
path Parameters
designId
required
string

Unique identifier of the design

formatSpecifier
required
string

Format name or UID

Responses

Response samples

Content type
application/json
{}

Asset Generation

Generate images, animated videos, GIFs, HTML5 banners, and print-ready PDFs programmatically from your Abyssale designs.

The generation workflow is simple:

  1. Build your design in Abyssale (or pick one from the Template Library)
  2. Send your dynamic data — text, images, colors — via the API
  3. Receive the generated asset URL in the response

Use the synchronous endpoint for single-image generation with an immediate response. Use the asynchronous endpoint for bulk banner creation across multiple formats at once — ideal for marketing automation, personalized ad campaigns, and batch asset production at scale.

Generate an image (synchronous)

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.

Best for: real-time image generation, single-asset workflows, or when you need the result inline without polling.

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

Authorizations:
api_key
path Parameters
designId
required
string <uuid>

Unique identifier (UUID) of the design

Request Body schema: application/json
required
required
object (Elements)

A dictionary containing all elements with properties you would like to override form the default design (keys correspond to layer names)

template_format_name
string

Corresponds to the format ID you would like to generate (only mandatory when your design contains several formats).

image_file_type
string
Enum: "png" "jpeg" "webp" "avif" "pdf" "auto"

Output file type. Defaults to the design's configured type when omitted.

file_compression_level
integer [ 1 .. 100 ]

Percentage of compression applied.

Responses

Request samples

Content type
application/json
{
  • "elements": {
    },
  • "template_format_name": "facebook-post",
  • "image_file_type": "png",
  • "file_compression_level": 80
}

Response samples

Content type
application/json
{}

Generate images/videos/PDFs asynchronously (multi-format)

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. 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}.

Authorizations:
api_key
path Parameters
designId
required
string <uuid>

Unique identifier (UUID) of the design

Request Body schema: application/json
required
required
object (Elements)

A dictionary containing all elements with properties you would like to override form the default design (keys correspond to layer names)

template_format_names
Array of strings

Format IDs you would like to generate.

The array can be empty or not provided if you want to generate all formats of this design.

callback_url
string <uri>

The url that will be called once generation of your images is done.

We will do a POST request of the NewBannerBatch event on this URL with a JSON payload.

image_file_type
string
Enum: "png" "jpeg" "webp" "avif" "gif" "pdf" "html5" "mp4" "webm" "auto"

Output file type. Depends on the design type (static/animated/printer). Defaults to the design's configured type when omitted.

file_compression_level
integer [ 1 .. 100 ]

Percentage of compression applied.

object

HTML5 output options (animated designs only)

object

GIF output options (animated designs only)

object

Video output options (animated designs only)

object

Print output options (printer/printer_multipage designs only)

original_visual_id
string <uuid>

UUID of the original visual this generation is based on.

Responses

Request samples

Content type
application/json
{
  • "elements": {
    },
  • "template_format_names": [
    ],
  • "callback_url": "http://example.com",
  • "image_file_type": "png",
  • "file_compression_level": 1,
  • "html5": {
    },
  • "gif": {
    },
  • "video": {
    },
  • "print": {
    },
  • "original_visual_id": "efce0750-ba21-49c4-be6f-4e6125cdc6bb"
}

Response samples

Content type
application/json
{
  • "generation_request_id": "06399fcd-0c21-47da-bd9b-1e653e0453e8"
}

Generate a multi-page PDF (asynchronous)

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}.

Authorizations:
api_key
path Parameters
designId
required
string <uuid>

Unique identifier (UUID) of the design

Request Body schema: application/json
required
required
object (Pages)

A dictionary containing all pages with properties you would like to override form the default design (keys correspond to layer names)

callback_url
string <uri>

The url that will be called once generation of your images is done.

We will do a POST request of the NewBannerBatch event on this URL with a JSON payload.

Responses

Request samples

Content type
application/json
{
  • "pages": {
    },
  • "callback_url": "http://example.com"
}

Response samples

Content type
application/json
{
  • "generation_request_id": "06399fcd-0c21-47da-bd9b-1e653e0453e8"
}

Poll async generation request status

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.

Authorizations:
api_key
path Parameters
generationRequestId
required
string <uuid>

Unique identifier (UUID) of the generation request

Responses

Response samples

Content type
application/json
{}

Fonts

Retrieve the fonts available in your Abyssale workspace. Fonts can be applied to text and button elements during image generation. Two types are supported: Google Fonts (free, always available) and custom fonts uploaded to your workspace.

Reference a font by its ID when overriding the font property in a generation request.

List available fonts

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.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Exports

Export a collection of previously generated banners as a single ZIP archive. Useful for downloading bulk assets for offline use, sharing with creative teams, or archiving a campaign's outputs. The export is processed asynchronously — provide a callback URL to receive a webhook notification when the archive is ready.

Banner export archive ready Webhook

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

Request Body schema: application/json
export_id
string <uuid>

ID of the export

archive_url
string <uri>

The zip public URL

requested_at
number

Timestamp at which the export has been requested

generated_at
number

Timestamp at which the export has been done

Responses

Request samples

Content type
application/json
{}

Export banners as ZIP archive (asynchronous)

Asynchronously package a set of previously generated banners 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.

Authorizations:
api_key
Request Body schema: application/json
required
ids
required
Array of strings <uuid> [ items <uuid > ]

An array of string that corresponds to the banners IDs you would like to export.

callback_url
string <uri>

The url that will be called once the generation of your export is done.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "export_id": "64238d01-d402-474b-8c2d-fbc957e9d290"
}

Files

Retrieve metadata and download URLs for generated files (images, videos, GIFs, HTML5 banners, and PDFs). Listen to webhook events to be notified in real time when a file or batch generation completes.

File generated Webhook

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

Request Body schema: application/json
id
required
string <uuid>
version
integer

Version number of the generated file.

sharing_id
string <uuid>

Identifier used for sharing this generated file.

required
object (File)
object (Format)
object (Design)

Responses

Request samples

Content type
application/json
{}

Batch generation completed Webhook

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.

Request Body schema: application/json
id
required
string <uuid>

Unique identifier (UUID) of the batch generation

required
Array of objects (Banner)

List of generated images

Array of objects

If any errors occur, they will be listed under that property

Responses

Request samples

Content type
application/json
{}

Get generated file

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.

Authorizations:
api_key
path Parameters
bannerId
required
string <uuid>

Unique identifier (UUID) of the file

Responses

Response samples

Content type
application/json
{}

Projects

Projects let you organize your designs into logical groups — for example by campaign, client, or content type. All designs must belong to a project to be accessible via the API. Use projects to scope design retrieval and keep large design libraries manageable.

List projects

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

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create a project

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

Authorizations:
api_key
Request Body schema: application/json
required
name
required
string [ 2 .. 100 ] characters

Name of the project

Responses

Request samples

Content type
application/json
{
  • "name": "Summer Campaign 2024"
}

Response samples

Content type
application/json
{
  • "id": "cb2c4add-4867-11f0-96f2-0a00d9eb8f78",
  • "name": "Summer Campaign 2024",
  • "created_at_ts": 1749827107
}

Workspace Templates

Workspace templates are master designs shared across your organization. Duplicate them into any project to create editable copies — useful for spinning up campaign variants, onboarding new clients, or maintaining brand-consistent starting points. The duplication is processed asynchronously; poll the status endpoint to track progress.

Duplicate a workspace template into a project

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}.

Authorizations:
api_key
path Parameters
companyTemplateId
required
string <uuid>
Example: 0c967bd0-4137-4690-ad70-249aa021c68b

Unique identifier (UUID) of the workspace template to duplicate

Request Body schema: application/json
required
project_id
required
string <uuid>

Target project ID where the template will be duplicated

name
string [ 2 .. 100 ] characters

Optional custom name for the duplicated template

Responses

Request samples

Content type
application/json
Example
{
  • "project_id": "d59adee9-4867-11f0-96f2-0a00d9eb8f78"
}

Response samples

Content type
application/json
{
  • "duplication_request_id": "40c32a4e-4869-11f0-96f2-0a00d9eb8f78"
}

Poll template duplication request status

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

Authorizations:
api_key
path Parameters
duplicateRequestId
required
string <uuid>
Example: 40c32a4e-4869-11f0-96f2-0a00d9eb8f78

Unique identifier (UUID) of the duplication request

Responses

Response samples

Content type
application/json
Example
{
  • "request_id": "40c32a4e-4869-11f0-96f2-0a00d9eb8f78",
  • "status": "COMPLETED",
  • "created_at_ts": 1749827734,
  • "completed_at_ts": 1749827736,
  • "errored_at_ts": null,
  • "target_project": {
    },
  • "designs": [
    ]
}

Dynamic Images

Dynamic images are live image URLs that render on-the-fly based on query parameters. Once created for a design, the URL can be embedded anywhere — emails, websites, social posts — and customized with different text, colors, or images per use case, without additional API calls. Ideal for personalization at scale.

Create a dynamic image URL

Creates a dynamic image URL for a given design. Only one dynamic image is allowed per design. Subsequent calls return the existing dynamic image. Use enable_rate_limit in the request body to enable API rate limiting for this image & enable_production_mode to enable production mode (default is test mode).

Authorizations:
api_key
path Parameters
designId
required
string

Unique identifier of the design

Request Body schema: application/json
required
enable_rate_limit
boolean
Default: false

Enable API rate limiting for this dynamic image

enable_production_mode
boolean
Default: false

Enable Production mode for this dynamic image

Responses

Request samples

Content type
application/json
{
  • "enable_rate_limit": true,
  • "enable_production_mode": true
}

Response samples

Content type
application/json
{}