Introduction

Welcome to the Abyssale API!

Abyssale API allows you to generate banners. 2 modes are available:

1. Generate a banner from a template

A template is a layout filled with a bunch of elements. The API call allows to fill their content (image, text, color) dynamically.

You can find a list of public templates under the Templates > Abyssale templates that can give you a good overview and easily start creating new ones.

2. Generate a banner from another banner (Only available for banners coming from the automated generation funnel)

When using the automated generation funnel, once bookmarked, every banner can be either dynamically resized or filled with a new content(Title, SubTitle, CTA). The API allows you to dynamically make both of those actions at once.

Authentication

You need to pass your api key in the x-api-key request header:

# With shell, you can just pass the correct header with each request
curl -H "x-api-key: YOUR-API-KEY" https://api.abyssale.com/ready

Make sure to replace YOUR-API-KEY with your API key. You should get a {"status": "ready"} response from the call abover.

Abyssale uses API keys to allow access to the API.

To get a key: open app.abyssale.com, go to Settings > API and click on the Request an API Key button, your API key will be available. Only the company owner can access this tab.

Currently, in beta, this key is limited to 100 banner generation requests / month in paid plans.

All API requests to the Abyssale server requires you to include your API key in a header that looks like the following:

x-api-key: YOUR-API-KEY

Generate Banners

1. From a template

curl -X POST -H "x-api-key:YOUR-API-KEY" -H "Content-Type: application/json"  \
-d '{
  "elements": {
    "primary_text": {
        "payload": "New branding available.",
        "color": "#FF0000"
    }
  }
}' \
https://api.abyssale.com/banner-builder/{{template_uuid}}/generate

Example of a well formatted json body:

{
  "elements": {
    "primary_text": {
        "payload": "New branding available.",
        "color": "#FF0000"
    },
    "cta": {
        "payload": "Click here"
    },
    "product_image": {
        "image_url": "https://url.com/a-public-url.png"
    }
  }
}

The above command returns JSON structured like this:

{
  "banner": {
    "id": "banner-id"
  },
  "image": {
    "type": "png",
    "url": "https://url.com/banner-id.png"
  }
}

You can find all API directives within the related template page. The API call will be filled with all the elements available within the template. Feel free to remove those that are not required to override.

The template uuid parameter can be found on the top left corner when editing the template:

The elements parameter is a dictionnary that can contain all elements of a template:

Here are the property available for each type of component (all are optional):

Text:

• payload: Text content
• color: Hexa color of the text

Button:

• payload: Text content
• color: Hexa color of the text (i.e. "#EAEAEA")
• background_color: Hexa color of the background

Image

• image_url: A public HTTP(s) link of your image (only JPEG & PNG are supported)

Logo

• image_url: A public HTTP(s) link of your image (only SVG/JPEG & PNG are supported)

Shape

• background_color: The Hexa color of the shape

2. From another banner (Only available for banners coming from the automated generation funnel)

curl -X POST -H "x-api-key:YOUR-API-KEY" -H "Content-Type: application/json"  \
-d '{"content": {"primary_text": "Vary your banner content"}}' \
https://api.abyssale.com/banners/{bannerUid}/generate

Example of a well formatted json body:

{
  "format": "FB_FEED",
  "content": {
    "primary_text": "I want to change the primary text.",
    "secondary_text": "I want to change the secondary text.",
    "cta_text": "I want to change the cta text.",
    "image_url": "http://mywebsite.com/my_image.png"
  }
}

The above command returns JSON structured like this:

{
  "banner": {
    "id": "banner-id",
    "format": "FB_FEED"
  },
  "image": {
    "type": "png",
    "url": "https://url.com/banner-id.png"
  }
}

HTTP Request

POST https://api.abyssale.com/banners/{bannerUid}/generate

Query Parameters

Where to find the banner uid ?

You can find the banner uid in the edit page.

Query Body

Example of a well formatted json body:

{ "format": "FB_FEED", "content": { "primary_text": "I want to change the primary text.", "secondary_text": "I want to change the secondary text.", "cta_text": "I want to change the cta text.", "image_url": "http://mywebsite.com/my_image.png" } }

Formats available:

Facebook:

1. FB_FEED: Ratio 1.91:1 (rectangle)
2. FB_SQUARE: Ratio 1:1 (square)

Google Display Ads (IAB):

1. IAB_300x250: Medium Rectangle - 300x250
2. IAB_300x600: Half Page - 300x600
3. IAB_728_90: Leaderboard - 728x90

Twitter:

1. TW_FEED: Post Ratio 16:9 (rectangle)

2. TW_DMC: Promoted Ratio 1.91:1 (rectangle)

Linkedin:

1. LI_FEED: Post Ratio 1.91:1 (rectangle)

Example of a response

A 200 response looks like this:

{ "banner": { "id": "banner-id", "format": "FB_FEED" }, "image": { "type": "png", "url": "https://url.com/banner-id.png" } }

An error (400) response looks like this:

{ "title": "body_validation_error", "errors": { "content": { "primary_text": [ "Shorter than minimum length 3." ] } } }

Common Errors

The Abyssale API uses the following error codes: