Introduction

Bannerbear is a service that turns graphic templates into a simple JSON-based API.

Your designer designs a template in Bannerbear
We turn it into an API
You use this API to generate variations of the template in PNG / JPG format

Authentication

To test your API key:

curl "https://api.bannerbear.com/v2/auth"
  -H "Authorization: Bearer API_KEY"

The above endpoint returns a JSON array like this:

{
    "message": "Authorized",
    "project": "My Project Name"
}

Bannerbear uses API keys to allow access to the API. You can get an API key by creating a project in Bannerbear.

Bannerbear expects the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer API_KEY

Replace API_KEY with your project API key

Account

To query your account status:

curl "https://api.bannerbear.com/v2/account"
  -H "Authorization: Bearer API_KEY"

Make sure to replace API_KEY with your API key.

{
    "created_at": "2019-10-22T09:49:45.265Z",
    "uid": "jJWBKNELpQPvbX5R93Gk",
    "paid_plan_name": "Bannerbear Marketer",
    "image_api_quota": 1000,
    "image_api_usage_this_month": 409,
    "video_api_quota": 3000,
    "video_api_usage_this_month": 1066,
    "current_project": {
        "name": "My Project Name"
    }
}

To check your account status at any time you can use this endpoint.

It will respond with your quota levels and current usage levels. Usage resets at the start of every month.

Note that video_api_quota and video_api_usage_this_month are in seconds.

Templates

Templates are the reusable designs that you create in the Bannerbear editor. You can list a project's templates via the API.

You can design a template using the Bannerbear template editor, or you can add one from the template library (and modify it as needed).

Every template has a list of modifications available, for example text boxes that you can populate with different text, or image placeholders that you can replace with different images.

List Templates

To list a project's templates:

curl "https://api.bannerbear.com/v2/templates"
  -H "Authorization: Bearer API_KEY"

HTTP Request

GET https://api.bannerbear.com/v2/templates

Get a Specific Template

To get a template:

curl "https://api.bannerbear.com/v2/templates/04PK8K2bctXHjqB97O"
  -H "Authorization: Bearer API_KEY"

The above endpoint returns JSON like this:

{
  "created_at": "2020-03-17T01:58:07.358Z",
  "name": "Twitter Demo",
  "self": "https://api.bannerbear.com/v2/templates/04PK8K2bctXHjqB97O",
  "uid": "04PK8K2bctXHjqB97O",
  "preview_url": null,
  "width": 1000,
  "height": 1000,
  "available_modifications": [
    {
      "name": "avatar",
      "image_url": null
    },
    {
      "name": "name",
      "text": null
    },
    {
      "name": "handle",
      "text": null
    },
    {
      "name": "body",
      "text": null
    }
  ]
}

HTTP Request

GET https://api.bannerbear.com/v2/templates/<uid>

Parameters

Parameter	Description
uid	The uid of the template to retrieve

Edit a Template

You can edit some basic attributes of a Template via the API.

HTTP Request

PATCH https://api.bannerbear.com/v2/templates/<uid>

Parameters

Parameter	Description
uid	The uid of the template to edit

PATCH Parameters

Send as a JSON object

Parameter	Type	Description
name	string	The template name
tags	array	An array of tags

Template Preview

Each time you edit a template in Bannerbear, a thumbnail is saved and made available in the preview_url property of the Template object.

Images

An Image is generated from a Template.

You generate images by sending a POST request to Bannerbear with a template uid and a list of template modifications you want to apply. These modifications can be things like: changing the text, changing the images or changing the colors.

Bannerbear will respond with JPG and PNG formats of the new Image you have requested.

List Images

You can get a list of the latest images in this project any time by issuing a GET request to the /images endpoint. This will respond with an array of Image objects.

To list newest images:

curl "https://api.bannerbear.com/v2/images"
  -H "Authorization: Bearer API_KEY"

Create an Image

To create an image:

curl "https://api.bannerbear.com/v2/images"
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json" 
  -d json

The above endpoint returns JSON like this:

