Integrate once, generate many images.
To get the best experience on this documentation please log-in!
This will fill the documentation with your own API key and secret and add buttons to test the API endpoints.
There are two methods to authenticate requests to the GenerateBanners.com API
In this authentication method, the secret is added in the Authorization
header. You should only use this method for server calls, so that you keep your api secret key to yourself.
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.
The base path for the api is https://api.generatebanners.com/api/v1/API_KEY/
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.
GET /template
Lists the metadata of all available templates.
async fetchAllTemplates() => {
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 /template/:id
Returns the metadata of one template.
async fetchAllTemplates() => {
const res = await fetch(
'https://api.generatebanners.com/api/v1/YOUR_API_KEY_HERE/template/dev-blog-highlight',
{
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/dev-blog-highlight
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.
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 = "dev-blog-highlight";
const variables = {
title: "Have fun creating banners!",
domain: "GenerateBanners.com",
};
const outputFile = "./output.jpg";
getImage(template, variables, outputFile).catch(console.log);