Generate a single image

How to generate synchronously a single image - Abyssale REST API

A single image is created by sending data and customisation parameters to the POST /banner-builder/{templateId}/generate endpoint, which will respond synchronously with a payload containing the URL of the generated image

Generating a JPEG image synchronously

• Supported template type: Static

• Generation response type: Synchronous

Generate image

POSThttps://api.abyssale.com/banner-builder/{templateId}/generate

Authorization

api_key

Path parameters

templateId*string (uuid)

Unique identifier (UUID) of the template

Body

application/json

elements*Elements (object)

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

template_format_namestring

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

Example: "facebook-post"

file_compression_levelinteger

Percentage of compression applied.

Example: 80

Response

200

Ok

Body

application/json

id*string (uuid)

Example: "64238d01-d402-474b-8c2d-fbc957e9d290"

image*Image (object)

formatFormat (object)

templateTemplate (object)

Request

JavaScriptCurlPython

const response = await fetch('https://api.abyssale.com/banner-builder/{templateId}/generate', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "id": "64238d01-d402-474b-8c2d-fbc957e9d290",
  "image": {
    "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"
  },
  "format": {
    "id": "facebook-post",
    "width": 1200,
    "height": 1200
  },
  "template": {
    "id": "64238d01-d402-474b-8c2d-fbc957e9d290",
    "name": "Ad campaign fall 2022",
    "created_at": 1649942114,
    "updated_at": 1649942114
  }
}

The full api reference can be found here.

Properties available for each type of component are available here.

If no parameter is sent, the generated image will correspond to the first format of the template with the default properties.

What type of image file is returned?

Only 2 image filetypes are supported (jpeg & png).

By default, Abyssale automatically determine the filetype from the format background color:

• If the background color contains transparency (alpha < 100), the generated image will be a PNG.

• Otherwise, the generated image will be a JPEG.

The default behavior can be overriden by using the image_file_type property (accepted values: png or jpeg).

Note that if you use jpeg for a template that contains transparency, it will be generated using a black opaque colour (as jpeg does not support transparency).

Get the default payload

To ease the creation of your payload, just go to one of your Template and choose Abyssale Rest API in the Generation Methods list. You will find the default associated payload in the console (Feel free to remove unnecessary properties/elements):

To copy the payload to your clipboard, click the Copy Code button.

Sample request

Do not forget to replace {YOUR-API-KEY} and {templateId}

cURL

curl -X POST -H "x-api-key:{YOUR-API-KEY}" -H "Content-Type: application/json"  \
-d '{
  "template_format_name": "main-crisp",
  "elements": {
    "image": {
      "image_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/9c872731-da6f-4923-b342-7c4250ac94cc/assets/370af020-5e56-445d-bdf7-02e819658a8a.jpeg",
      "fitting_type": "cover",
      "alignment": "middle center"
    },
    "text_title": {
      "payload": "Send best wishes to your lovelies with little easter gifts!",
      "color": "#FFFFFF",
      "font_size": 48,
      "font": "61566327-33c5-11ea-9877-92672c1b8195",
      "font_weight": 700,
      "line_height": 120,
      "alignment": "top left"
    }
  }
}' \
https://api.abyssale.com/banner-builder/{templateId}/generate

Javascript

const axios = require('axios');

const payload = {
  "template_format_name": "main-crisp",
  "elements": {
    "image": {
      "image_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/9c872731-da6f-4923-b342-7c4250ac94cc/assets/370af020-5e56-445d-bdf7-02e819658a8a.jpeg",
      "fitting_type": "cover",
      "alignment": "middle center"
    },
    "text_title": {
      "payload": "Send best wishes to your lovelies with little easter gifts!",
      "color": "#FFFFFF",
      "font_size": 48,
      "font": "61566327-33c5-11ea-9877-92672c1b8195",
      "font_weight": 700,
      "line_height": 120,
      "alignment": "top left"
    }
  }
}

axios.post("https://api.abyssale.com/banner-builder/{templateId}/generate", payload, {
    headers: {"x-api-key": "{YOUR-API-KEY}", "Content-Type": "application/json", "timeout": 30000}
  }).then(response => {
    console.log(response.data)
})

Python

import json
import requests

image_generation_payload = {
  "template_format_name": "main-crisp",
  "elements": {
    "image": {
      "image_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/9c872731-da6f-4923-b342-7c4250ac94cc/assets/370af020-5e56-445d-bdf7-02e819658a8a.jpeg",
      "fitting_type": "cover",
      "alignment": "middle center"
    },
    "text_title": {
      "payload": "Send best wishes to your lovelies with little easter gifts!",
      "color": "#FFFFFF",
      "font_size": 48,
      "font": "61566327-33c5-11ea-9877-92672c1b8195",
      "font_weight": 700,
      "line_height": 120,
      "alignment": "top left"
    }
  }
}

r = requests.post("https://api.abyssale.com/banner-builder/{templateId}/generate",
  headers={"x-api-key": "YOUR-API-KEY", "Content-Type": "application/json"},
  data=json.dumps(image_generation_payload),
  timeout=30
)
r.json()

Sample response

{
  "id": "5978e8d9-ab34-4735-a2cb-fe95c2c56251",
  "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 Feed",
    "width": 1200,
    "height": 628
  },
  "template": {
    "id": "46d22c62-d134-44d3-a040-138e4ea9ea08",
    "name": "Abyssale demo - FB Feed",
    "created_at": 1602256303,
    "updated_at": 1602685407
  }
}

What are the 2 image URLs?

As you can see in the sample response, 2 image urls are returned:

• A link (the url property) pointing directly to the Abyssale object storage service (S3).

  • Example: https://production-banners.s3.eu-west-1.amazonaws.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg

  • Hotlinking is allowed (a fair usage policy applies) but is not recommended as those URLs are not designed to have low latency and high transfer speeds features.

• A CDN link (the cdn_url property):

  • Example (not reachable): https://cdn.abyssale.com/demo/996739f4-b563-428a-a6e8-ec3cb8bd03d4.jpeg

  • Those URL are designed for high-speed & low-latency performance. A limited bandwidth applies to all plans (see the pricing table).

Errors

The Abyssale Image Generation API can return the following error codes :

Code	Description
400	Bad Request Your request is invalid. Either one of the parameter sent in the request is wrong or the generation failed due to one of the given property. A payload will be returned in the HTTP response explaining the error. For instance, here are payloads returned: If a given parameter is invalid (here the given color is invalid): {"message": "body_validation_errors: {'media': {'text_role': ["The following property is invalid: ({'color': ['Must be an hexadecimal color. i.e. #EAEAEA']})."]}}", "errors": {"media": {"text_role": ["The following property is invalid: ({'color': ['Must be an hexadecimal color. i.e. #EAEAEA']})."]}}} If a text cannot be inserted: {"id": "cannot_build_banner", "message": "Element text_name error: The text 'Welcome to the Abyssale Developer Hub' cannot fit within the defined space."}
401 403	Unauthorized Ensure your API key is the right one.
404	Not Found The route (or the given template) cannot be found.
405	Method Not Allowed You tried to access Abyssale with an invalid method.
429	API Limits reached All of your image generation API calls are consumed: You should upgrade to a higher plan.
500	Internal Server Error Try again later: Contact us on [e-mail] if the error occurs.