API Reference - Abyssale

Welcome to the Abyssale API Reference!

Let's scale your image production 🚀

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: 5 requests/s
Only successful generated images are counted in your API usage.
Trial plan: 30 requests are included.
Available Integrations: Zapier, Make (ex Integromat) & Airtable (if you prefer using nocode)

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

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.

Get Designs

Retrieve all of your designs (containing for each the id, name, creation date & update date)

Authorizations:

api_key

path Parameters

category_id	string <uuid> Unique identifier (UUID) of a category. Filter designs by a category.
type	string Enum: "static" "animated" "printer" "printer_multipage" Filter designs by one of these types static, animated, printer, printer_multipage

Responses

Response samples

200

Content type

application/json

[{"id": "64238d01-d402-474b-8c2d-fbc957e9d290",
"name": "Ad campaign fall 2025",
"type": "static",
"created_at": 1649942114,
"updated_at": 1649942114,
"category_name": "Fall campaigns",
"preview_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/a9b3c668-7b84-4924-adf0-815dae727d32.png"
}
]

Get Design details

Retrieve the details of a design (general information, formats, elements & properties).

Authorizations:

api_key

path Parameters

designId

required

string <uuid>

Unique identifier (UUID) of the design

Responses

Response samples

200

Content type

application/json

{"id": "64238d01-d402-474b-8c2d-fbc957e9d290",
"name": "Ad campaign fall 2025",
"type": "static",
"created_at": 1649942114,
"updated_at": 1649942114,
"category_name": "Fall campaigns",
"formats": [{"id": "facebook-post",
"width": 1200,
"height": 1200,
"preview_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/a9b3c668-7b84-4924-adf0-815dae727d32.png"
}
],
"elements": [{"name": "element-name",
"type": "text",
"attributes": [{"id": "payload",
"help": "Text content (i.e. Lorem ipsum)",
"values": {"facebook-post": "My image title"
}
}
]
}
]
}

Images

Basically, images are created by injecting your data (and customization parameters) into your design.

The generation process is straightforward:

Create your design in Abyssale (or use one from the Abyssale library)
Send your data through the API
Your image is created. The related image URL is sent back synchronously in the API response.

Generate image

Authorizations:

api_key

path Parameters

designId

required

string <uuid>

Unique identifier (UUID) of the design

Request Body schema: application/json

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).
file_compression_level	integer [ 1 .. 100 ] Percentage of compression applied.

Responses

Request samples

Payload

Content type

application/json

{"elements": {"element-name1": {"background_color": "#FF0000"
},
"element-name2": {"background_color": "#FF0000"
}
},
"template_format_name": "facebook-post",
"file_compression_level": 80
}

Response samples

200

Content type

application/json

{"id": "64238d01-d402-474b-8c2d-fbc957e9d290",
"file": {"type": "jpeg",
"url": "https://production-banners.s3.eu-west-1.amazonaws.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
"cdn_url": "https://cdn.abyssale.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
"filename": "996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg"
},
"format": {"id": "facebook-post",
"width": 1200,
"height": 1200
},
"template": {"id": "64238d01-d402-474b-8c2d-fbc957e9d290",
"name": "Ad campaign fall 2025",
"type": "static",
"created_at": 1649942114,
"updated_at": 1649942114,
"category_name": "Fall campaigns"
}
}

Generate Multi-Format Images/Videos/Pdf

Generate multiple formats of an image/video/pdf at once from a design created in Abyssale. This method is asynchronous and allows to generate several media (images/videos/pdf/gif) with one API call. Of course, it can also be used for single image generation (because of time-constraints for instance).

You can find available formats & elements of a design by calling the GET /designs/{designId} route.

Authorizations:

api_key

path Parameters

designId

required

string <uuid>

Unique identifier (UUID) of the design

Request Body schema: application/json

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.

Responses

Request samples

Payload

Content type

application/json

{"elements": {"element-name1": {"background_color": "#FF0000"
},
"element-name2": {"background_color": "#FF0000"
}
},
"template_format_names": ["facebook-feed",
"instagram-post",
"iab-medium"
],
"callback_url": "http://example.com"
}

Response samples

200

Content type

application/json

{"generation_request_id": "06399fcd-0c21-47da-bd9b-1e653e0453e8"
}

Fonts

Get fonts

Retrieve all of your fonts (custom & google fonts)

Authorizations:

api_key

Responses

Response samples

200

Content type

application/json

[{"id": "61568e7c-33c5-11ea-9877-92672c1b8195",
"name": "Ubuntu Mono",
"available_weights": [100
],
"type": "google"
}
]

Exports

You can generate an export (.zip format) of multiple banners. This process is asynchronous and requires a webhook on your side.

New export Webhook

A new banner export is available

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

Payload

Content type

application/json

{"export_id": "38cb7df3-1160-4824-8531-2bacde2b6517",
"archive_url": "https://production-banners.s3.eu-west-1.amazonaws.com/demo/export_38cb7df3-1160-4824-8531-2bacde2b6517.zip",
"requested_at": 1642150000,
"generated_at": 1642150002
}

Create a banner export

As this method is asynchronous you need to provide a callback URL that will be called back when the export is done. We will do a POST request on this URL with a JSON payload.

Authorizations:

api_key

Request Body schema: application/json

ids required	Array of strings <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

Payload

Content type

application/json

{"ids": ["64238d01-d402-474b-8c2d-fbc957e9d290"
],
"callback_url": "https://your-webhook.com/export-abyssale"
}

Response samples

200

Content type

application/json

{"export_id": "64238d01-d402-474b-8c2d-fbc957e9d290"
}

Files

Generation of files (images/videos or html5) can be listened from the following events. Once a file has been generated, its details can be retrieved from the "Get File" endpoint.

