BoxBrownie.com API v2.0 Docs

Overview

Photo Editing jobs allow you to submit images and have various different types of editing applied to them.

Create a Photo Editing Job

POST /api/v2/job/createPhotoEditing

Endpoint: https://www.boxbrownie.com/api/v2/job/createPhotoEditing
HTTP Method: POST
Requires Authentication? Yes
Required Parameters: xml
Optional Parameters: (string) responseFormat [json|xml]

To create a Photo Editing job, we require you to send us an XML payload that contains a job title and one or more <fileGroup> blocks that describe the file URL of the image to be edited, and any desired editing options.

Your job XML should start with a job title.

<jobTitle>	String	Required	Max 1 Occurence	The title for the job. 100 characters max

Then, for each primary image that you want to include for editing, your XML should include an occurence of <fileGroup>. A file group will contain all the information for the edit that is being performed. Your XML may contain any number of <fileGroup> elements.

<fileGroup>		Required	Multiple Allowed	Represents one output. Contains XML for any images (primary and reference images) and any edit options for the output
<fileGroupComment>	String	Optional	Max 1 Occurence	An optional comment containing any special instructions for the file group

Within the <fileGroup> element, you will need to specify the file URL of the image that is going to be edited. You can specify more than one file URL if desired. The first file URL in each <files> block is treated as the primary image (the one that will be edited). Any subsequent <fileURL> elements will be treated as reference images for the edit. You may include any number of <fileURL> elements, just keep in mind that only the first in each file group will be edited.

<files>		Required	Max 1 Occurence	Contains one or more `<fileURL>` elements for the file group
<fileURL>	String	Required	Multiple Allowed	A file URL. The first occurence of `<fileURL>` in each `<files>` block is treated as the primary image for the file group (the one that will be edited). Subsequent `<fileURL>` elements are treated as reference images only and will not be edited

Within the <fileGroup> element, you may optionally provide a <sampleImages> block that contains one or more <sampleImageId> elements. This can be used to attach pre-uploaded sample images from your BoxBrownie.com account as additional reference images in the job. For more information, see the Sample Images documentation.

<sampleImages>		Optional	Max 1 Occurence	Contains one or more `<sampleImageId>` elements for the file group
<sampleImageId>	String	Required	Multiple Allowed	The unique ID of a sample image from your BoxBrownie.com account.

Within the <fileGroup> element, you will need to specify a <photoEditingTypes> block that contains at least one <photoEditingType> block. Each <photoEditingType> block must contain an <editName> element and may contain an <options> block defining the photo editing options that are to be applied.

Note: Not all <editName> values require an <options> block. Some edit types do not have any accepted options. In these cases, simply providing the <editName> element is adequate.

<photoEditingTypes>		Required	Max 1 Occurence	Contains one or more `<photoEditingType>` elements for the file group
<photoEditingType>		Required	Multiple Allowed	Contains exactly one `<editName>` and one `<options>` block
<editName>	String	Required	Max 1 Occurrence	The key of an Editing Type

Photo Editing Options are provided in an <options> block, with each option being defined as an <option> element containing both an <optionName> and an <optionValue>. Below, you can see an interactive list of accepted <optionName> and <optionValue> values.

Note: Acceptable <optionName> and <optionValue> values will vary depending on which <editName> is provided. Please see the section below for more information on which values are valid.

<options>		Required	Max 1 Occurence	Contains one or more `<option>` elements for the edit
<option>		Required	Multiple Allowed	Contains exactly one `<optionName>` and one `<optionValue>`
<optionName>	String	Required	Max 1 Occurrence	The key of a Photo Editing Option
<optionValue>	String	Required	Max 1 Occurrence	The key of a Photo Editing Option Value

Example XML

Below, you can see an example XML payload. This example defines 1 <fileGroup> element with two different edits applied. If this were a real job, you could expect to receive 1 completed output file when completed

