NAV
shell

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:

alt text

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

alt text

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

Text:

Button:

Image

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

Parameter Required Description
bannerUid True You will use this banner as a template

Where to find the banner uid ?

You can find the banner uid in the edit page.

alt text alt text

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

Parameter Required Description
format false Change the format of a banner
content.primary_text false Change the banner's primary text
content.secondary_text false Change te banner's secondary text. If the secondary text doesn't exist on the original image it won't be taken into account
content.cta_text false Change the banner's cta text. If there is no cta nothing will happen
content.image_url false Change the image of the original banner. Remember that the url must be public.

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:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401/403 Unauthorized -- Your API key is wrong.
404 Not Found -- The url could not be found.
405 Method Not Allowed -- You tried to access Abyssale with an invalid method.
500 Internal Server Error -- We had a problem with our server. Try again later.