New file Webhook

A new file is available

Request Body schema: application/json

id required	string <uuid>
required	object (File)
	object (Format)
	object (Design)

Responses

Request samples

Payload

Content type

application/json

{"id": "64238d01-d402-474b-8c2d-fbc957e9d290",
"file": {"type": "jpeg",
"url": "https://production-banners.s3.eu-west-1.amazonaws.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
"cdn_url": "https://cdn.abyssale.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
"filename": "996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg"
},
"format": {"id": "facebook-post",
"width": 1200,
"height": 1200
},
"template": {"id": "64238d01-d402-474b-8c2d-fbc957e9d290",
"name": "Ad campaign fall 2025",
"type": "static",
"created_at": 1649942114,
"updated_at": 1649942114,
"category_name": "Fall campaigns"
}
}

New File Batch Webhook

A batch generation of files is completed

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

Payload

Content type

application/json

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"banners": [{"id": "64238d01-d402-474b-8c2d-fbc957e9d290",
"file": {"type": "jpeg",
"url": "https://production-banners.s3.eu-west-1.amazonaws.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
"cdn_url": "https://cdn.abyssale.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
"filename": "996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg"
},
"format": {"id": "facebook-post",
"width": 1200,
"height": 1200
},
"template": {"id": "64238d01-d402-474b-8c2d-fbc957e9d290",
"name": "Ad campaign fall 2025",
"type": "static",
"created_at": 1649942114,
"updated_at": 1649942114,
"category_name": "Fall campaigns"
}
}
],
"errors": [{"template_format_name": "string",
"reason": "string"
}
]
}

Get File

Retrieve the information of a file

Authorizations:

api_key

path Parameters

bannerId

required

string <uuid>

Unique identifier (UUID) of the file

Responses

Response samples

200

Content type

application/json

{"id": "64238d01-d402-474b-8c2d-fbc957e9d290",
"file": {"type": "jpeg",
"url": "https://production-banners.s3.eu-west-1.amazonaws.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
"cdn_url": "https://cdn.abyssale.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg",
"filename": "996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg"
},
"format": {"id": "facebook-post",
"width": 1200,
"height": 1200
},
"template": {"id": "64238d01-d402-474b-8c2d-fbc957e9d290",
"name": "Ad campaign fall 2025",
"type": "static",
"created_at": 1649942114,
"updated_at": 1649942114,
"category_name": "Fall campaigns"
}
}

Projects

Projects allow you to organize your designs into logical groups. Each project can contain multiple designs and helps manage your design assets efficiently.

Get Projects

Retrieve all of your projects (containing id, name & creation date)

Authorizations:

api_key

Responses

Response samples

200

Content type

application/json

[{"id": "9d00e9fe-9bd5-4471-acad-baa702a867e9",
"name": "Animation Tests",
"created_at_ts": 1654763057
},
{"id": "bdf9ab44-f5fd-47ad-881d-a45906901233",
"name": "HTML5 Tests",
"created_at_ts": 1663767647
}
]

Create Project

Create a new project to organize your templates and images

Authorizations:

api_key

Request Body schema: application/json

name

required

string [ 2 .. 100 ] characters

Name of the project

Responses

Request samples

Payload

Content type

application/json

{"name": "Summer Campaign 2024"
}

Response samples

200

Content type

application/json

{"id": "cb2c4add-4867-11f0-96f2-0a00d9eb8f78",
"name": "Summer Campaign 2024",
"created_at_ts": 1749827107
}

Workspace Templates

Workspace templates are shared templates that can be duplicated into your projects. The duplication process is asynchronous and allows you to copy workspace templates into your projects for customization.

Duplicate Workspace Template

Duplicate a workspace template into a project. This operation is asynchronous. Use the returned duplication_request_id to track the duplication progress with the polling endpoint.

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

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

Payload

Content type

application/json

Example

Basic template duplication

{"project_id": "d59adee9-4867-11f0-96f2-0a00d9eb8f78"
}

Response samples

200

Content type

application/json

{"duplication_request_id": "40c32a4e-4869-11f0-96f2-0a00d9eb8f78"
}

Get 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

200

Content type

application/json

Example

Successfully completed duplication

{"request_id": "40c32a4e-4869-11f0-96f2-0a00d9eb8f78",
"status": "COMPLETED",
"created_at_ts": 1749827734,
"completed_at_ts": 1749827736,
"errored_at_ts": null,
"target_project": {"id": "d59adee9-4867-11f0-96f2-0a00d9eb8f78",
"name": "HTML5 Tests",
"created_at_ts": 1749827125
},
"designs": [{"original_design_id": "0c967bd0-4137-4690-ad70-249aa021c68b",
"target_design_id": "afb1a61a-6c50-4bc3-a49b-3381822d4e81",
"target_design_name": "New Design name"
}
]
}

Multi-Pages Pdf

Generate Multi-Pages Pdf

Generate multiple page pdf designed in Abyssale. This method is asynchronous and allows to generate a multiple page printable PDF with one API call. Of course, it can also be used for single image generation (because of time-constraints for instance).

You can find available formats & elements of a design by calling the POST /designs/{designId} route.

Authorizations:

api_key

path Parameters

designId

required

string <uuid>

Unique identifier (UUID) of the design

Request Body schema: application/json

	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

Payload

Content type

application/json

{"pages": {"page_1": {"root": {"background_color": "#FF0000"
}
},
"page_2": {"root": {"background_color": "#FF0000"
}
}
},
"callback_url": "http://example.com"
}

Response samples

200

Content type

application/json

{"generation_request_id": "06399fcd-0c21-47da-bd9b-1e653e0453e8"
}