{
  "created_at": "2020-02-20T07:59:23.077Z",
  "status": "pending",
  "self": "https://api.bannerbear.com/v2/images/kG39R5XbvPQpLENKBWJj",
  "uid": "kG39R5XbvPQpLENKBWJj",
  "image_url": null,
  "template": "6A37YJe5qNDmpvWKP0",
  "modifications": [
    {
      "name": "title",
      "text": "Lorem ipsum dolor sit amed",
      "color": null,
      "background": null
    },
    {
      "name": "avatar",
      "image_url": "https://www.bannerbear.com/assets/sample_avatar.jpg"
    }
  ],
  "webhook_url": null,
  "webhook_response_code": null,
  "transparent": false,
  "metadata": null
}

HTTP Request

POST https://api.bannerbear.com/v2/images

POST Parameters

Send as a JSON object

Parameter	Type	Description
template	string	The template uid you want to use
modifications	array	A list of Modifications you want to make
webhook_url optional	string	A url to POST the `Image` object to upon rendering completed
transparent optional	boolean	Render a PNG with a transparent background. Defaults to `false` (white backround).
metadata optional	string	Metadata that you need to store e.g. ID of a record in your DB

You can view a sample API payload for any template in the Bannerbear API Console.

Modifications Array

Example modifications:

{
  "modifications": [
    {
      "name": "title",
      "text": "Lorem ipsum dolor sit amed"
    },
    {
      "name": "avatar",
      "image_url": "https://www.bannerbear.com/assets/sample_avatar.jpg"
    }
  ]
}

Your Image API payload should contain a parameter named modifications which is an array of modifications you would like to apply to a template.

All properties are optional, for example if you do not specify a color, the object's default color will be used.

Property	Type	Description
name	string	The name of the item you want to change
text	string	Replacement text you want to use
color	string	Color hex of object e.g. "#FF0000"
background	string	Color hex of text background
font_family	string	Change the font if needed
image_url	string	Replacement image url you want to use (must be publicly viewable)
anchor_x	string	For image containers to change the anchor point (left, center, right)
anchor_y	string	For image containers to change the anchor point (top, center, bottom)
fill_type	string	For image containers to change the fill type (fill, fit)
chart_data	string	A comma-delimited list of numbers to send to a Bar Chart object
rating	integer	A number from 0 to 100 to send to a Star Rating object
target	string	A url or text to send to a QR Code object
hide	boolean	Set to `true` to hide an object

Image Response

All images are created with the status pending.

Images are usually rendered within a few seconds. When completed, the status changes to completed.

You can poll the GET endpoint for status updates. The self property of the response provides this endpoint.

When completed the image url is found in the image_url property of the Image object. It will be in PNG format.

You can also grab a JPG version of the image from image_url_jpg.

Webhooks

Instead of polling, we recommended you define a webhook in webhook_url which Bannerbear will POST the Image object to after image rendering is complete.

To secure your webhook endpoint, Bannerbear will POST with the following header:

Authorization: Bearer WEBHOOK_KEY

Bannerbear will replace WEBHOOK_KEY with your project's webhook key

You can find your project's webhook key in its settings page.

Hotlinking

You may hotlink to image_url or image_url_jpg in your application. The JPG file will download and display faster for your users.

Hotlinking is offered on a Fair Use basis. We allow for approx 20GB of bandwidth per month from each account. If you consistently go over this amount we will contact you — you may need to upgrade your account or self-host the media.

Get a Specific Image

To get an image:

curl "https://api.bannerbear.com/v2/images/kG39R5XbvPQpLENKBWJj"
  -H "Authorization: Bearer API_KEY"

The above endpoint returns JSON like this:

