HDR

In this guide we will be walking you through how to enhance your first HDR image, you will:

1. Learn how to register the fact you want to upload 2 or more brackets for a HDR image with Autoenhance

2. Upload your image file for each bracket to Autoenhance using the provided endpoint received after registering your image

3. Tell Autoenhance you have finished uploading your brackets and you are ready for it to start merging them.

4. Checking the status of the order

5. Downloading the final enhanced HDR image

This guide assumes the following:

• You have already have an API key, if you don't have one please see our guide here.

• That you have already uploaded a single bracket, if you haven't we reccomend you follow our guide here

1. Uploading the brackets

Before Autoenhance can enhance your HDR image it needs each bracket to be uploaded, the process works the same as for a single bracket except we need to indicate that we are uploading brackets for a HDR image. To do this we need to do two things:

• Set the hdr field to true, this indicates that we want Autoenhance to operate in HDR mode and to not enhance our images until we have indicated all of our brackets have been uploaded.

• Provide an order_id, this is so that Autoenhance knows that these brackets belong together and are eligible to be merged together

In order to be able to enhance HDR images, you need to be able to upload them first. In this example we have the steps from the Single Bracket page

Before you continue You don't need to specify the enhancement preferences while uploading brackets. All of the preferences must be present in the body of the post request to /orders/{id}/merge.

JavaScript

const uploadBracket = async (orderId, apiKey, file) => {
    const createImageResponse = await fetch(
      "https://api.autoenhance.ai/v3/images/",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "x-api-key": apiKey,
        },
        body: JSON.stringify({
          order_id: orderId, // order_id needs to be specified
          image_name: file.name, 
          contentType: file.type,
          hdr:true // hdr flag needs to be present and set to true
        }),
      }
    );

    const { s3PutObjectUrl } = await createImageResponse.json();
    
    if(s3PutObjectUrl){
      const uploadImageResponse = await fetch(s3PutObjectUrl, {
        method: "PUT",
        headers: {
          "Content-Type": file.type,
          "x-api-key": apiKey,
        },
        body: file,
      });
      
      if(uploadImageResponse.ok){
        console.log('Image successfully uploaded')
      } else {
        console.log('Error uploading image');
      }
    }
}

Python

import requests
import json

def upload_bracket(order_id, api_key, file_path):
    create_image_url = "https://api.autoenhance.ai/v3/images/"
    headers = {
        "Content-Type": "application/json",
        "x-api-key": api_key,
    }
    payload = {
        "order_id": order_id, # order_id needs to be specified
        "image_name": file_path.split('/')[-1],
        "contentType": file.type,
        "hdr": True # hdr flag needs to be present and set to True
    }
    
    create_image_response = requests.post(create_image_url, headers=headers, data=json.dumps(payload))
    
    if create_image_response.status_code != 200:
        create_image_response.raise_for_status()

    create_image_data = create_image_response.json()
    s3_put_object_url = create_image_data.get('s3PutObjectUrl')
    
    if s3_put_object_url:
        with open(file_path, 'rb') as file_data:
            upload_image_headers = {
                "Content-Type": file_data.type,
                "x-api-key": api_key,
            }
            upload_image_response = requests.put(s3_put_object_url, headers=upload_image_headers, data=file_data)
            
            return upload_image_response
    else:
        raise ValueError("s3PutObjectUrl not found in the response")

PHP

function upload_bracket($order_id, $api_key, $file) {
    $create_image_url = "https://api.autoenhance.ai/v3/images/";

    $create_image_data = array(
        "order_id" => $order_id,
        "image_name" => $file['name'],
        "contentType" => $file['type'],
        "hdr" => true
    );

    $create_image_options = array(
        'http' => array(
            'header'  => "Content-Type: application/json\r\n" .
                         "x-api-key: $api_key",
            'method'  => 'POST',
            'content' => json_encode($create_image_data),
        ),
    );

    $create_image_context  = stream_context_create($create_image_options);
    $create_image_result = file_get_contents($create_image_url, false, $create_image_context);

    if ($create_image_result === FALSE) {
        echo 'Error creating image';
        return;
    }

    $create_image_response = json_decode($create_image_result, true);
    $s3_put_object_url = $create_image_response['s3PutObjectUrl'];

    if ($s3_put_object_url) {
        $upload_image_options = array(
            'http' => array(
                'header'  => "Content-Type: " . $file['type'] . "\r\n" .
                             "x-api-key: $api_key",
                'method'  => 'PUT',
                'content' => file_get_contents($file['tmp_name']),
            ),
        );

        $upload_image_context  = stream_context_create($upload_image_options);
        $upload_image_result = file_get_contents($s3_put_object_url, false, $upload_image_context);

        if ($upload_image_result === FALSE) {
            echo 'Error uploading image';
            return;
        }

        echo 'Image successfully uploaded';
    }
}

cURL

Create image

curl -X POST \
  https://api.autoenhance.ai/v3/images/ \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
        "order_id": "YOUR_ORDER_ID",
        "image_name": "your-image-name.jpg",
        "contentType": "image/jpeg",
        "hdr": true
      }'