<job>
    <jobTitle>My Photo Editing</jobTitle>
    <fileGroup>
        <files>
            <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured02.png</fileURL>
            <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured06.png</fileURL>
        </files>
        <sampleImages>
            <sampleImageId>99ccd87633acb90545c7ebcf4f57511df8d50a33</sampleImageId>
            <sampleImageId>d9c2ca823cf01a54df60f190da405151eab3c700</sampleImageId>
        </sampleImages>
        <photoEditingTypes>
            <photoEditingType>
                <editName>IMAGE_ENHANCEMENT_REAL_ESTATE</editName>
                <options>
                    <option>
                        <optionName>GRASS_REPAIR</optionName>
                        <optionValue>OPTION_YES</optionValue>
                    </option>
                    <option>
                        <optionName>SKY_REPLACEMENT</optionName>
                        <optionValue>OPTION_YES</optionValue>
                    </option>
                    <option>
                        <optionName>DAY_SKY_STYLE</optionName>
                        <optionValue>STYLE_ANY</optionValue>
                    </option>
                </options>
            </photoEditingType>
            <photoEditingType>
                <editName>ITEM_REMOVAL_TIER_1</editName>
            </photoEditingType>
        </photoEditingTypes>
        <fileGroupComment>Here is a comment on this file group</fileGroupComment>
    </fileGroup>
</job>

Example Response

Below, you can see an example response for the above example API Request.

{
  "success": "1",
  "job": {
    "jobId": "130fe17ee35d8e0444d18aeed9265555ede53050",
    "jobTitle": "My Photo Editing",
    "jobReference": "J888492240117",
    "jobStatus": "Pending",
    "jobDateSubmitted": "2024-03-19 15:11:34",
    "jobCost": "7.00",
    "jobCostCurrency": "AUD"
  }
}

<?xml version="1.0"?>
<response>
    <success>1</success>
    <job>
        <jobId>130fe17ee35d8e0444d18aeed9265555ede53050</jobId>
        <jobTitle>My Photo Editing</jobTitle>
        <jobReference>J888492240117</jobReference>
        <jobStatus>Pending</jobStatus>
        <jobDateSubmitted>2024-03-19 15:11:34</jobDateSubmitted>
        <jobCost>7.00</jobCost>
        <jobCostCurrency>AUD</jobCostCurrency>
    </job>
</response>

Simulate a Photo Editing Job

POST /api/v2/job/simulatePhotoEditing

Endpoint: https://www.boxbrownie.com/api/v2/job/simulatePhotoEditing
HTTP Method: POST
Requires Authentication? Yes
Required Parameters: xml
Optional Parameters: (string) responseFormat [json|xml]

The BoxBrownie.com API allows you to simulate the creation of a Photo Editing job in order to check for any errors in the XML payload of a job submission by using this endpoint. Additionally, this endpoint will return the expected job credit cost for the XML payload.

This endpoint accepts the same XML that you would use with the Create a Photo Editing Job endpoint.

Note: Using this endpoint will not create any jobs in your account, and will not charge your BoxBrownie.com account.

Note: Estimated credit cost does not take into account any free trials associated with your BoxBrownie.com account.

Example Response

Below, you can see an example response when supplying job XML to this endpoint.

{
  "success": "1",
  "jobCost": "7.00",
  "jobCostCurrency": "AUD",
  "xmlIsValid": "1"
}

<?xml version="1.0"?>
<response>
    <success>1</success>
    <jobCost>7.00</jobCost>
    <jobCostCurrency>AUD</jobCostCurrency>
    <xmlIsValid>1</xmlIsValid>
</response>

Retrieve a Photo Editing Job

GET /api/v2/job/{jobReference}

Endpoint: https://www.boxbrownie.com/api/v2/job/{jobReference}
HTTP Method: GET
Requires Authentication? Yes
Required Parameters: jobReference
Optional Parameters: (string) responseFormat [json|xml]

You may retrieve details about any job in your BoxBrownie.com account by supplying the reference number of the job jobReference.

Example Response

{
  "job": {
    "jobId": "130fe17ee35d8e0444d18aeed9265555ede53050",
    "jobTitle": "My Photo Editing",
    "jobReference": "J888492240117",
    "jobStatus": "Complete",
    "jobDateSubmitted": "2024-03-19 15:11:34",
    "jobCost": "7.00",
    "jobCostCurrency": "AUD",
    "jobDateCompleted": "2024-03-20 12:30:24",
    "output": {
      "file": [
        {
          "fileId": "75eebcbab044b3fe3358392b56d92b8c6fd6d208",
          "fileURL": "https://boxbrownie.b-cdn.net/completed/75eebcbab044b3fe3358392b56d92b8c6fd6d208.jpg"
        }
      ]
    }
  }
}