{
  "created_at": "2020-02-20T07:59:23.077Z",
  "status": "completed",
  "self": "https://api.bannerbear.com/v2/images/kG39R5XbvPQpLENKBWJj",
  "uid": "kG39R5XbvPQpLENKBWJj",
  "image_url": "https://cdn.bannerbear.com/...",
  "template": "6A37YJe5qNDmpvWKP0",
  "modifications": [
    {
      "name": "title",
      "text": "Lorem ipsum dolor sit amed",
      "color": null,
      "background": null
    },
    {
      "name": "avatar",
      "image_url": "https://www.bannerbear.com/assets/sample_avatar.jpg"
    }
  ],
  "webhook_url": null,
  "webhook_response_code": null,
  "transparent": false,
  "metadata": null
}

After creating an image request you will receive a uid. You can poll this endpoint to find out when the image has been rendered. When the status is completed the image url will be available in image_url.

HTTP Request

GET https://api.bannerbear.com/v2/images/<uid>

Parameters

Parameter	Description
uid	The uid of the image to retrieve

Create an Image via GET

Bannerbear also supports creating images via GET request.

In Bannerbear this is achieved using Signed URLs.

Signed URLs product page

Signed URLs documentation

Video Templates

Video Templates are a subset of Templates.

Every Video Template is attached to a Template.

Templates hold design / layout information - as would be required to render Images.

Video Templates simply hold some extra instructions, telling Bannerbear what kind of video to render. This can be seen in the render_type property.

To list a project's video templates:

curl "https://api.bannerbear.com/v2/video_templates"
  -H "Authorization: Bearer API_KEY"

HTTP Request

GET https://api.bannerbear.com/v2/video_templates

Get a Specific Video Template

To get a video template:

curl "https://api.bannerbear.com/v2/video_templates/GL4kqNvzJ09lYxgVdO"
  -H "Authorization: Bearer API_KEY"

The above endpoint returns JSON like this:

{
  "created_at": "2020-09-15T05:21:22.066Z",
  "self": "http://api.bannerbear.com/v2/video_templates/GL4kqNvzJ09lYxgVdO",
  "uid": "GL4kqNvzJ09lYxgVdO",
  "name": "Quote Example",
  "width": 1000,
  "height": 1000,
  "render_type": "transcribe",
  "available_modifications": [
    {
      "name": "avatar",
      "image_url": null
    },
    {
      "name": "name",
      "text": null,
      "color": null,
      "background": null
    },
    {
      "name": "subtitle",
      "text": null,
      "color": null,
      "background": null
    }
  ]
}

HTTP Request

GET https://api.bannerbear.com/v2/video_templates/<uid>

Parameters

Parameter	Description
uid	The uid of the video template to retrieve

Videos

A Video is generated from a Video Template.

You generate videos by sending a POST request to Bannerbear with a video template uid, a list of template modifications you want to apply, and a media file.

Bannerbear will respond with an MP4 format of the new Video you have requested.

You can get a list of the latest videos in this project any time by issuing a GET request to the /videos endpoint. This will respond with an array of Video objects.

You can optionally use a ?status= query string to filter the results.

Valid statuses are completed and pending_approval.

To list newest videos:

curl "https://api.bannerbear.com/v2/videos"
  -H "Authorization: Bearer API_KEY"

Create a Video

To create a video:

curl "https://api.bannerbear.com/v2/videos"
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json" 
  -d json

The above endpoint returns JSON like this:

{
  "input_media_url": "https://www.bannerbear.com/audio/test.m4a",
  "created_at": "2020-09-16T05:30:19.568Z",
  "length_in_seconds": 0,
  "approval_required": true,
  "approved": false,
  "status": "pending",
  "self": "https://api.bannerbear.com/v2/videos/kG39R5XbvPQpLENKBWJj",
  "uid": "kG39R5XbvPQpLENKBWJj",
  "render_type": "overlay",
  "percent_rendered": 0,
  "video_url": null,
  "modifications": [
    {
      "name": "avatar",
      "image_url": "https://cdn.bannerbear.com/sample_images/welcome_bear_photo.jpg"
    }
  ],
  "webhook_url": null,
  "webhook_response_code": null,
  "metadata": null,
  "transcription": null
}

HTTP Request

POST https://api.bannerbear.com/v2/videos

POST Parameters

Send as a JSON object