Upload Image to S3
Replace S3_PUT_OBJECT_URL with the value of s3PutObjectUrl received from the previous response

curl -X PUT \
  S3_PUT_OBJECT_URL \
  -H 'Content-Type: image/jpeg' \
  -H 'x-api-key: YOUR_API_KEY' \
  --data-binary @path/to/your/image.jpg

2. Uploading your images and triggering HDR merge

Once you have uploaded all of your brackets, you are now ready to request Autoenhance start merging them.

There are two options depending on your use case.

Automatic Merging

By default when you call the /orders/<order_id>/merge endpoint, Autoenhance will analyse the metadata and visual similarity of your brackets. They will be automatically grouped together and returned as a single HDR image.

Fixed Merging

In cases where you already know each time how many brackets you shot you can provide the /orders/<order_id>/merge endpoint the number_of_brackets_per_image field with a number - in this case Autoenhance willsort your brackets by the time they were shot using their metadata and group your brackets based on this i.e if you set this to 3 then every 3 brackets will be grouped into one image

Make sure you have successfully uploaded all of your brackets including their metadata before calling the merge endpoint. Failure to do so may result in HDR images with brackets that are missing or incorrectly grouped.

JavaScript

const uploadAllBrackets = async (apiKey, files, orderId) => {  
  const promises = files.map(file => uploadBracket(orderId, apiKey, file));
  
  await Promise.all(promises);
  
  const mergeResponse = await fetch(
    `https://api.autoenhance.ai/v3/orders/${orderId}/merge`,
    {
      method: "POST",
      headers: {
        "x-api-key": apiKey,
      }
    }
  );
  
  // This is an URL to our web application where you can
  // take a look at your order, you don't need to return it.
  return `https://app.autoenhance.ai/orders/${orderId}`
};

const apiKey = YOUR_API_KEY;
const files = [File, File, File] // Array of Files or Blobs
const orderId = "YOUR_UNIQUE_ORDER_ID" // Ideally generated with uuidv4

uploadAllBrackets(apiKey, files, orderId)

Python

def upload_all_brackets(api_key, files, order_id):
    for file in files:
        upload_bracket(order_id, api_key, file)

    merge_url = f"https://api.autoenhance.ai/v3/orders/{order_id}/merge"
    merge_headers = {"x-api-key": api_key}
    merge_response = requests.post(merge_url, headers=merge_headers)
    if merge_response.status_code != 200:
        raise Exception(f"Failed to merge order: {merge_response.text}")
  
    #This is an URL to our web application where you can
    #take a look at your order, you don't need to return it.
    return f"https://app.autoenhance.ai/orders/{order_id}"

api_key = "YOUR_API_KEY"
files = [open('file1.jpg', 'rb'), open('file2.jpg', 'rb'), open('file3.jpg', 'rb')]  # List of file objects
order_id = "YOUR_UNIQUE_ORDER_ID"  # Ideally generated with uuid.uuid4()

order_url = upload_all_brackets(api_key, files, order_id)

# Close the files after uploading
for file in files:
    file.close()

print(order_url)

PHP

function upload_all_brackets($api_key, $files, $order_id) {
    $promises = array_map(function($file) use ($order_id, $api_key) {
        return upload_bracket($order_id, $api_key, $file);
    }, $files);

    $merge_url = "https://api.autoenhance.ai/v3/orders/$order_id/merge";

    $merge_options = array(
        'http' => array(
            'header'  => "x-api-key: $api_key",
            'method'  => 'POST',
        ),
    );

    $merge_context  = stream_context_create($merge_options);
    $merge_result = file_get_contents($merge_url, false, $merge_context);

    if ($merge_result === FALSE) {
        return 'Error merging brackets';
    }

    // Return the URL to the web application
    return "https://app.autoenhance.ai/orders/$order_id";
}

$api_key = "YOUR_API_KEY";
$files = [/* Array of Files or Blobs */];
$order_id = "YOUR_UNIQUE_ORDER_ID";

upload_all_brackets($api_key, $files, $order_id);

Untitled

Upload each bracket

for file in file1 file2 file3; do
    # Replace file1, file2, file3 with the actual paths to your files
    curl -X POST \
      https://api.autoenhance.ai/v3/images/ \
      -H 'Content-Type: application/json' \
      -H 'x-api-key: YOUR_API_KEY' \
      -d '{
            "order_id": "YOUR_ORDER_ID",
            "image_name": "your-image-name.jpg",
            "contentType": "image/jpeg",
            "hdr": true
          }'
done

Merge brackets

curl -X POST \
  https://api.autoenhance.ai/v3/orders/YOUR_ORDER_ID/merge \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY'

3. Checking the order status

Grouping brackets for each HDR image can take between 10 seconds to 5 minutes to complete depending on the number of brackets that need grouping.

We can check when this has finished by calling the GET /order/<order_id> endpoint and reading the is_merging and is_processing fields. Whilst the AI is still grouping the orders is_merging will be true, however if you want to display the progress of this grouping to customers then the images field will gradually be populated with images.