<?xml version="1.0"?>
<response>
    <job>
        <jobId>130fe17ee35d8e0444d18aeed9265555ede53050</jobId>
        <jobTitle>My Photo Editing</jobTitle>
        <jobReference>J888492240117</jobReference>
        <jobStatus>Complete</jobStatus>
        <jobDateSubmitted>2024-03-19 15:11:34</jobDateSubmitted>
        <jobCost>7.00</jobCost>
        <jobCostCurrency>AUD</jobCostCurrency>
        <jobDateCompleted>2024-03-20 12:30:24</jobDateCompleted>
        <output>
            <file>
                <fileId>75eebcbab044b3fe3358392b56d92b8c6fd6d208</fileId>
                <fileURL>https://boxbrownie.b-cdn.net/completed/75eebcbab044b3fe3358392b56d92b8c6fd6d208.jpg</fileURL>
            </file>
        </output>
    </job>
</response>

Rework a Photo Editing Job

POST /api/v2/job/reworkPhotoEditing

Endpoint: https://www.boxbrownie.com/api/v2/job/reworkPhotoEditing
HTTP Method: POST
Requires Authentication? Yes
Required Parameters: xml
Optional Parameters: (string) responseFormat [json|xml]

After a Photo Editing job has been completed, you will have the ability to submit rework requests for any number of completed output images. Similarly to creating a new job, you will be required to supply an XML payload describing which images to rework, with instructions about what you want changed.

You must supply either a <jobId> or a <jobReference> and at least one <rework> block that contains both one <fileId> and one <reworkComment>

Images are supplied in the form of a <fileId>, which can be obtained when retrieving a completed job.

Note: Photo Editing jobs can only be reworked if it has been less than 2 months since the jobDateCompleted time, and if there are no existing active reworks for any supplied <fileId> values.

Example XML

Below, you can see an example XML payload. In this example, we are requesting 1 rework for the supplied jobId.

<job>
    <jobId>130fe17ee35d8e0444d18aeed9265555ede53050</jobId>
    <rework>
        <fileId>75eebcbab044b3fe3358392b56d92b8c6fd6d208</fileId>
        <reworkComment>Please add more clouds in the sky</reworkComment>
    </rework>
</job>

Example Response

{
  "success": "1"
}

<?xml version="1.0"?>
<response>
    <success>1</success>
</response>

Photo Editing Types

GET /api/v2/job/photoEditingType

Endpoint: https://www.boxbrownie.com/api/v2/job/photoEditingType
Endpoint: https://www.boxbrownie.com/api/v2/job/photoEditingType/{editName}
Endpoint: https://www.boxbrownie.com/api/v2/job/photoEditingType/{editName}/{optionName}
HTTP Method: GET
Requires Authentication? No
Optional Parameters:
(string) editName,
(string) optionName,
(string) responseFormat [json|xml]

When creating a new Photo Editing job, you will supply one or more <photoEditingType> blocks to tell us how you would like your image editing to be done. This is done by providing am <editName> and pairs of <optionName> and <optionValue>.

You can query this endpoint to return a list of all accepted photo editing types and their accepted options/values. Alternatively, you can provide the optional editName parameter to return only information and accepted values for that specific edit type

Example Response

URLhttps://www.boxbrownie.com/api/v2/job/photoEditingType