Parameter	Type	Description
video_template	string	The video template uid you want to use
input_media_url	string	Full url to a video or audio file you want to import as the background of the video
modifications optional	array	A list of Modifications you want to make
webhook_url optional	string	A url to POST the `Image` object to upon rendering completed
metadata optional	string	Metadata that you need to store e.g. ID of a record in your DB
trim_to_length_in_seconds optional	integer	Force a video to trim to a specific length

You can view a sample API payload for any template in the Bannerbear API Console.

The modifications array follows the same format as an Image modifications array.

View the Images section for more information on modifications.

Sometimes you may want to trim a video to a specific length, in which case you can use trim_to_length_in_seconds. Note that this will simply end the video / audio stream at the length you specify, which may produce undesirable results. Use this option carefully.

Video Response

All videos are created with the status pending.

Video rendering time depends on length / complexity of the video. It can vary from a few seconds to a few minutes. When completed, the status changes to completed.

You can poll the GET endpoint for status updates. The self property of the response provides this endpoint.

When completed the video url is found in the video_url property of the Video object. It will be in MP4 format.

Webhooks

Instead of polling, we recommended you define a webhook in webhook_url.

Bannerbear will POST the Video object to your webhook after video rendering is complete.

Bannerbear will also POST to this webhook for any videos that enter the pending_approval status so please check the status property in your application logic.

To secure your webhook endpoint, Bannerbear will POST with the following header:

Authorization: Bearer WEBHOOK_KEY

Bannerbear will replace WEBHOOK_KEY with your project's webhook key

You can find your project's webhook key in its settings page.

Hotlinking

You may hotlink to video_url in your application.

Get a Specific Video

To get an image:

curl "https://api.bannerbear.com/v2/videos/kG39R5XbvPQpLENKBWJj"
  -H "Authorization: Bearer API_KEY"

The above endpoint returns JSON like this:

{
  "input_media_url": "https://www.bannerbear.com/audio/test.m4a",
  "created_at": "2020-09-16T05:30:19.568Z",
  "length_in_seconds": 16,
  "approval_required": true,
  "approval_given": false,
  "status": "pending_approval",
  "self": "http://api.bblocaldev.com:5000/v2/videos/kG39R5XbvPQpLENKBWJj",
  "uid": "kG39R5XbvPQpLENKBWJj",
  "render_type": "overlay",
  "percent_rendered": 0,
  "video_url": null,
  "modifications": [
    {
      "name": "avatar",
      "image_url": "https://cdn.bannerbear.com/sample_images/welcome_bear_photo.jpg"
    }
  ],
  "webhook_url": null,
  "webhook_response_code": null,
  "metadata": null,
  "transcription": [
    "Okay, this is a voice memo that I'm just using",
    "as a test because I'm going to try to auto transcribe",
    "and create a video from this voice memo."
  ]
}

After creating an video request you will receive a uid. You can poll this endpoint to find out when the video has been rendered. When the status is completed the video url will be available in video_url.

HTTP Request

GET https://api.bannerbear.com/v2/videos/<uid>

Parameters

Parameter	Description
uid	The uid of the video to retrieve

Edit a Video

Video Templates have an approval_required boolean setting.

When approval_required is false rendering starts after the Create Video request.

When approval_required is true all video requests go through an approval workflow. When the video status is pending_approval the video will be held until a user takes further action, either via the Bannerbear dashboard or the API.

Edit and Approve actions are only relevant when approval_required is true.

Currently the main reason for setting approval_required to true is to check that the automatic audio transcription is accurate, and to make any adjustments required.

HTTP Request

PATCH https://api.bannerbear.com/v2/videos

PATCH Parameters

Send as a JSON object

Parameter	Type	Description
uid	string	The uid of the video to patch
transcription	array	An array of strings of your new transcription

Note that each element of the transcription array represents a specific timestamp. For that reason, the number of lines of your patched text must match the original. Bannerbear will not update the record if the number is different.

Editing transcriptions is meant for minor corrections, not making major changes.

Approve a Video

To approve a video and start the rendering process, set approved to true.

