Home | Bannertize Documentation

Introduction

Bannertize is images generation service which generates images based on Designed/CSS Coded Templates via API, Forms, No-Code, Airtable & Simple URL. This is a documentation to Generate Image(s) via API.

Select, Design or Code the Template.
Bannertize turns this into an API.
You can use this API to generate Images.

API Base URL

https://api.bannertize.com

Authentication

Bannertize uses API keys to allow access to the API. An API key is auto-generated on account creation.

You are required to provide API key with all API requests as Bearer Token:

Authorization: Bearer API_KEY

API Key can be found at profile page.

User Endpoint

GET /v1/user

Sample Response

{
    name: 'Geet Purwar',
    email: '[email protected]',
    paid_plan: 'Plus'
}

Accounts

Check your account status any time at this endpoint.

It will respond with your plan credits counts and current usage.

Account Endpoint

GET /v1/account

Sample Response

{
    created_at: "2019-10-22T09:49:45.265Z",
    uid: "c02412c5-61dd-44b1-9f87-742580d01fb7",
    plan_name: "Plus",
    credits_assigned: 1000,
    credits_usage_this_month: 409
}

Images

Bannertize provides following `images` endpoints to
Generate & Retrieve Image.

Endpoint

POST /v1/image
GET /v1/image/:uid

Generating Image

You can Generate Image by sending POST request to the endpoint along with Template specific modifications.

Bannertize will respond with `Result Url` which has all details such as status (pending/completed) & WebP version of image along with PNG/JPG/PDF (if requested).

Endpoint

POST /v1/image

Request Response

Sample Request Object

var request = {
    template: "34dd6b07-3ff3-4045-b892-fcb9bbb3b1f6",
    modifications:[
    {
        layer: "color",
        background: "slate-700",
        highlight: "rose-500"
    },
    {
        layer: "text",
        color: "gray-900",
        content: "Lorem ipsum dolor sit amet"
    }
    ],
    webhook_url: null,
    render_pdf: false,
    render_png: false,
    render_jpg: false,
    render_retina_image: false,
    render_transparent_image: false
}


// Sending Request to /v1/images endpoint
fetch('https://api.bannertize.com/v1/image', {
	method: 'POST',
	body: JSON.stringify(request),
	headers: {
		'Content-Type' : 'application/json',
		'Authorization' : `Bearer ${API_TOKEN}`
	}
})

Sample Response

{
	uuid: "d631f96f-381c-474c-a6bf-f23e6ebcae9d",
	created_at: "2023-01-31T04:18:34.000000Z",
	status: "pending",
	result_url: "https://api.bannertize.com/v1/image/d631f96f-381c-474c-a6bf-f23e6ebcae9d",
	template: "34dd6b07-3ff3-4045-b892-fcb9bbb3b1f6",
	template_name: "Christmas",
	width: 1277,
	height: 719,
	image_url: null,
	image_url_webp: null,
	image_url_png: null,
	image_url_jpg: null,
	pdf_url: null,
	webhook_url: null,
	credits_used: 1
}

Retrieve an image

Retrieves a single Image object referenced by its unique ID.

You can Retrieve Image by sending GET request to the endpoint along with Image Uid.

Bannertize will respond with Response showing status (pending/completed), Credits details & WebP version of image along with PNG/JPG/PDF (if requested).

Endpoint

GET /v1/image/:uid

Request Response

Sample Request Object

fetch(`https://api.bannertize.com/v1/image/${UID}`, {
    method: 'GET'
})

Sample Response

