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.

Submit to URL: https://api.bonanza.com/api/background_burns
Method: POST

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.

Submit to URL: https://api.bonanza.com/api/background_burns/:id
Method: GET
:id The unique ID of the Background Burn which you want to view

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.

Submit to URL: https://api.bonanza.com/api/background_burns/:id
Method: PUT
:id The unique ID of the Background Burn which you want to view

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.

Submit to URL: https://api.bonanza.com/api/background_burns/:id
Method: DELETE
:id The unique ID of the Background Burn you want to remove

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.

Submit to URL: https://api.bonanza.com/api/background_burns
Method: GET

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.