HTTP Request

PATCH https://api.bannerbear.com/v2/videos

PATCH Parameters

Send as a JSON object

Parameter	Type	Description
uid	string	The uid of the video to patch
approved	boolean	Set to `true` to begin rendering

Reject a Video

To reject a video and cancel the rendering process, set rejected to true.

HTTP Request

PATCH https://api.bannerbear.com/v2/videos

PATCH Parameters

Send as a JSON object

Parameter	Type	Description
uid	string	The uid of the video to patch
rejected	boolean	Set to `true` to delete video and cancel the rendering process

The rejected property takes precedent over all other Video properties, meaning that if you send a PATCH payload with both rejected and approved set to true, the video will be rejected.

Errors

The Bannerbear API uses the following error codes:

Error Code	Meaning
202	Accepted -- Your request is has been accepted for processing
200	OK
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
404	Not Found -- The specified request could not be found.
429	Too Many Requests -- Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

The Bannerbear API rate limit is 10 requests per 10 seconds.

Advanced

Animated Gifs

This endpoint creates an animated gif slideshow. The principle is similar to creating an Image request

Example:

When generating a static Image you send a single payload of modifications in a parameter called modifications.

When generating an Animated Gif you send an array of modifications payloads in a parameter called frames. Essentially you are instructing Bannerbear to generate multiple Images at once.

Bannerbear will generate the necessary images, stitch them together and respond with the gif of the new Animated Gif you have requested.

Create an Animated Gif

To create an animated gif:

curl "https://api.bannerbear.com/v2/animated_gifs"
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json" 
  -d json

The above endpoint returns JSON like this:

{
  "created_at": "2020-12-02T05:35:57.364Z",
  "uid": "a46YPx8Z65pwmKrdGE",
  "self": "https://api.bannerbear.com/v2/animated_gifs/a46YPx8Z65pwmKrdGE",
  "template": "1eGqK9b33PxbnaYpP8",
  "status": "pending",
  "frames": [
    [], //modifications
    [], //modifications
    []  //modifications
  ],
  "fps": 1,
  "frame_durations": null,
  "loop": true,
  "image_url": null,
  "webhook_url": null,
  "webhook_response_code": null,
  "metadata": null
}

HTTP Request

POST https://api.bannerbear.com/v2/animated_gifs

POST Parameters

Send as a JSON object

Parameter	Type	Description
template	string	The template uid you want to use
frames	array	An array of Modifications arrays
fps	float	Frame rate of gif (default is 1 frame per second)
frame_durations	array	Override the `fps` setting with an array of values to set a custom duration for each frame
loop	boolean	Loop the gif (defaults to true)
webhook_url optional	string	A url to POST the `Image` object to upon rendering completed
metadata optional	string	Metadata that you need to store e.g. ID of a record in your DB

Depending on your content an animated gif may take a few seconds or longer to generate.

To be notified when it is complete, you can use the webhook. Alternatively you can poll the self endpoint and check the status attribute.

Frames Array

Example frames:

{
  "frames": [
    [
      {
        "name": "title",
        "text": "This is the first title"
      },
      {
        "name": "photo",
        "text": "https://www.mydomain/image1.jpg"
      }
    ],
    [
      {
        "name": "title",
        "text": "This is the second title"
      },
      {
        "name": "photo",
        "text": "https://www.mydomain/image2.jpg"
      }
    ]
  ]
}

Your Animated Gif API payload should contain a parameter named frames which is an array of arrays - each child array representing an individual frame of the gif. Each frame array is a set of standard modifications.

Animated Gifs can have a maximum of 30 frames.

Template Sets

Templates Sets are sets of Templates that you group together in the Bannerbear dashboard. You can list a project's template sets via the API.

Every template set has a list of modifications available, for example text boxes that you can populate with different text, or image placeholders that you can replace with different images.

To create a collection of images, you send a payload of data to the /collections endpoint with the template set UID.

List Template Sets

To list a project's template sets:

curl "https://api.bannerbear.com/v2/template_sets"
  -H "Authorization: Bearer API_KEY"

