Bannerbear API Reference
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 Images and Videos
https://api.bannerbear.com
Authentication
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
You can find the API key in your Project → Settings page.
All API requests on Bannerbear are scoped to a Project.
get | /v2/auth |
{
"message": "Authorized",
"project": "My Project Name"
}
Account
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.
Video usage is measured in seconds.
get | /v2/account |
{
"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"
}
}
Errors
The Bannerbear API uses the following status / error codes. The Bannerbear API rate limit is 10 requests per 10 seconds.
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. |
Webhooks
All core resources feature a webhook system so you can be notified when the resource has been generated.
To secure your webhook endpoint, Bannerbear will POST with the following header:
Authorization: Bearer WEBHOOK_KEY
You can find the webhook key in your Project → Settings page.
Async / Sync
The Bannerbear API is primarily asynchronous. When generating a new image, collection etc you POST a request, the API responds immediately with 202 Accepted and you either receive the generated result via webhook or via polling.
This is the preferred pattern as it keeps the request / response cycle predictable.
However, there is a synchronous option if you would simply like to wait for the response in the initial request.
To make a synchronous request use the synchronous base URL. The API required attributes / parameters function the same as normal. Synchronous requests will wait until the media file has finished generating before responding.
There is a timeout of 10 seconds on synchronous requests. Timeouts respond with a 408 status code.
Another option for synchronous image generation is using the signed URLs feature.
https://sync.api.bannerbear.com
POST | /v2/images |
POST | /v2/collections |
POST | /v2/screenshots |
Images
Images are the main resource on Bannerbear.
You generate images by sending a POST request 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.
post | /v2/images |
get | /v2/images/:uid |
get | /v2/images |
The image object
Attributes
- uid stringThe unique ID for this object.
- status stringThe current status of the image; pending, completed or failed.
- self stringThe permalink to this object.
- template stringThe unique ID of the template used as the base of the image.
- image_url stringThe final, rendered image url. This will be null to begin with and populates when the image has the status completed
- modifications listA list of template modifications made on this object.
- webhook_url stringCustom webhook url called when the object status is completed.
- webhook_response_code integerThe HTTP response code received by the webhook_url.
- transparent booleanIs true if the rendered image has a transparent background.
- metadata stringCustom metadata field to store arbitrary data.
{
"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
}
Create an image
Creating an image on Bannerbear is achieved via this endpoint.
This endpoint responds with 202 Accepted after which your image will be queued to generate. Images are usually rendered within a few seconds. When completed, the status changes to completed.
You can poll the GET endpoint for status updates or use a webhook to get the final image posted to you.
Parameters
- template stringrequiredThe template uid that you want to use.
- modifications listrequiredA list of modifications you want to make.
- Child Parameters
- name stringThe name of the layer you want to change.
- text stringReplacement text you want to use.
- color stringColor hex of layer e.g. "#FF0000".
- background stringColor hex of text background.
- font_family stringChange the font if needed.
- image_url stringFor image containers: change the image.
- effect stringFor image containers: change the effect.
- anchor_x stringFor image containers: change the anchor point (left, center, right).
- anchor_y stringFor image containers: change the anchor point (top, center, bottom).
- fill_type stringFor image containers: change the fill type (fill, fit).
- chart_data stringFor chart containers: a comma-delimited list of numbers to use as data.
- rating integerFor star rating containers: a number from 0 to 100 to use as the rating.
- target stringFor QR Code containers: url or text to use as the code target.
- shift_x integerShift layer along the x axis.
- shift_y integerShift layer along the y axis.
- hide booleanSet to true to hide a layer
- webhook_url stringA url to POST the full Image object to upon rendering completed.
- transparent booleanRender a PNG with a transparent background. Default is false.
- metadata stringAny metadata that you need to store e.g. ID of a record in your DB.
post | /v2/images |
var data = {
"template" : "jJWBKNELpQPvbX5R93Gk",
"modifications" : [
{
"name" : "layer1",
"text" : "This is my text"
},
{
"name" : "photo",
"image_url" : "https://www.pathtomyphoto.com/1.jpg"
}
]
}
fetch('https://api.bannerbear.com/v2/images', {
method: 'POST',
body: JSON.stringify(data),
headers: {
'Content-Type' : 'application/json',
'Authorization' : `Bearer ${API_KEY}`
}
})
Retrieve an image
Retrieves a single Image object referenced by its unique ID.
Parameters
- uid stringrequiredThe image uid that you want to retrieve.
get | /v2/images/:uid |
fetch(`https://api.bannerbear.com/v2/images/${UID}`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
List all images
Lists images inside a project.
Parameters
- page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
get | /v2/images |
fetch('https://api.bannerbear.com/v2/images', {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
Videos
Videos are generated from a Video Template.
You generate videos by sending a POST request 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.
post | /v2/videos |
get | /v2/videos/:uid |
patch | /v2/videos |
get | /v2/videos |
The video object
Attributes
- uid stringThe unique ID for this object.
- status stringThe current status of the video; pending, pending_approval, rendering, completed or failed.
- self stringThe permalink to this object.
- video_template stringThe unique ID of the video template used as the base of the video.
- input_media_url stringThe media (movie or audio) that was provided to as the base of the video.
- video_url stringThe final, rendered video url. This will be null to begin with and populates when the video has the status completed
- length_in_seconds integerThe measured length in seconds of the input_media_url. Bannerbear will validate the length before rendering videos to prevent going over quota.
- approval_required booleanWhether this video requires approval before rendering proceeds. This setting can be changed in the Build Pack settings for a video template.
- approved booleanApproval status of the video.
- render_type stringThe name of the Build Pack.
- percent_rendered integerThe progress of the video render from 0 to 100.
- transcription listThe transcription for the video line by line. This is populated automatically if you are using Bannerbear's auto-transcription feature.
- frames listApplies only to videos using the Multi Overlay build pack. A list of modifications lists, each one representing a single graphic overlay on the video.
- frame_durations listApplies only to videos using the Multi Overlay build pack. Custom durations for each frame. When not specified, frames will be spread evenly across the video.
- modifications listA list of template modifications made on this object.
- webhook_url stringCustom webhook url called when the object status is completed.
- webhook_response_code integerThe HTTP response code received by the webhook_url.
- metadata stringCustom metadata field to store arbitrary data.
{
"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"
}
],
"frames": null,
"frame_durations": null,
"webhook_url": null,
"webhook_response_code": null,
"metadata": null,
"transcription": null
}
Create a video
Creating a video on Bannerbear is achieved via this endpoint.
This endpoint responds with 202 Accepted after which your video will be queued to generate. 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 or use a webhook to get the final video posted to you.
Parameters
- video_template stringrequiredThe video template uid that you want to use.
- input_media_url stringrequiredFull url to a video or audio file you want to import as the background of the video.
- modifications listA list of modifications you want to make. See Create an image for more details on the child parameters. Unlike an Image the modifications list is not always required for a Video.
- blur integerApply a blur filter (max: 100) to the incoming video.
- trim_to_length_in_seconds integerForce trim the end video to a specific time.
- webhook_url stringA url to POST the full Video object to upon rendering completed.
- metadata stringAny metadata that you need to store e.g. ID of a record in your DB.
- frames listApplies only to videos using the Multi Overlay build pack. A list of modifications lists, each one representing a single graphic overlay on the video.
- frame_durations listApplies only to videos using the Multi Overlay build pack. Custom durations for each frame. When not specified, frames will be spread evenly across the video.
post | /v2/videos |
//add a simple text overlay to a video
var data = {
"video_template" : "9JWBASDKLpQPvbX5R93Gk",
"input_media_url": "https://www.bannerbear.com/my/video.mp4",
"modifications" : [
{
"name" : "layer1",
"text" : "This is my text"
}
]
}
fetch('https://api.bannerbear.com/v2/videos', {
method: 'POST',
body: JSON.stringify(data),
headers: {
'Content-Type' : 'application/json',
'Authorization' : `Bearer ${API_KEY}`
}
})
Retrieve a video
Parameters
- uid stringrequiredThe video uid that you want to retrieve.
get | /v2/videos/:uid |
fetch(`https://api.bannerbear.com/v2/videos/${UID}`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
Update a video
Parameters
- uid stringrequiredThe video uid that you want to update.
- transcription listA replacement transcription containing your corrected / edited text. 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.
- approved booleanSet to true to approve the video and start the rendering process.
patch | /v2/videos |
//update a transcription and begin rendering
var data = {
"uid": "ASDKLpQPvbX",
"transcription" : [
"This is a replacement for line 1",
"and this is a replacement for line 2"
],
"approved" : true
}
fetch(`https://api.bannerbear.com/v2/videos`, {
method: 'PATCH',
body: JSON.stringify(data),
headers: {
'Content-Type' : 'application/json',
'Authorization' : `Bearer ${API_KEY}`
}
})
List all videos
Parameters
- page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
get | /v2/videos |
fetch('https://api.bannerbear.com/v2/videos', {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
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.
The collection object
Attributes
- uid stringThe unique ID for this object.
- status stringThe current status of the collection; pending, completed or failed.
- self stringThe permalink to this object.
- template_set stringThe unique ID of the template set to be used.
- image_urls objectAn object of final, rendered image urls. This will be null to begin with and populates when the collection has the status completed
- images listAn array of the full Image objects in this collection.
- modifications listA list of template modifications made on this object.
- webhook_url stringCustom webhook url called when the object status is completed.
- webhook_response_code integerThe HTTP response code received by the webhook_url.
- transparent booleanIs true if the rendered images have a transparent background.
- metadata stringCustom metadata field to store arbitrary data.
{
"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,
"transparent": false,
"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
]
}
Create a collection
Creating a collection on Bannerbear is achieved via this endpoint and behaves the same as creating a single Image except with a different response.
This endpoint responds with 202 Accepted after which your collection will be queued to generate. Collections are usually rendered within a few seconds. When completed, the status changes to completed.
You can poll the GET endpoint for status updates or use a webhook to get the final video posted to you.
Parameters
- template_set stringrequiredThe template set uid that you want to use.
- modifications listrequiredA list of modifications you want to make. See Create an image for more details on the child parameters.
- webhook_url stringA url to POST the full Collection object to upon rendering completed.
- metadata stringAny metadata that you need to store e.g. ID of a record in your DB.
- transparent booleanRender the collection with a transparent background. Default is false.
post | /v2/collections |
var data = {
"template_set" : "LXk3bz1BDnAmYMpdZr",
"modifications" : [
{
"name" : "layer1",
"text" : "This is my text"
},
{
"name" : "photo",
"image_url" : "https://www.pathtomyphoto.com/1.jpg"
}
]
}
fetch('https://api.bannerbear.com/v2/collections', {
method: 'POST',
body: JSON.stringify(data),
headers: {
'Content-Type' : 'application/json',
'Authorization' : `Bearer ${API_KEY}`
}
})
Retrieve a collection
Parameters
- uid stringrequiredThe collection uid that you want to retrieve.
get | /v2/collections/:uid |
fetch(`https://api.bannerbear.com/v2/collections/${UID}`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
List all collections
Parameters
- page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
get | /v2/collections |
fetch('https://api.bannerbear.com/v2/collections', {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
Animated Gifs
Animated Gifs on Bannerbear take the form of simple slideshows. You can add multiple frames, control the duration of individual frames, control the number of loops and more.
The animated gif object
Attributes
- uid stringThe unique ID for this object.
- self stringThe permalink to this object.
- template stringThe unique ID of the template used as the base of the image.
- image_url stringThe final, rendered image url. This will be null to begin with and populates when the image has the status completed
- frames listA list of modifications lists, each one representing a single frame of the gif.
- input_media_url stringAn optional movie file that can be used as part of the gif.
- fps integerFrame rate of gif (default is 1 frame per second).
- frame_durations listCustom durations for each frame (overrides fps).
- loop booleanIndicates whether the gif is looped.
- webhook_url stringCustom webhook url called when the object status is completed.
- webhook_response_code integerThe HTTP response code received by the webhook_url.
- metadata stringCustom metadata field to store arbitrary data.
{
"created_at": "2020-12-02T05:35:57.364Z",
"uid": "a46YPx8Z65pwmKrdGE",
"self": "https://api.bannerbear.com/v2/animated_gifs/a46YPx8Z65pwmKrdGE",
"template": "1eGqK9b33PxbnaYpP8",
"status": "pending",
"input_media_url": null,
"frames": [
[], //list of modifications
[], //list of modifications
[] //list of modifications
],
"fps": 1,
"frame_durations": null,
"loop": true,
"image_url": null,
"webhook_url": null,
"webhook_response_code": null,
"metadata": null
}
Create an animated gif
This endpoint responds with 202 Accepted after which your animated gif will be queued to generate. Animated gifs are usually rendered within a few seconds. When completed, the status changes to completed.
You can poll the GET endpoint for status updates or use a webhook to get the final animated gif posted to you.
Parameters
- template stringrequiredThe template uid that you want to use.
- frames listrequiredA list of modifications lists to apply in sequence. See Create an image for more details on the child parameters. Animated Gifs can have a maximum of 30 frames.
- input_media_url stringAn optional movie file that can be used as part of the gif. Depending on the number of frames you pass in, Bannerbear will generate thumbnails of this movie and place them sequentially into an image container in your template named video_frame.
post | /v2/animated_gifs |
var data = {
"template" : "1eGqK9b33PxbnaYpP8",
"frames" : [
[ //frame 1 starts here
{
"name" : "layer1",
"text" : "This is my text"
},
{
"name" : "photo",
"image_url" : "https://www.pathtomyphoto.com/1.jpg"
}
],
[ //frame 2 starts here
{
"name" : "layer1",
"text" : "This is my follow up text"
},
{
"name" : "photo",
"image_url" : "https://www.pathtomyphoto.com/2.jpg"
}
]
]
}
fetch('https://api.bannerbear.com/v2/animated_gifs', {
method: 'POST',
body: JSON.stringify(data),
headers: {
'Content-Type' : 'application/json',
'Authorization' : `Bearer ${API_KEY}`
}
})
Retrieve an animated gif
Parameters
- uid stringrequiredThe animated gif uid that you want to retrieve.
get | /v2/animated_gifs/:uid |
fetch(`https://api.bannerbear.com/v2/animated_gifs/${UID}`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
List all animated gifs
Parameters
- page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
get | /v2/animated_gifs |
fetch('https://api.bannerbear.com/v2/animated_gifs', {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
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.
The screenshot object
Attributes
- uid stringThe unique ID for this object.
- status stringThe current status of the image; pending, completed or failed.
- self stringThe permalink to this object.
- url stringThe website that was screenshotted.
- screenshot_image_url stringThe final, rendered image url. This will be null to begin with and populates when the image has the status completed
- mobile booleanUse mobile headers when performing the screenshot.
- webhook_url stringCustom webhook url called when the object status is completed.
- webhook_response_code integerThe HTTP response code received by the webhook_url.
{
"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"
}
Create a screenshot
This endpoint responds with 202 Accepted after which your screenshot will be queued to generate. Screenshots are usually rendered within a few seconds. When completed, the status changes to completed.
You can poll the GET endpoint for status updates or use a webhook to get the final screenshot posted to you.
Parameters
- url stringrequiredThe website you want to screenshot.
- width integerScreenshot browser width, defaults to 1200 if not set.
- height integerScreenshot browser height, defaults to full page if not set.
- mobile booleanUse mobile user agent. Default is false.
- webhook_url stringA url to POST the full Screenshot object to upon rendering completed.
post | /v2/screenshots |
var data = {
"url" : "https://www.apple.com"
}
fetch('https://api.bannerbear.com/v2/screenshots', {
method: 'POST',
body: JSON.stringify(data),
headers: {
'Content-Type' : 'application/json',
'Authorization' : `Bearer ${API_KEY}`
}
})
Retrieve a screenshot
Parameters
- uid stringrequiredThe screenshot uid that you want to retrieve.
get | /v2/screenshots/:uid |
fetch(`https://api.bannerbear.com/v2/screenshots/${UID}`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
List all screenshots
Parameters
- page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
get | /v2/screenshots |
fetch('https://api.bannerbear.com/v2/screenshots', {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
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.
The template object
Attributes
- uid stringThe unique ID for this object.
- name stringThe name of this template.
- self stringThe permalink to this object.
- preview_url stringA thumbnail of the latest version of the template.
- available_modifications listA list of available modifications.
- tags listAn array of tags for this template.
{
"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
}
],
"tags": [
"shoes",
"instagram"
]
}
Retrieve a template
Parameters
- uid stringrequiredThe template uid that you want to retrieve.
get | /v2/templates/:uid |
fetch(`https://api.bannerbear.com/v2/templates/${UID}`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
Update a template
You can edit some basic attributes of a Template via the API.
Parameters
- name stringThe name of the template.
- tags listAn array of tags for this template.
patch | /v2/templates/:uid |
var data = {
"tags" : [
"Tag1",
"Tag2"
],
"name" : "My template"
}
fetch(`https://api.bannerbear.com/v2/templates/${UID}`, {
method: 'PATCH',
body: JSON.stringify(data),
headers: {
'Content-Type' : 'application/json',
'Authorization' : `Bearer ${API_KEY}`
}
})
List all templates
Parameters
- page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
- tag stringquery stringList items only with this tag.
get | /v2/templates |
fetch('https://api.bannerbear.com/v2/templates', {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
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.
The template set object
Attributes
- uid stringThe unique ID for this object.
- name stringThe name of this template set.
- self stringThe permalink to this object.
- available_modifications listA list of available modifications.
{
"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
}
]
}
Retrieve a template set
Parameters
- uid stringrequiredThe template set uid that you want to retrieve.
get | /v2/template_sets/:uid |
fetch(`https://api.bannerbear.com/v2/template_sets/${UID}`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
List all template sets
Parameters
- page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
get | /v2/template_sets |
fetch('https://api.bannerbear.com/v2/template_sets', {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
Video Templates
Video Templates are a subset of Templates.
Templates for Images 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 attribute.
The video template object
Attributes
- uid stringThe unique ID for this object.
- name stringThe name of this video template.
- self stringThe permalink to this object.
- render_type stringThe name of the Build Pack.
- approval_required booleanWhether videos under this template require approval before rendering proceeds. This setting can be changed in the video template Build Pack settings.
- preview_url stringA thumbnail of the latest version of the template.
- available_modifications listA list of available modifications.
{
"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,
"approval_required": true,
"preview_url": null,
"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
}
]
}
Retrieve a video template
Parameters
- uid stringrequiredThe video template uid that you want to retrieve.
get | /v2/video_templates/:uid |
fetch(`https://api.bannerbear.com/v2/video_templates/${UID}`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
List all video templates
Parameters
- page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
get | /v2/video_templates |
fetch('https://api.bannerbear.com/v2/video_templates', {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})
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 parameter 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.
This endpoint simply returns a list of valid fonts.
get | /v2/fonts |
{
"Serif": [
"Abril Fatface",
"Alegreya",
"Arvo",
"BioRhyme",
"Corben",
"Cormorant",
"Courier Prime",
"Coustard",
"DM Serif Display",
"Eczar",
"Frank Ruhl Libre",
"Gravitas One",
"IBM Plex Serif",
"Jomolhari",
"Libre Baskerville",
"Lora",
"Merriweather",
"Neuton",
"Noto Serif",
"Old Standard TT",
"PT Serif",
"Playfair Display",
"Prata",
"Source Serif Pro",
"Spectral",
"Vollkorn"
],
"Sans Serif": [
"Alegreya Sans",
"Anton",
"Archivo",
"Archivo Narrow",
"Cabin",
"Catamaran",
"Chivo",
"Fira Sans",
"IBM Plex Sans",
"Karla",
"Lato",
"Libre Franklin",
"Montserrat",
"Muli",
"Noto Sans",
"Nunito",
"Open Sans",
"Oswald",
"Oxygen",
"PT Sans",
"Pontano Sans",
"Poppins",
"Puritan",
"Raleway",
"Roboto",
"Source Sans Pro",
"Space Mono",
"Titillium Web",
"Ubuntu",
"Varela",
"Work Sans"
],
"Novelty": [
"Caveat",
"Courgette",
"Delius",
"Kalam",
"Merienda",
"Patrick Hand",
"Permanent Marker",
"Press Start 2P",
"Satisfy",
"VT323"
],
"International": [
"Noto Sans SC",
"Noto Sans TC",
"Noto Sans JP",
"Noto Sans KR"
],
"Custom": [
"bb_custom_font_2cd55546-ec00-4af9-aeca-4a3cd186da53_otf"
]
}
Effects
Bannerbear has a number of built-in effects that you can apply to image containers at the template level.
However, you can also set these on-the-fly when you make Image API requests using the effect property.
This is useful if you need to make multiple variations from a template, but use different effects in each one.
This endpoint simply returns a list of valid effects.
get | /v2/effects |
[
"Smart Crop",
"Grayscale",
"Sepia",
"Gaussian Blur",
"Grayscale + Gaussian Blur",
"Flip Horizontal",
"Flip Vertical",
"Negate",
"Gameboy",
"16bit"
]
Diagnoses
Sometimes an image you generate on Bannerbear may not turn out as expected.
The most common problem is with imported images, which is the current focus for this diagnostic tool.
An imported image may be missing at the origin, or blocking Bannerbear access etc. This is usually due to permissions, file formats etc, but it can be tedious to track down the root cause.
This endpoint helps you isolate the problem, given an Image ID.
When you create a Diagnosis, Bannerbear will run through a series of checks on the data in the Image you have requested the diagnosis for. You will then receive a report with issues and suggested fixes.
Author's note: The subtle difference between the singular Diagnosis and plural Diagnoses is easy to miss. Ensure you use the right spelling when using this endpoint.
The diagnosis object
Attributes
- uid stringThe unique ID for this object.
- type stringThe parent object type
- parent_uid stringThe parent object unique ID
- status stringThe current status of the diagnosis; pending or completed.
- report objectA categorized report of issues with your Image. For now the only category is external_images which lists your image_urls and displays any issues Bannebear had with accessing them.
{
"uid": "KqePQDVvDXZwgNz2oJ",
"type": "Image",
"parent_uid": "kG39R5XbvPQpLENKBWJj",
"self": "https://api.bannerbear.com/v2/diagnoses/KqePQDVvDXZwgNz2oJ",
"status": "completed",
"report": {
"external_images": [
{
"image_url": "https://externalhost.com/assets/sample_avatar.jpg",
"result": "success",
"comment": null,
},
{
"image_url": "https://externalhost.io/assets/ads123da.jpg",
"result": "fail",
"comment": "404 Not Found",
}
]
}
}
Create a diagnosis
This endpoint responds with 202 Accepted after which your report will be queued to generate.
When completed, the status changes to completed.
Use the GET endpoint to retrieve the final report.
Parameters
- image_uid stringrequiredThe Image uid that you would like to run a diagnostic on. Currently this endpoint only supports Image uids.
post | /v2/diagnoses |
//create a report for Image UID kG39R5XbvPQpLENKBWJj
var data = {
"image_uid" : "kG39R5XbvPQpLENKBWJj"
}
fetch('https://api.bannerbear.com/v2/diagnoses', {
method: 'POST',
body: JSON.stringify(data),
headers: {
'Content-Type' : 'application/json',
'Authorization' : `Bearer ${API_KEY}`
}
})
Retrieve a diagnosis
Parameters
- uid stringrequiredThe diagnosis uid that you want to retrieve.
get | /v2/diagnoses/:uid |
fetch(`https://api.bannerbear.com/v2/diagnoses/${UID}`, {
method: 'GET',
headers: {
'Authorization' : `Bearer ${API_KEY}`
}
})