BoxBrownie.com API v2.0 Docs

Overview

Designed for professional photographers with multiple exposures/brackets per output image.

Create a Bracketed/HDR Job

POST /api/v2/job/createBracketed

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

To create a Bracketed/HDR job, we require you to send us an XML payload that contains a job title, the expected number of outputs (expressed as an integer), a list of URLs to the images/exposures you would like edited, a list of options for the job and finally any additional comments/instructions that may be required for the job.

Your job XML should start with a <jobTitle>

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

Then, specify the <editCount>. This element is where you specify the expected number of outputs for the job. If you have a total of 3 'brackets' consisting of 7 images/exposures each for a total of 21 images, your <editCount> will be 3.

<editCount>	Int	Required	Max 1 Occurence	Sets the expected number of outputs for the job

Next, we specify the <files> element. A <files> element consists of all the images/exposures in this job, represented via individual <fileURL> elements.Note: There is no need to order your exposures so they are grouped together as our editors will sort them at edit time.

<files>		Required	Max 1 Occurence	Contains one or more `<fileURL>` elements for the file group
<fileURL>	String	Required	Multiple Allowed	A file URL.

When creating a new Bracketed/HDR job, all available editing options are enabled by default. If you however, you would like to control which editing options are applied/only apply a certain selection of our available options, you may supply an <option> block with <optionKey> values inside. See the section below on Bracketed/HDR Option Types for more information.

Note: Specifying this element is optional. If you use it, we will only add the options you choose, else all options will be ENABLED by default.

<options>		Optional	Max 1 Occurence	Contains one or more `<fileURL>` elements for the file group
<optionKey>	String	Required	Multiple Allowed	The key of an option type.

You may add an optional <jobComment> element. A <jobComment> element contains any additional instructions or requests for the job and will be passed through to our editors.

<jobComment>	Text	Optional	Max 1 Occurence	Additional instructions or requests for the job.

Optionally, you may 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 job
<sampleImageId>	String	Required	Multiple Allowed	The unique ID of a sample image from your BoxBrownie.com account.

Example XML

Below, you can see an example XML payload. This example defines a job consisting of 3 "brackets" of 7 images/exposures each, for a total of 21 images. If this were a real job, you could expect to receive 3 completed output files when completed

<job>
    <jobTitle>My Bracketed Job</jobTitle>
    <editCount>3</editCount>
    <files>
        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured01.png</fileURL>
        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured02.png</fileURL>
        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured03.png</fileURL>
        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured04.png</fileURL>
        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured05.png</fileURL>

        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured06.png</fileURL>
        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured07.png</fileURL>
        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured08.png</fileURL>
        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured09.png</fileURL>
        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured10.png</fileURL>

        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured01.png</fileURL>
        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured02.png</fileURL>
        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured03.png</fileURL>
        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured04.png</fileURL>
        <fileURL>https://d1dbtne32ilur4.cloudfront.net/img/press/featured05.png</fileURL>
    </files>
    <sampleImages>
        <sampleImageId>99ccd87633acb90545c7ebcf4f57511df8d50a33</sampleImageId>
        <sampleImageId>d9c2ca823cf01a54df60f190da405151eab3c700</sampleImageId>
    </sampleImages>
    <options>
        <optionKey>REMOVE_LENS_DISTORTION</optionKey>
        <optionKey>ADJUST_WHITE_BALANCE</optionKey>
    </options>
    <jobComment>Here is a comment</jobComment>
</job>

Example Response

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

{
  "success": "1",
  "job": {
    "jobId": "6b69da4137e8e8a400d8dc5155b2ba5bc7ab6e1c",
    "jobTitle": "My Bracketed Job",
    "jobReference": "B988857034558",
    "jobStatus": "Submitted API",
    "jobDateSubmitted": "2024-03-27 23:21:19",
    "jobCost": "6.00",
    "jobCostCurrency": "AUD"
  }
}

<?xml version="1.0"?>
<response>
    <success>1</success>
    <job>
        <jobId>6b69da4137e8e8a400d8dc5155b2ba5bc7ab6e1c</jobId>
        <jobTitle>My Bracketed Job</jobTitle>
        <jobReference>B988857034558</jobReference>
        <jobStatus>Submitted API</jobStatus>
        <jobDateSubmitted>2024-03-27 23:21:19</jobDateSubmitted>
        <jobCost>6.00</jobCost>
        <jobCostCurrency>AUD</jobCostCurrency>
    </job>
</response>

Simulate a Bracketed/HDR Job

POST /api/v2/job/simulateBracketed

Endpoint: https://www.boxbrownie.com/api/v2/job/simulateBracketed
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 Bracketed/HDR 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 Bracketed/HDR 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": "20.00",
  "jobCostCurrency": "AUD",
  "xmlIsValid": "1"
}

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