HTTP Request

GET https://api.bannerbear.com/v2/template_sets

Get a Specific Template Set

To get a template:

curl "https://api.bannerbear.com/v2/template_sets/04PK8K2bctXHjqB97O"
  -H "Authorization: Bearer API_KEY"

The above endpoint returns JSON like this:

{
    "name": "My Template Set",
    "created_at": "2020-11-11T02:48:54.472Z",
    "self": "http://api.bannerbear.com/v2/template_sets/VymBYa7gMjW6JQ2njM",
    "uid": "VymBYa7gMjW6JQ2njM",
    "available_modifications": [
        {
            "name": "tweet",
            "text": null,
            "color": null,
            "background": null
        },
        {
            "name": "avatar",
            "image_url": null
        },
        {
            "name": "name",
            "text": null,
            "color": null,
            "background": null
        }
    ]
}

HTTP Request

GET https://api.bannerbear.com/v2/template_sets/<uid>

Parameters

Parameter	Description
uid	The uid of the template set to retrieve

Collections

Sometimes you want to use the same data payload but push to multiple templates at once. In Bannerbear, you can do this by grouping templates together in a Template Set. Pushing data to a Template Set results in a response that includes multiple images (depending on how many templates were in your set).

This multi-image object is known as a Collection.

List Collections

You can get a list of the latest collection in this project any time by issuing a GET request to the /collections endpoint. This will respond with an array of Collection objects.

To list newest images:

curl "https://api.bannerbear.com/v2/collections"
  -H "Authorization: Bearer API_KEY"

Create a Collection

To create a collection:

curl "https://api.bannerbear.com/v2/collections"
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json" 
  -d json

The above endpoint returns JSON like this:

{
  "created_at": "2020-07-31 04:28:32 UTC",
  "uid": "rZdpMYmAnDB1zb3kXL",
  "self": "https://api.bannerbear.com/v2/collections/rZdpMYmAnDB1zb3kXL",
  "template_set": "Dbl5xYVgKRzLwaNdqo",
  "status": "completed",
  "modifications": [
    {
      "name": "text_container",
      "text": "Hello World"
    }
  ],
  "webhook_url": null,
  "webhook_response_code": null,
  "metadata": null,
  "image_urls": {
    "template_EagXkA3DwM1ZW2VBYw_image_url": "https://cdn.bannerbear.com/...",
    "template_197xPQmDnLqZG3E82Y_image_url": "https://cdn.bannerbear.com/..."
  },
  "images": [
    //array of Image objects
  ]
}

HTTP Request

POST https://api.bannerbear.com/v2/collections

Post Parameters

Send as a JSON object

Parameter	Type	Description
template_set	string	The template set uid you want to use
modifications	array	A list of Modifications you want to make
webhook_url optional	string	A url to POST the `Collection` object to upon rendering completed
metadata optional	string	Metadata that you need to store e.g. ID of a record in your DB

For more information on the modifications parameter, see the Images endpoint.

Status

All collections are created with the status pending.

Collections are usually rendered within a few seconds. When completed, the status changes to completed.

You can poll the GET endpoint for status updates. The self property of the response provides this endpoint. Alternatively you can provide a webhook to get notified when generation is completed.

Get a Specific Collection

To get a collection:

curl "https://api.bannerbear.com/v2/collections/rZdpMYmAnDB1zb3kXL"
  -H "Authorization: Bearer API_KEY"

The above endpoint returns JSON like this:

{
  "created_at": "2020-07-31 04:28:32 UTC",
  "uid": "rZdpMYmAnDB1zb3kXL",
  "self": "https://api.bannerbear.com/v2/collections/rZdpMYmAnDB1zb3kXL",
  "template_set": "Dbl5xYVgKRzLwaNdqo",
  "status": "completed",
  "modifications": [
    {
      "name": "text_container",
      "text": "Hello World"
    }
  ],
  "webhook_url": null,
  "webhook_response_code": null,
  "metadata": null,
  "image_urls": {
    "template_EagXkA3DwM1ZW2VBYw_image_url": "https://cdn.bannerbear.com/...",
    "template_197xPQmDnLqZG3E82Y_image_url": "https://cdn.bannerbear.com/..."
  },
  "images": [
    //array of Image objects
  ]
}

