Synchronous generation

Endpoint

POST /banner-builder/{design_id}/generate

Key Characteristics

• Immediate asset creation

• Single asset generation

• Supports on static design

• Instant response with asset URL

Generation Process

1. Send design ID and customization parameters

2. Receive immediate response

3. Asset generated and URL provided

Diagram

API Documentation

Generate image

post

Authorizations

Path parameters

templateIdstring · uuidRequired

Unique identifier (UUID) of the template

Body

template_format_namestringOptional

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

Example: facebook-post

file_compression_levelinteger · min: 1 · max: 100Optional

Percentage of compression applied.

Example: 80

Responses

200

Ok

application/json

post

HTTPcURLJavaScriptPython

POST /banner-builder/{templateId}/generate HTTP/1.1
Host: api.abyssale.com
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 138

{
  "elements": {
    "ANY_ADDITIONAL_PROPERTY": {
      "background_color": "#FF0000"
    }
  },
  "template_format_name": "facebook-post",
  "file_compression_level": 80
}

200

Ok

{
  "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 2022",
    "type": "static",
    "created_at": 1649942114,
    "updated_at": 1649942114,
    "category_name": "Fall campaigns"
  }
}

You can find all layers properties in this section

Sample request

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

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://mycompany.com/image.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/{designId}/generate

Javascript

const axios = require('axios');

const payload = {
  "template_format_name": "main-crisp",
  "elements": {
    "image": {
      "image_url": "https://mycompany.com/image.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/{designId}/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://mycompany.com/image.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/{designId}/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).

Progress your design generation journey by diving deeper into configuration

• Generate single image