As each image is grouped the AI will automatically start enhancing them, you can check the status of each image individually using their status fields. Once all images have been enhanced the is_processing field for the order will change to false which can be used to stop showing any processing indicators to your end user.

You should always check your order status before downloading your images. In this case, we need to check whether the order has falsy values for is_merging and is_processing or not. You can start downloading all of your images once both of them are false.

JavaScript

const orderId = "ID_OF_YOUR_ORDER";

const checkOrderStatus = async (orderId) => {
    const response = await fetch(`https://api.autoenhance.ai/orders/${orderId}`,{
        method: "GET"
    })
    
    const { is_merging, is_processing } = await response.json();
}

Python

order_id = "ID_OF_YOUR_ORDER";

def check_order_status(order_id):
    url = f"https://api.autoenhance.ai/v3/orders/{order_id}"
    
    response = requests.get(url)
    response_data = response.json()
    
    is_merging = response_data.get('is_merging')
    is_processing = response_data.get('is_processing')
    
    return is_merging, is_processing

PHP

function check_order_status($order_id) {
    $url = "https://api.autoenhance.ai/orders/$order_id";

    $options = array(
        'http' => array(
            'method'  => 'GET',
        ),
    );

    $context  = stream_context_create($options);
    $result = file_get_contents($url, false, $context);

    if ($result === FALSE) {
        return 'Error checking order status';
    }

    $response = json_decode($result, true);
    $is_merging = $response['is_merging'];
    $is_processing = $response['is_processing'];

    return array(
        'is_merging' => $is_merging,
        'is_processing' => $is_processing
    );
}

cURL

curl -X GET \
  https://api.autoenhance.ai/orders/ID_OF_YOUR_ORDER \
  -H 'Content-Type: application/json'

4. Downloading image

Once our order has finished grouping and enhancing we can download the images as usual.

JavaScript

const apiKey = "YOUR_API_KEY";
const imageId = "ID_OF_YOUR_IMAGE";

const checkImageStatus = async (imageId) => {
    const response = await fetch(`https://api.autoenhance.ai/v3/images/${imageId}`,{
         method: "GET"   
    })
    
    const {enhanced, error} = await response.json();
    
    return {
         enhanced:enhanced,
         error:error
    }
}

const downloadImage = async (imageId, apiKey) => {
     const imageStatus = await checkImageStatus(imageId);
     if(!imageStatus.error && imageStatus.enhanced){
        const response = await fetch(
        `https://api.autoenhance.ai/v3/images/${imageId}/enhanced`,
        { 
            method: "GET",
            headers: {
                "x-api-key": apiKey,
            },
        });
        const imageSource = await response.json()
    
        return imageSource
     }
}

Python

import requests

api_key = "YOUR_API_KEY"
image_id = "ID_OF_YOUR_IMAGE"

def check_image_status(image_id):
    response = requests.get(f"https://api.autoenhance.ai/v3/images/{image_id}")
    data = response.json()
    enhanced = data.get('enhanced')
    error = data.get('error')
    
    return {
        'enhanced': enhanced,
        'error': error
    }

def download_image(image_id, api_key):
    image_status = check_image_status(image_id)
    if not image_status['error'] and image_status['enhanced']:
        response = requests.get(
            f"https://api.autoenhance.ai/v3/images/{image_id}/enhanced",
            headers={
                "x-api-key": api_key,
            }
        )
        image_source = response.json()
        return image_source

PHP

$api_key = "YOUR_API_KEY";
$image_id = "ID_OF_YOUR_IMAGE";

function check_image_status($image_id) {
    $url = "https://api.autoenhance.ai/v3/images/" . $image_id;

    $options = array(
        'http' => array(
            'method'  => 'GET',
        ),
    );

    $context  = stream_context_create($options);
    $result = file_get_contents($url, false, $context);

    if ($result === FALSE) {
        return array(
            'enhanced' => false,
            'error' => 'Error checking image status'
        );
    }

    $response = json_decode($result, true);
    return array(
        'enhanced' => $response['enhanced'],
        'error' => $response['error']
    );
}

function download_image($image_id, $api_key) {
    $image_status = check_image_status($image_id);

    if (!$image_status['error'] && $image_status['enhanced']) {
        $url = "https://api.autoenhance.ai/v3/images/" . $image_id . "/enhanced";

        $options = array(
            'http' => array(
                'method'  => 'GET',
                'header'  => "x-api-key: $api_key"
            ),
        );

        $context  = stream_context_create($options);
        $result = file_get_contents($url, false, $context);

        if ($result === FALSE) {
            return 'Error downloading enhanced image';
        }

        return json_decode($result, true);
    }

    return 'Image is not enhanced or an error occurred';
}

cURL

Check image status

curl -X GET \
  https://api.autoenhance.ai/v3/images/ID_OF_YOUR_IMAGE \
  -H 'Content-Type: application/json'

Download image

curl -X GET \
  https://api.autoenhance.ai/v3/images/ID_OF_YOUR_IMAGE/enhanced \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY'

This example uses the least possible amount of properties in order to create an image. If you want to apply any kind of preferences to it, visit our Image Settings page to find out more about them. Once you are familiar with them, simply add them in the body of the POST request to our API.