HTTP Request

GET https://api.bannerbear.com/v2/collections/<uid>

Parameters

Parameter	Description
uid	The uid of the collection to retrieve

Screenshots

The Bannerbear API includes a screenshot tool if you need to capture screenshots of public webpages. It is not as fully-featured as standalone screenshot tools and is mostly intended for simple screenshot jobs.

Each screenshot counts as 1 image against your quota.

Create a Screenshot

To create a screenshot:

curl "https://api.bannerbear.com/v2/screenshots"
  -H "Authorization: Bearer API_KEY"
  -H "Content-Type: application/json" 
  -d json

The above endpoint returns JSON like this:

{
  "url": "https://www.apple.com",
  "width": 1200,
  "height": 3000,
  "created_at": "2021-01-05T06:54:52.912Z",
  "mobile": false,
  "self": "https://api.bannerbear.com/v2/screenshots/xwbeAQqO70Y3oyd2WY",
  "uid": "xwbeAQqO70Y3oyd2WY",
  "screenshot_image_url": null,
  "webhook_url": null,
  "webhook_response_code": null,
  "status": "pending"
}

HTTP Request

POST https://api.bannerbear.com/v2/screenshots

Post Parameters

Send as a JSON object

Parameter	Type	Description
url	string	A publicly-viewable url you want to screenshot
width optional	integer	Screenshot browser width, defaults to 1200 if not set
height optional	integer	Screenshot browser height, defaults to full page if not set
mobile optional	boolean	Use mobile user agent, default is false
webhook_url optional	string	A url to POST the `Screenshot` object to upon rendering completed

Status

All screenshots are created with the status pending.

End to end, a screenshot usually takes a couple of seconds.

You can poll the GET endpoint for status updates. The self property of the response provides this endpoint.

Webhooks

Instead of polling, we recommended you define a webhook in webhook_url which Bannerbear will POST the Screenshot object to after rendering is complete. The rendered image url is found in the screenshot_image_url property of the Screenshot object.

Get a Specific Screenshot

To get a screenshot:

curl "https://api.bannerbear.com/v2/screenshots/W7ErAeVjZAb6G1MpNQ"
  -H "Authorization: Bearer API_KEY"

The above endpoint returns JSON like this:

{
  "url": "https://www.apple.com",
  "width": 1200,
  "height": 3000,
  "created_at": "2021-01-05T06:54:52.912Z",
  "mobile": false,
  "self": "https://api.bannerbear.com/v2/screenshots/xwbeAQqO70Y3oyd2WY",
  "uid": "xwbeAQqO70Y3oyd2WY",
  "screenshot_image_url": "https://cdn.bannerbear.com/...",
  "webhook_url": null,
  "webhook_response_code": null,
  "status": "completed"
}

HTTP Request

GET https://api.bannerbear.com/v2/screenshots/<uid>

Parameters

Parameter	Description
uid	The uid of the screenshot to retrieve

Fonts

Fonts are set at the template level in Bannerbear. When you design a template and create a text box, you choose a font for that text box. So it is not necessary to set fonts when creating images via the API, as the defaults will be used.

However, if you wish you can change fonts in your images on-the-fly when creating an image by adding a font_family attribute and the name of a valid font.

If you use an invalid font name when creating an image, the template default font will be used.

Default Fonts

Default Sans Serif Fonts

