Background Burner API Reference
The Background Burner API allows for you to integrate Bonanza's Background Burner functionality into your own app or website. Try out the Background Burner for yourself.
In order to use the API, you must have Bonanza API credentials.
All Background Burner API requests return a JSON response.
The API provides four RESTful actions:
- Create : Queue a new background burn
- Show : Get the progress of a specific background burn
- Update : Select the "final mask" for a specific background burn
- Delete: Remove a specific background burn
- Index : List the 100 most recent burns for a specific user
Create
Queue a new background burn.
Request Parameters
Argument |
Type |
Occurrence |
Meaning |
url |
url |
Required |
Remote URL to the image that is to be burned |
key |
string |
Required |
Your Bonanza API developer id |
user_id |
string |
Recommended |
A user identifier you assign to the user. Generally, it's the unique ID assigned to the user by your application. We will optimize burn performance for repeat users who burn the same type of images. |
name |
string |
Optional |
Filename or the title of the picture. The more info about the picture, the better and faster we can burn it. |
description |
string |
Optional |
Any additional text that describes the picture. |
callback |
url |
Optional |
A URL we should POST to when the burn is complete, as well as when the final mask is selected or changed.
It must be a valid URL including the protocol ("http://" or "https://"). |
Show
Get the progress of a specific background burn.
Request Parameters
Argument |
Type |
Occurrence |
Meaning |
key |
string |
Required |
Your Bonanza API developer id |
user_id |
string |
Required |
The user identifier you assigned to the user when queueing the background burn. Generally, it's the unique ID assigned to the user by your application. We will optimize burn performance for repeat users who burn the same type of images. |
Update
Select the "final mask" for a specific background burn.
Request Parameters
Argument |
Type |
Occurrence |
Meaning |
key |
string |
Required |
Your Bonanza API developer id |
user_id |
string |
Required |
The user identifier you assigned to the user when queueing the background burn. Generally, it's the unique ID assigned to the user by your application. We will optimize burn performance for repeat users who burn the same type of images. |
selected_mask_id |
integer |
Required |
The ID of the Background Mask to apply as the "final mask" to this background burn |
Delete
Remove a specific background burn. Once removed, it will no longer show up in the index response.
Request Parameters
Argument |
Type |
Occurrence |
Meaning |
key |
string |
Required |
Your Bonanza API developer id |
user_id |
string |
Required |
The user identifier you assigned to the user when queueing the background burn. Generally, it's the unique ID assigned to the user by your application. We will optimize burn performance for repeat users who burn the same type of images. |
Index
List the 100 most recent burns for a specific user.
Request Parameters
Argument |
Type |
Occurrence |
Meaning |
key |
string |
Required |
Your Bonanza API developer id |
user_id |
string |
Required |
The user identifier you assigned to the user when queueing the background burn. Generally, it's the unique ID assigned to the user by your application. We will optimize burn performance for repeat users who burn the same type of images. |
Successful Responses
Successful requests return an HTTP status of 200.
Response values included in all requests
Return Value |
Type |
Occurrence |
Meaning |
action |
string |
Always |
The name of the action you sent the request to. |
message |
string |
Always |
Description of the result of the request - either a success or error message. |
user_id |
string |
Always |
The user identifier you assigned to the user when queueing the background burn. |
burn_user_id |
integer |
Always |
Bonanza's internal id for the Burn User. |
access_token |
string |
Always |
Unused |
Response values included in Create, Show, Update and Delete requests
Return Value |
Type |
Occurrence |
Meaning |
id |
integer |
Always |
The unique ID assigned to this background burn |
url |
string |
Always |
The remote image URL submitted to be burned |
position_in_queue |
integer |
Always |
The position in Background Burn queue. Will be 0 for completed burns. Time until burn starts is roughly 5 seconds multiplied by position in queue |
complete |
boolean |
Always |
True if the burn is complete, or false if it is waiting or in progress |
selected_mask_id |
integer |
Conditionally |
The id of the Background Mask selected by the user. Will be null if no mask has been selected |
final_result_url |
string |
Conditionally |
A URL to the image with the applied selected mask. Will be null if no mask has been selected |
source_image_url |
string |
Always |
A URL to the image that was uploaded (stored on Bonanza's servers) |
masks |
Container |
Conditionally |
An array of all possible Background Masks for this burn. Will be empty unless the burn is complete |
masks.id |
integer |
Always |
The unique ID assigned to this Background Mask |
masks.url |
string |
Always |
A URL to the generated Background Mask image |
masks.composite_url |
string |
Always |
A URL to the generated Background Mask image composited over the source image |
masks.variation |
string |
Always |
The name of the general method used to produce the Background Mask. |
masks.quality_score |
integer |
Always |
An integer describing our assessment of the mask quality, where higher score = likely better mask |
review_complete |
boolean |
Conditonally |
True when the burn has been reviewed by an expert. Only applies to expert-reviewed memberships |
Response values included in Index requests
Return Value |
Type |
Occurrence |
Meaning |
count |
integer |
Always |
The number of background burns returned for this user (max 100). |
background_burns |
Container |
Always |
An array of Background Burns |
background_burns.id |
integer |
Always |
The unique ID assigned to this background burn |
background_burns.url |
string |
Always |
The remote image URL submitted to be burned |
background_burns.position_in_queue |
integer |
Always |
The position in Background Burn queue. Will be 0 for completed burns. Time until burn starts is roughly 5 seconds multiplied by position in queue |
background_burns.complete |
boolean |
Always |
True if the burn is complete, or false if it is waiting or in progress |
background_burns.selected_mask_id |
integer |
Conditionally |
The id of the Background Mask selected by the user. Will be null if no mask has been selected |
background_burns.final_result_url |
string |
Conditionally |
A URL to the image with the applied selected mask. Will be null if no mask has been selected |
background_burns.source_image_url |
string |
Always |
A URL to the image that was uploaded (stored on Bonanza's servers) |
background_burns.masks |
Container |
Conditionally |
An array of all possible Background Masks for this burn. Will be empty unless the burn is complete |
background_burns.masks.id |
integer |
Always |
The unique ID assigned to this Background Mask |
background_burns.masks.url |
string |
Always |
A URL to the generated Background Mask image |
background_burns.masks.composite_url |
string |
Always |
A URL to the generated Background Mask image composited over the source image |
background_burns.masks.variation |
string |
Always |
The name of the general method used to produce the Background Mask. |
background_burns.masks.quality_score |
integer |
Always |
An integer describing our assessment of the mask quality, where higher score = likely better mask |
Error Responses
Error responses return an HTTP status of 200.
Return Value |
Type |
Occurrence |
Meaning |
type |
string |
Always |
The type of error that occurred. |
message |
string |
Always |
An explanation of the error. |