Retrieve a Bracketed/HDR 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": "6b69da4137e8e8a400d8dc5155b2ba5bc7ab6e1c",
        "jobTitle": "My HDR Job",
        "jobReference": "B988857034558",
        "jobStatus": "Complete",
        "jobDateSubmitted": "2024-03-27 23:21:19",
        "jobCost": "6.00",
        "jobCostCurrency": "AUD",
        "jobDateCompleted": "2024-03-27 23:49:17",
        "output": {
            "files": [
                {
                    "fileId": "86b9a368ce49256b4825a19ef6e276ece4d8c3d3",
                    "fileURL": "https://s3.us-west-1.wasabisys.com/dev-boxbrownie/photography/completed/86b9a368ce49256b4825a19ef6e276ece4d8c3d3.png"
                },
                {
                    "fileId": "6ee4bbae4a3d58869eb80423beccc3315c7fae67",
                    "fileURL": "https://s3.us-west-1.wasabisys.com/dev-boxbrownie/photography/completed/6ee4bbae4a3d58869eb80423beccc3315c7fae67.png"
                },
                {
                    "fileId": "813c857666d5d8a2169c44b598e69a26bae7cc10",
                    "fileURL": "https://s3.us-west-1.wasabisys.com/dev-boxbrownie/photography/completed/813c857666d5d8a2169c44b598e69a26bae7cc10.png"
                }
            ]
        }
    }
}

<?xml version="1.0"?>
<response>
    <job>
        <jobId>4fc353cec0bd01317f2b17f31e74a1c4c2a1e3bc</jobId>
        <jobTitle>My AI Copywrite Job</jobTitle>
        <jobReference>AIC311912025035</jobReference>
        <jobStatus>Complete</jobStatus>
        <jobDateSubmitted>2024-04-02 22:34:45</jobDateSubmitted>
        <jobCost>0</jobCost>
        <jobCostCurrency>AUD</jobCostCurrency>
        <jobDateCompleted>2024-04-02 23:03:26</jobDateCompleted>
        <output>Welcome to this idyllic retreat, a splendid two-bedroom unit nestled in a serene Maroochydore complex, where tranquillity meets modern convenience. This abode has been impeccably designed to cater to small families or couples seeking a harmonious blend of comfort and style.</output>
    </job>
</response>

Rework a Bracketed/HDR Job

POST /api/v2/job/reworkBracketed

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

After a Bracketed/HDR 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: Bracketed/HDR 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>

Bracketed/HDR Option Types

GET /api/v2/job/bracketedOptionType

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

For fine grain control over what editing options are applied to your job, you may supply an optional <option> block with the relevant <optionKey> values inside.

You can query this endpoint to return a list of all accepted photo editing types and their accepted options/values.

NOTE: If no <option> block is provided, all editing options are enabled by default and will be applied if/where possible.

Example Response

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

{
  "optionTypes": [
    {
      "optionName": "BALANCE_WHITE",
      "optionDescription": "White balancing"
    },
    {
      "optionName": "SHARPEN_IMAGE",
      "optionDescription": "Image sharpening"
    },
    {
      "optionName": "STRAIGHTENING",
      "optionDescription": "Vertical & horizontal straightening"
    },
    {
      "optionName": "REMOVE_BLEMISHES",
      "optionDescription": "Remove minor blemishes"
    },
    ...
  ]
}

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

<?xml version="1.0"?>
<response>
    <optionTypes>
        <optionName>BALANCE_WHITE</optionName>
        <optionDescription>White balancing</optionDescription>
    </optionTypes>
    <optionTypes>
        <optionName>SHARPEN_IMAGE</optionName>
        <optionDescription>Image sharpening</optionDescription>
    </optionTypes>
    <optionTypes>
        <optionName>STRAIGHTENING</optionName>
        <optionDescription>Vertical &amp; horizontal straightening</optionDescription>
    </optionTypes>
    <optionTypes>
        <optionName>REMOVE_BLEMISHES</optionName>
        <optionDescription>Remove minor blemishes</optionDescription>
    </optionTypes>
    ...
</response>

Accepted Option Types

Below is a table of accepted <optionKey> values that can be passed into an <options> element.

Note: Remember, specifying an <options> element with <optionKey> values is entirely optional and only needed if you require a specific set of options. If an <options> element isn't provided, ALL <optionKey> values will be applied if/where applicable.

Option Type	Option Description
SHARPEN_IMAGE	Image sharpening
REMOVE_PHOTOGRAPHER_REFLECTION	Remove photographer’s reflection
REPLACE_WINDOWS_HDR	HDR bracketing with indoor window replacement
ADD_FIRE	Add fire to fireplaces
REMOVE_FLASH_REFLECTION	Flash reflection removal
REMOVE_DUST_SPOT	Dust spot removal
REPLACE_TV_SCREEN	TV screen replacement
ADJUST_TONE	Tone adjustment
ENHANCE_WATER	Ocean/River Water Enhancement
REMOVE_POOL_CLEANERS	Remove pool cleaners from water
REPLACE_LAWN	Lawn enhancement – repair or replace
REPLACE_SKY	Sky Replacement
ADJUST_BRIGHTNESS_CONTRAST	Brightness & contrast adjustment
REMOVE_LENS_DISTORTION	Lens distortion removal
REMOVE_BLEMISHES	Remove minor blemishes
STRAIGHTENING	Vertical & horizontal straightening
ADJUST_WHITE_BALANCE	White balancing

Topics

Bracketed/HDR Editing

Overview

Create a Bracketed/HDR Job

Example XML

Example Response

Simulate a Bracketed/HDR Job

Example Response

Retrieve a Bracketed/HDR Job

Example Response

Rework a Bracketed/HDR Job

Example XML

Example Response

Bracketed/HDR Option Types

Example Response

Accepted Option Types