font_family	Type
Alegreya Sans	Sans Serif
Anton	Sans Serif
Archivo	Sans Serif
Archivo Narrow	Sans Serif
Cabin	Sans Serif
Catamaran	Sans Serif
Chivo	Sans Serif
Fira Sans	Sans Serif
IBM Plex Sans	Sans Serif
Karla	Sans Serif
Lato	Sans Serif
Libre Franklin	Sans Serif
Montserrat	Sans Serif
Muli	Sans Serif
Noto Sans	Sans Serif
Nunito	Sans Serif
Open Sans	Sans Serif
Oswald	Sans Serif
Oxygen	Sans Serif
PT Sans	Sans Serif
Pontano Sans	Sans Serif
Poppins	Sans Serif
Puritan	Sans Serif
Raleway	Sans Serif
Roboto	Sans Serif
Source Sans Pro	Sans Serif
Space Mono	Sans Serif
Titillium Web	Sans Serif
Ubuntu	Sans Serif
Varela	Sans Serif
Work Sans	Sans Serif

Default Serif Fonts

font_family	Type
Abril Fatface	Serif
Alegreya	Serif
Arvo	Serif
BioRhyme	Serif
Corben	Serif
Cormorant	Serif
Courier Prime	Serif
Coustard	Serif
DM Serif Display	Serif
Eczar	Serif
Frank Ruhl Libre	Serif
Gravitas One	Serif
IBM Plex Serif	Serif
Jomolhari	Serif
Libre Baskerville	Serif
Lora	Serif
Merriweather	Serif
Neuton	Serif
Noto Serif	Serif
Old Standard TT	Serif
PT Serif	Serif
Playfair Display	Serif
Prata	Serif
Source Serif Pro	Serif
Spectral	Serif
Vollkorn	Serif

Example text box modification:

{
  "name": "title",
  "text": "Lorem ipsum dolor sit amed",
  "font_family": "Noto Serif"
}

Custom Fonts

Custom fonts are managed in the fonts management page.

List All Fonts

You can get a list of valid font names by issuing a GET request to the /fonts endpoint. This list will include all default Bannerbear fonts plus any custom fonts you have uploaded.

You can also refer to the fonts management page in your Bannerbear account for the correct font names to use for your custom fonts - click the API button.

To list all available fonts:

curl "https://api.bannerbear.com/v2/fonts"
  -H "Authorization: Bearer API_KEY"

Airtable

Airtable Import

To start an import:

curl -X POST "https://api.bannerbear.com/v2/templates/04PK8K2bctXHjqB97O/airtable"
  -H "Authorization: Bearer API_KEY"

The above endpoint returns JSON like this:

{
    "message": "Airtable import has started"
}

HTTP Request

POST https://api.bannerbear.com/v2/templates/<uid>/airtable

Parameters

Parameter	Description
uid	The uid of the template to initiate Airtable Import on

If you have an airtable connected to a template you can initiate an airtable import by issuing a POST request to this endpoint.

This endpoint responds with simple success or failure message. Images are not returned by this endpoint.

To see new Images as they are imported from Airtable you can watch the List Images endpoint which lists all new images.

Introduction

Authentication

Account

Templates

List Templates

HTTP Request

Get a Specific Template

HTTP Request

Parameters

Edit a Template

HTTP Request

Parameters

PATCH Parameters

Template Preview

Images

List Images

Create an Image

HTTP Request

POST Parameters

Modifications Array

Image Response

Webhooks

Hotlinking

Get a Specific Image

HTTP Request

Parameters

Create an Image via GET

Video Templates

List Video Templates

HTTP Request

Get a Specific Video Template

HTTP Request

Parameters

Videos

List Videos

Create a Video

HTTP Request

POST Parameters

Video Response

Webhooks

Hotlinking

Get a Specific Video

HTTP Request

Parameters

Edit a Video

HTTP Request

PATCH Parameters

Approve a Video

HTTP Request

PATCH Parameters

Reject a Video

HTTP Request

PATCH Parameters

Errors

Advanced

Animated Gifs

Create an Animated Gif

HTTP Request

POST Parameters

Frames Array

Template Sets

List Template Sets

HTTP Request

Get a Specific Template Set

HTTP Request

Parameters

Collections

List Collections

Create a Collection

HTTP Request

Post Parameters

Status

Get a Specific Collection

HTTP Request

Parameters

Screenshots

Create a Screenshot

HTTP Request

Post Parameters

Status