{
  "photoEditingTypes": [
    {
      "editName": "BACKGROUND_REMOVAL_TIER_1",
      "editDescription": "Background Removal - Simple",
      "options": {}
    },
    {
      "editName": "IMAGE_ENHANCEMENT_REAL_ESTATE",
      "editDescription": "Image Enhancement Real Estate",
      "options": [
        {
          "optionName": "GRASS_REPAIR",
          "optionDescription": "Grass Repair or Replacement",
          "optionType": "Multiple Choice",
          "optionCompulsory": "No",
          "optionValues": [
            {
              "optionValue": "OPTION_YES",
              "optionValueDescription": "Yes",
              "optionValueCreditCost": "0"
            },
            {
              "optionValue": "OPTION_NO",
              "optionValueDescription": "No",
              "optionValueCreditCost": "0"
            }
          ]
        },
        {
          "optionName": "SKY_REPLACEMENT",
          "optionDescription": "Sky Replacement",
          "optionType": "Multiple Choice",
          "optionCompulsory": "No",
          "optionValues": [
            {
              "optionValue": "OPTION_YES",
              "optionValueDescription": "Yes",
              "optionValueCreditCost": "0"
            },
            {
              "optionValue": "OPTION_NO",
              "optionValueDescription": "No",
              "optionValueCreditCost": "0"
            }
          ]
        },
        ...
      ]
    },
    ...
  ]
}

URLhttps://www.boxbrownie.com/api/v2/job/photoEditingType?responseFormat=xml

<?xml version="1.0"?>
<response>
    <photoEditingTypes>
        <editName>BACKGROUND_REMOVAL_TIER_1</editName>
        <editDescription>Background Removal - Simple</editDescription>
        <options/>
    </photoEditingTypes>
    <photoEditingTypes>
        <editName>IMAGE_ENHANCEMENT_REAL_ESTATE</editName>
        <editDescription>Image Enhancement Real Estate</editDescription>
        <options>
            <optionName>GRASS_REPAIR</optionName>
            <optionDescription>Grass Repair or Replacement</optionDescription>
            <optionType>Multiple Choice</optionType>
            <optionCompulsory>No</optionCompulsory>
            <optionValues>
                <optionValue>OPTION_YES</optionValue>
                <optionValueDescription>Yes</optionValueDescription>
                <optionValueCreditCost>0</optionValueCreditCost>
            </optionValues>
            <optionValues>
                <optionValue>OPTION_NO</optionValue>
                <optionValueDescription>No</optionValueDescription>
                <optionValueCreditCost>0</optionValueCreditCost>
            </optionValues>
        </options>
        <options>
            <optionName>SKY_REPLACEMENT</optionName>
            <optionDescription>Sky Replacement</optionDescription>
            <optionType>Multiple Choice</optionType>
            <optionCompulsory>No</optionCompulsory>
            <optionValues>
                <optionValue>OPTION_YES</optionValue>
                <optionValueDescription>Yes</optionValueDescription>
                <optionValueCreditCost>0</optionValueCreditCost>
            </optionValues>
            <optionValues>
                <optionValue>OPTION_NO</optionValue>
                <optionValueDescription>No</optionValueDescription>
                <optionValueCreditCost>0</optionValueCreditCost>
            </optionValues>
        </options>
        ...
    </photoEditingTypes>
    ...
</response>

URLhttps://www.boxbrownie.com/api/v2/job/photoEditingType/IMAGE_ENHANCEMENT_REAL_ESTATE

{
  "editName": "IMAGE_ENHANCEMENT_REAL_ESTATE",
  "editDescription": "Image Enhancement Real Estate",
  "options": [
    {
      "optionName": "GRASS_REPAIR",
      "optionDescription": "Grass Repair or Replacement",
      "optionType": "Multiple Choice",
      "optionCompulsory": "No",
      "optionValues": [
        {
          "optionValue": "OPTION_YES",
          "optionValueDescription": "Yes",
          "optionValueCreditCost": "0"
        },
        {
          "optionValue": "OPTION_NO",
          "optionValueDescription": "No",
          "optionValueCreditCost": "0"
        }
      ]
    },
    {
      "optionName": "SKY_REPLACEMENT",
      "optionDescription": "Sky Replacement",
      "optionType": "Multiple Choice",
      "optionCompulsory": "No",
      "optionValues": [
        {
          "optionValue": "OPTION_YES",
          "optionValueDescription": "Yes",
          "optionValueCreditCost": "0"
        },
        {
          "optionValue": "OPTION_NO",
          "optionValueDescription": "No",
          "optionValueCreditCost": "0"
        }
      ]
    },
    ...
  ]
}