{
    "uuid": "d631f96f-381c-474c-a6bf-f23e6ebcae9d",
    "status": "completed",
    "created_at": "2023-01-31T04:18:44.000000Z",
    "card_uid": "34dd6b07-3ff3-4045-b892-fcb9bbb3b1f6",
    "card_name": "Christmas",
    "width": "1277",
    "height": "719",
    "modifications": [
      {
        "layer": "color",
        "blob_top": "rose-600",
        "backblob_1": "sky-500",
        "bottomline_1": "rose-500",
        "bottomline_2": "#4D220D"
      },
      {
        "blob": "On Sale",
        "layer": "text",
        "bottomline_1": "Promo code : NYRSL21",
        "bottomline_2": "Promo code : NYRSL21"
      },
      {
        "main": "https://images.unsplash.com/photo-1599253366255-57649c2cd60e?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1028&q=100",
        "layer": "image"
      }
    ],
    "webhook": {
      "url": null,
      "response_status_code": null,
      "response_status_text": null
    },
    "used_credits": 1,
    "image_url": "https://cloud.bannertize.com/1/1675138724370.webp",
    "image_url_png": null,
    "render_jpg": false,
    "image_url_jpg": null,
    "render_webp": false,
    "image_url_webp": "https://cloud.bannertize.com/1/1675138724370.webp",
    "render_pdf": false,
    "image_url_pdf": null,
    "render_retina_image": false,
    "render_transparent_image": false
  }

Generating Images (via Set)

You can Generate Multiple Images by sending POST request to the endpoint along with `Set` specific modifications.

Bannertize will respond with `Set Result Url` which has all details such as status (pending/completed) & WebP version of image along with PNG/JPG/PDF (if requested).

Endpoint

POST /v1/set

Request Response

Sample Request Object

var request = {
    "set": "b6c5b47d-e629-4f61-9f83-46ae8674dbb5",
    "modifications": [
      {
        "layer": "color",
        "background": "slate-700",
        "highlight": "rose-500",
        "text": "emerald-900"
      },
      {
        "layer": "text",
        "color": "gray-900",
        "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam feugiat eros at diam tempor vitae accumsan neque ullamcorper. Praesent hendrerit sollicitudin tellus quis malesuada.",
        "button": "Order Now",
        "headline": "New Collection",
        "headline2": "50% OFF",
        "para1": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam feugiat eros at diam tempor vitae accumsan neque ullamcorper",
        "para2": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam feugiat eros at diam tempor vitae accumsan neque ullamcorper",
        "website": "www.brandname.com"
      },
      {
        "layer": "image",
        "person": "https://images.unsplash.com/photo-1617127365659-c47fa864d8bc?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=987&q=80",
        "logo": "https://cloud.bannertize.com/medias/tcJCORoK6xo9OToRIhkpNPaXv9vR4PUryRPSFHdc.svg",
        "main": "https://images.unsplash.com/photo-1619020985209-852c1de42d42?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1480&q=80"
      },
      {
        "layer": "theme",
        "main": "emerald"
      }
    ],
    "webhook_url": null,
    "render_jpg": false,
    "render_png": false,
    "render_pdf": false,
    "render_retina_image": false,
    "render_transparent_image": false,
    "render_best_quality": false
  }  


// Sending Request to /v1/images endpoint
fetch('https://api.bannertize.com/v1/set', {
	method: 'POST',
	body: JSON.stringify(request),
	headers: {
		'Content-Type' : 'application/json',
		'Authorization' : `Bearer ${API_TOKEN}`
	}
})

Sample Response

{
	"uid": "f8361cf0-e834-4475-a0ed-59cf49f509c1",
	"set": {
		"name": "Social Media",
		"uid": "b6c5b47d-e629-4f61-9f83-46ae8674dbb5"
	},
	"options": {
		"webhook_url": null,
		"render_jpg": false,
		"render_png": false,
		"render_pdf": false,
		"render_retina_image": false,
		"render_transparent_image": false,
		"render_best_quality": false
	},
	"used_credits": 2,
	"status": "pending",
	"result_url": "https://api.bannertize.com/v1/set/f8361cf0-e834-4475-a0ed-59cf49f509c1",
	"created_at": "2023-01-31T04:45:19.000000Z"
}

Retrieve Template

Retrieves a single Template object referenced by its unique ID.

You can Retrieve Image by sending GET request to the endpoint along with Template Uid.

Bannertize will respond with Response object showing status, dimensions, preview-url, available-modifications along with other fields.

Endpoint

GET /v1/template/:uid

Request Response

Sample Request Object

fetch(`https://api.bannertize.com/v1/template/${UID}`, {
    method: 'GET',
    headers: {
        'Authorization' : `Bearer ${API_KEY}`
    }
})

Sample Response

