GBGenerateBanners.com

Fast & secure API

Integrate once, generate many images.

This documents details how the GenerateBanners API works. If you're using JavaScript, you might be interest in our JavaScript SDK .

Authentication

You can get your API key and secret on your Account page.

There are two methods to authenticate requests to the GenerateBanners.com API

Authorization header
HMAC-signed URL

Authorization header

In this authentication method, the secret is added in the Authorization header. You should only use this method for server-side calls, so that you keep your api secret key to yourself.

HMAC-signed URL

This authentication method hides the secret key by creating a signature. It uses HMAC-256. The use-case for this authentication method is to sign the render urls GET /template/:slug/render so that they can be embeded directly in the frontend/email without disclosing the API secret.

Api base path

The base path for the api is https://api.generatebanners.com/api/v1/API_KEY/

Rate limits

All endpoints are rate-limited to 10 requests per second per IP.

On top of the previous rate-limit, the render endpoint GET /template/:slug/render is rate-limited to 100 requests per 15 minutes per API key.

When reaching the limit, the API will return a 429 HTTP error code until the end of the rate-limit interval.

Get all templates `GET /template`

Lists the metadata of all available templates.

Code examples

async getAllTemplates() => {
    const res = await fetch(
        'https://api.generatebanners.com/api/v1/YOUR_API_KEY_HERE/template',
        {
            headers: {
                Authorization: 'Bearer YOUR_API_SECRET_HERE',
            },
        }
    );
    const json = await res.json();
    return json;
}

curl -H "Accept: application/json" \
    -H "Authorization: Bearer YOUR_API_SECRET_HERE" \
    https://api.generatebanners.com/api/v1/YOUR_API_KEY_HERE/template

Get one template `GET /template/:id`

Returns the metadata of one template.

Code examples

async getTemplate() => {
    const res = await fetch(
        'https://api.generatebanners.com/api/v1/YOUR_API_KEY_HERE/template/YOUR_TEMPLATE_ID_HERE',
        {
            headers: {
                Authorization: 'Bearer YOUR_API_SECRET_HERE',
            },
        }
    );
    const json = await res.json();
    return json;
}

curl -H "Accept: application/json" \
    -H "Authorization: Bearer YOUR_API_SECRET_HERE" \
    https://api.generatebanners.com/api/v1/YOUR_API_KEY_HERE/template/YOUR_TEMPLATE_ID_HERE

Get one template signed url `GET /template/:slug/sign-url`

Returns a signed url to a template rendering, based on the content from the query string. This is a great endpoint to return a safe signed-url without having to deal with HMAC signing.

Code examples

async getSignedUrl() => {
    const res = await fetch(
        'https://api.generatebanners.com/api/v1/YOUR_API_KEY_HERE/template/YOUR_TEMPLATE_ID_HERE/sign-url?filetype=jpeg&layer1_text=hello%20world',
        {
            headers: {
                Authorization: 'Bearer YOUR_API_SECRET_HERE',
            },
        }
    );
    const json = await res.json();
    return json;
}

curl -H "Accept: application/json" \
    -H "Authorization: Bearer YOUR_API_SECRET_HERE" \
    'https://api.generatebanners.com/api/v1/YOUR_API_KEY_HERE/template/YOUR_TEMPLATE_ID_HERE/sign-url?filetype=jpeg&layer1_text=hello%20world'

Render one template `GET /template/:slug/render`

Renders a template based on the content from the query string. All API requests to this endpoint must be signed via HMAC.

Code examples

const { createHmac } = require("crypto");
const fs = require("fs").promises;
const got = require("got");

const DOMAIN = "https://api.generatebanners.com";
const API_KEY = process.env.API_KEY;
const API_SECRET = process.env.API_SECRET;
if (!API_KEY) {
    return console.log("This script needs a GenerateBanners.com API key");
}
if (!API_SECRET) {
    return console.log("This script needs a GenerateBanners.com API secret");
}

async function getImage(template, variables, outputFile) {
    const query = Object.keys(variables)
        .map(
            (key) =>
                encodeURIComponent(key) +
                "=" +
                encodeURIComponent(variables[key])
        )
        .join("&");

    const url =
        "/api/v1/" + API_KEY + "/template/" + template + "/render?" + query;

    // Sign url
    const hmac = createHmac("sha256", API_SECRET).update(url).digest("hex");
    const target = DOMAIN + url + `&hmac=${hmac}`;

    // Get image
    const image = await got(target).buffer();

    // Save it locally
    await fs.writeFile(outputFile, image);
    console.log("Wrote", outputFile);
}

const template = "YOUR_TEMPLATE_ID_HERE";
const variables = {
    title_text: "Have fun creating banners!",
    subtitle_text: "GenerateBanners.com",
};
const outputFile = "./output.jpg";

getImage(template, variables, outputFile).catch(console.log);

GenerateBanners.com