URLhttps://www.boxbrownie.com/api/v2/job/photoEditingType/IMAGE_ENHANCEMENT_REAL_ESTATE?responseFormat=xml

<?xml version="1.0"?>
<response>
    <editName>IMAGE_ENHANCEMENT_REAL_ESTATE</editName>
    <editDescription>Image Enhancement Real Estate</editDescription>
    <options>
        <optionName>GRASS_REPAIR</optionName>
        <optionDescription>Grass Repair or Replacement</optionDescription>
        <optionType>Multiple Choice</optionType>
        <optionCompulsory>No</optionCompulsory>
        <optionValues>
            <optionValue>OPTION_YES</optionValue>
            <optionValueDescription>Yes</optionValueDescription>
            <optionValueCreditCost>0</optionValueCreditCost>
        </optionValues>
        <optionValues>
            <optionValue>OPTION_NO</optionValue>
            <optionValueDescription>No</optionValueDescription>
            <optionValueCreditCost>0</optionValueCreditCost>
        </optionValues>
    </options>
    <options>
        <optionName>SKY_REPLACEMENT</optionName>
        <optionDescription>Sky Replacement</optionDescription>
        <optionType>Multiple Choice</optionType>
        <optionCompulsory>No</optionCompulsory>
        <optionValues>
            <optionValue>OPTION_YES</optionValue>
            <optionValueDescription>Yes</optionValueDescription>
            <optionValueCreditCost>0</optionValueCreditCost>
        </optionValues>
        <optionValues>
            <optionValue>OPTION_NO</optionValue>
            <optionValueDescription>No</optionValueDescription>
            <optionValueCreditCost>0</optionValueCreditCost>
        </optionValues>
    </options>
    ...
</response>

Accepted Photo Editing Types

Below is a table of accepted <editName> keys. Click on an <editName> to see a table of accepted <optionName> keys for that item.

Note: If an edit type is not clickable in the below table, then it does not have any child options, so an <options> block is not required for that edit type.

Edit Name	Edit Description
BACKGROUND_REMOVAL_TIER_1	Background Removal - Simple
BACKGROUND_REMOVAL_TIER_2	Background Removal - Medium
BACKGROUND_REMOVAL_TIER_3	Background Removal - Hard
IMAGE_ENHANCEMENT_REAL_ESTATE	Image Enhancement Real Estate
IMAGE_ENHANCEMENT_AUTOMOTIVE	Image Enhancement Automotive
IMAGE_ENHANCEMENT_MARINE	Image Enhancement Marine
IMAGE_ENHANCEMENT_GENERAL	Image Enhancement General
ITEM_REMOVAL_TIER_2	Item Removal & Virtual Cleaning - Standard
ITEM_REMOVAL_TIER_1	Item Removal & Virtual Cleaning - Minor
COLOUR_CHANGE	Colour Change
IMAGE_ENHANCEMENT_DAY_TO_DUSK	Day to Dusk
BACKGROUND_CHANGE	Background Change
PORTRAIT_RETOUCHING	Portrait Retouching
AERIAL_EDITING_COLOUR_FADE	Aerial Editing - Color Fade
AERIAL_EDITING_DROP_PIN	Aerial Editing - Drop Pin
AERIAL_EDITING_LOT_HIGHLIGHT_MULTI	Aerial Editing - Multiple Lot Highlight
AERIAL_EDITING_LOT_HIGHLIGHT_SINGLE	Aerial Editing - Single Lot Highlight
AERIAL_EDITING_COMBO	Aerial Editing - Combo
IMAGE_ENHANCEMENT_360	360 Image Enhancement
ITEM_REMOVAL_360_TIER_2	360 Item Removal & Virtual Cleaning - Standard
ITEM_REMOVAL_360_TIER_1	360 Item Removal & Virtual Clean - Minor
SHADOW_REMOVAL	Shadow Removal
TURN_ON_LIGHTS	Turn on Lights

Topics

Photo Editing

Overview

Create a Photo Editing Job

Example XML

Example Response

Simulate a Photo Editing Job

Example Response

Retrieve a Photo Editing Job

Example Response

Rework a Photo Editing Job

Example XML

Example Response

Photo Editing Types

Example Response

Accepted Photo Editing Types