{
	"uid": "c43e1fda-8bf8-4e43-b89d-0e9ecd413362",
	"name": "Christmas Invitation",
	"modifications": [
		{
			"layer": "text",
			"line_1": "Christmas Party",
			"line_2": "December 24",
			"line_3": "8:00 PM",
			"line_4": "Free Drinks",
			"line_5": "Come Celebrate & Let\"s have fun together.",
			"line_6": "christmasparty.com"
		}
	],
	"dimensions": {
		"width": "613",
		"height": "859"
	},
	"preview_url": "https://cloud.bannertize.com/1/[email protected]",
	"created_at": "2022-12-06T05:58:28.000000Z"
}

Retrieve Set-Instance

Retrieves a single Set-Instance object referenced by its unique ID.

You can retrieve Set-Instance by sending GET request to the endpoint along with Set-Instance Uid.

Bannertize will respond with Response object showing status (pending/completed), Credits details & array of Image Objects with respective WebP version along with PNG/JPG/PDF (if requested).

Endpoint

GET /v1/set/:uid

Request Response

Sample Request Object

fetch(`https://api.bannertize.com/v1/set/${UID}`, {
    method: 'GET'
})

Sample Response

{
    "uid": "f8361cf0-e834-4475-a0ed-59cf49f509c1",
    "set": {
        "name": "Social Media",
        "uid": "b6c5b47d-e629-4f61-9f83-46ae8674dbb5"
    },
    "options": {
        "render_jpg": false,
        "render_pdf": false,
        "render_png": false,
        "webhook_url": null,
        "render_best_quality": false,
        "render_retina_image": false,
        "render_transparent_image": false
    },
    "modifications": [
    {
        "text": "emerald-900",
        "layer": "color",
        "highlight": "rose-500",
        "background": "slate-700"
    },
    {
        "color": "gray-900",
        "layer": "text",
        "para1": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam feugiat eros at diam tempor vitae accumsan neque ullamcorper",
        "para2": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam feugiat eros at diam tempor vitae accumsan neque ullamcorper",
        "button": "Order Now",
        "content": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam feugiat eros at diam tempor vitae accumsan neque ullamcorper. Praesent hendrerit sollicitudin tellus quis malesuada.",
        "website": "www.brandname.com",
        "headline": "New Collection",
        "headline2": "50% OFF"
    },
    {
        "logo": "https://cloud.bannertize.com/medias/tcJCORoK6xo9OToRIhkpNPaXv9vR4PUryRPSFHdc.svg",
        "main": "https://images.unsplash.com/photo-1619020985209-852c1de42d42?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1480&q=80",
        "layer": "image",
        "person": "https://images.unsplash.com/photo-1617127365659-c47fa864d8bc?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=987&q=80"
    },
    {
        "main": "emerald",
        "layer": "theme"
    }
    ],
    "used_credits": 2,
    "set_instance_status": "completed",
    "set_instance_completed_at": "2023-01-31 04:45:26",
    "images": [
    {
        "uuid": "0cc753c2-92d6-49db-b28f-45023100bc31",
        "status": "completed",
        "created_at": "2023-01-31T04:45:20.000000Z",
        "template_name": "Handwriting Text",
        "webhook": {
            "url": null,
            "response_status_code": null,
            "response_status_text": null
        },
        "used_quota": null,
        "width": "1080",
        "height": "1080",
        "image_url": null,
        "image_url_webp": null,
        "image_url_jpg": null,
        "image_url_png": null,
        "render_pdf": false,
        "image_url_pdf": null
    },
    {
        "uuid": "6046053a-8520-4337-aa76-0020bfcaaac2",
        "status": "completed",
        "created_at": "2023-01-31T04:45:26.000000Z",
        "template_name": "Email : New Collection",
        "webhook": {
            "url": null,
            "response_status_code": null,
            "response_status_text": null
        },
        "used_quota": null,
        "width": "640",
        "height": "auto",
        "image_url": "https://cloud.bannertize.com/1/1675140326364.webp",
        "image_url_webp": "https://cloud.bannertize.com/1/1675140326364.webp",
        "image_url_jpg": null,
        "image_url_png": null,
        "render_pdf": false,
        "image_url_pdf": null
    }
    ]
}