Automate your post-production workflow with Imagen API

  • Updated

Imagen overview

Imagen is an AI-powered solution that eliminates hours of busy work from post-production for professional photographers. 

How does it work? 

Photographers create an AI Profile or choose a Talent or Imagen AI Profile. Then, they upload photos to Imagen. Imagen edits the photos with their AI Profile in a fraction of the time that the manual process takes. Last, they export the photos and deliver them to their customers.

Imagen API streamlines and automates the photographer’s post-production editing workflow, similar to the Imagen app. This document explains the flow and the endpoints you need to call.

These are the main steps when using Imagen API: 

  1. Choose an AI Profile – Try out AI Profiles to find one to use for editing with Imagen API.
  2. Cull your photos before uploading them for editing. Culling isn't part of Imagen API.
  3. Edit photos – Upload photos to Imagen’s S3 bucket on AWS to edit them with an AI Profile and AI tools.
  4. Export photos for delivery – Export the edited photos in a project to JPEG format. This step isn’t mandatory. Some companies prefer to tweak edits and export photos with their editing software.

Before you begin

Prerequisites

You need to sign up for Imagen before you can use Imagen API.  Then, email the Imagen customer success team to ask for an API key. In your email, include the email address you used to sign up for Imagen.

Imagen base URL

The base URL for the Imagen API is https://api-beta.imagen-ai.com/v1/.

Reference API docs

Here is the reference API documentation for Imagen API.

Authentication

Imagen API uses an API key for authentication. Add it as a header to your requests in text format. The header name is x-api-key. 

Here is an example:

curl --location ‘https://api-beta.imagen-ai.com/v1/profiles/’ \

--header ‘x-api-key: <api_key>’ \

--header ‘Content-Type: application/json’ 

Supported file formats for editing photos

Imagen API supports these file formats for editing photos:

  • RAW: NEF, CR2, CR3, ARW, NRW, CRW, SRF, SR2, ORF, RW2, RAF, PTX, PEF, RWL, SRW, 3FR, and FFF
  • DNG
  • JPEG 

Choose an AI Profile

AI Profiles predict a photographer’s editing style and then edit the photos accordingly. Imagen offers many AI Profiles for free, or you can create one from your photos. 

You choose an AI Profile that will be compatible with the photos you want to edit. Make sure to match the file format and editing style of your photos. Then, call the /profiles/ endpoint to get a list of all available profiles. In the response, you find the profile_key of the one you want to use.

  1. Edit your photos online to choose an AI Profile you like. You can upload up to 10 RAW photos and quickly get results.  If you don’t find one you like, use the Imagen app to create a Personal AI Profile.
  2. Get a list of AI Profiles and their keys.

Call GET https://api-beta.imagen-ai.com/v1/profiles/ to get a list of AI Profiles available to edit your photos. 

The response includes the Personal AI Profiles you created in the Imagen app and all available Talent and Imagen AI Profiles. Each AI Profile has a profile_key that identifies it. You will need this profile_key when editing the photos in your project.

Response example with a sample of the available AI Profiles

{

    "data": {

        "profiles": [

            {

                "profile_key": <profile key of the Personal AI Profile>,

                "profile_name": "wedding",

                "profile_type": "Personal",

                "image_type": "RAW"

            },

            {

                "profile_key": 14715,

                "profile_name": "LOVE & LIGHT",

                "profile_type": "Talent",

                "image_type": "RAW"

            },

            {

                "profile_key": 163322,

                "profile_name": "ELEGANT HOME",

                "profile_type": "Talent",

                "image_type": "RAW"

            }

        ]

    }

}



Choose AI tools to improve editing

AI tools offer additional AI-powered photo processing that improves the editing of the photos in the project. You can mix and match the AI tools according to your needs. Some AI tools are mutually exclusive, so you must choose one or the other. Others are geared to specific photography types like real estate or sports. 

In this section, we cover how to choose AI tools. Later in the process, you add the AI tools to the edit request.

Imagen AI tools

AI tool parameter Description
crop Crops to a 2x3 aspect ratio for optimal composition in many types of photography. It can’t be used together with headshot_crop or portrait_crop.
headshot_crop Aligns and sizes all your headshots consistently, making it ideal for yearbook and professional headshots. It centers the subject and aligns the eyes to the same horizontal line, across photos. It can’t be used together with crop or portrait_crop.
hdr_merge Combines multiple photos with different exposures into one photo so that the exposure for the outside and the inside are both correct. It is used primarily for real estate photography. See HDR Merge for the requirements.
perspective_correction Corrects distortions in real estate photography caused by wide-angle lenses or imperfect shooting angles so that vertical and horizontal lines are straight. It can’t be used together with straighten.
portrait_crop Centers the main subject of each photo and then crops with a 4x5 aspect ratio. It keeps optimal spacing above the head and other key details. Recommended for portrait and studio shoots as well as school and sports. It can’t be used together with crop or headshot_crop.
straighten Rotates each photo according to its horizon. It can’t be used together with perspective_correction.
subject_mask Selects the photo's main subject in a similar way to Lightroom, applies a mask using brushes, and then applies a local AI edit to that mask.
smooth_skin Reduces the visibility of imperfections in the skin, such as fine lines and blemishes, resulting in a more polished and visually appealing complexion.
window_pull Optimizes exposure to balance interior and exterior lighting. It works with HDR bracketed shots and post-HDR merged photos, eliminating hours of manual window masking. Recommended for real estate photography.

 

Mutually exclusive AI tools

Some similar AI tools are mutually exclusive from each other. Choose either:

  • crop, headshot_crop, or portrait_crop
  • perspective_correction or straighten.

AI tools for different photography types

Real estate

For real estate photography, use hdr_merge and perspective_correction. Make sure you don't use the straighten AI tool.

School and sports

For school and sports photography, use portrait_crop.

General for all types

These AI tools are good for most photography types.

  • crop
  • straighten
  • subject_mask
  • smooth_skin

 

Edit photos

1. Create a project

Call POST https://api-beta.imagen-ai.com/v1/projects/ to create a project.

We recommend creating a project for each shoot. A project organizes your photos with the AI Profile you chose for editing these photos. The response is the project_uuid used to identify this project. Use this project_uuid until you export your photos to JPEG.

Response example

{

    "data": {

        "project_uuid": "<project_uuid>"

    }

}

 

2. Get temporary upload links to upload photos

Call POST https://api-beta.imagen-ai.com/v1/projects/<PROJECT_UUID>/get_temporary_upload_links.

In the request, in the files_list param, include the file names of the photos to upload. Use list format.

The response includes a temporary link for each photo to Imagen’s S3 bucket on AWS. This link is the AWS presigned URL.

Request example

curl --location ‘https://api.dev.imagen-ai.com/v1/projects/<project_uuid>/get_temporary_upload_links’ \

--header ‘x-api-key: <api_key>’ \

--header ‘Content-Type: application/json’ \

--data ‘{

    “files_list”: [

        {“file_name”: “922A4846.CR2”},

        {“file_name”: “922A4832.CR2”},

        {“file_name”: “922A4818.CR2”},

        {“file_name”: “922A4809.CR2”}

    ]

}’

 

Response example

{

    "data": {

        "files_list": [

            {

                "file_name": "922A4846.raw",

                "upload_link": "<presigned URL for 922A4846.raw>"

            },

            {

                "file_name": "922A4832.raw",

                "upload_link": "<presigned URL for 922A4832.raw>"

            },

            {

                "file_name": "922A4818.raw",

                "upload_link": "<presigned URL for 922A4818.raw>"

            },

            {

                "file_name": "922A4809.raw",

                "upload_link": "<presigned URL for 922A4809.raw>"

            }

        ]

    }

}



3. Upload each photo to its temporary upload link

Upload photos to Imagen’s S3 bucket on AWS with the temporary upload links from the response in the previous step. Use any method you like.

For more information on uploading files with a presigned URL, see this guide in the AWS documentation.

Testing in Postman

  • Delete Content-Type from the header.
  • In the Params tab, add a new parameter named Content-Type with an empty string ("") as its value.

Request header requirements

If you included md5 in the files_list param in the request for the temporary upload links, make sure to include MD5 in the request header to upload the photos. For sample code in Python, see api_client.py in the Imagen API project in Github.

Request body requirements

In the request body, add Content-Type as a query parameter with an empty string ("") as its value.

4. Start editing 

Call POST https://api-beta.imagen-ai.com/v1/projects/<PROJECT_UUID>/edit to start editing with the AI Profile you chose. 

In the request body, include the:

Example of the request body

{

  "profile_key": <profile key>,

  "hdr_merge": true,

  "photography_type": "NO_TYPE",

  "callback_url": "string",

  "perspective_correction": true

}

The response is a message that the project was edited successfully. If there is an error, email our customer success team.

Profile key

The profile_key is an identifier for the AI Profile you use to edit your project. Use integer format. See the response in Choose an AI Profile to get your profile_key.

AI tools

An AI tool is an additional AI-powered photo processing tool that you can add when editing the photos in the project. 

Photography type

The photography_type indicates the type of photography shoot in the project. This param is optional. 

Here are the photography_type values:

  • WEDDING
  • REAL_ESTATE
  • SCHOOL
  • SPORTS
  • EVENTS
  • PORTRAITS
  • NO_TYPE
  • OTHER
  • LANDSCAPE_NATURE
  • FAMILY_NEWBORN
  • BOUDOIR

Callback URL

The callback_url is a POST endpoint that Imagen can use to send status messages to your API. This param is optional. If you use it, you don’t need to check the edit status. This endpoint must be open to Imagen. 

Possible statuses sent in the request are:

Response example

{“project_uuid”: “<the project UUID>”, “status”: “Failed/Completed”, “action”: “edit/export”“}



5. Check the edit status

Call GET https://api-beta.imagen-ai.com/v1/projects/<PROJECT_UUID>/edit/status to get the current status of the editing process. Continue calling this endpoint with long polling until the status is Completed.

If you want to bypass this status check, include the callback_url in the /projects/<PROJECT_UUID>/edit/ request. See Callback URL for more information.

Here are the statuses in the response:

  • Pending: The editing process hasn’t started. Once the editing starts, the status will change to IN PROGRESS.
  • In Progress: Imagen API is in the process of editing the photos.
  • Failed: Email the customer success team.
  • Completed: Imagen API has finished editing the photos. Continue to one of the following:

 

6. Get temporary download links to download edited photos

After receiving a COMPLETED status, call GET https://api-beta.imagen-ai.com/v1/projects/<PROJECT_UUID>/edit/get_temporary_download_link. 

In the request, include the photos to download in the files_list param. Use list format.

The response includes a temporary link for each photo to Imagen’s S3 bucket on AWS. This link is the AWS presigned URL.

Response example

{

    "data": {

        "files_list": [

            {

                "file_name": "922A4846.DNG",

                "upload_link": "<presigned URL for 922A4846.DNG>"

            },

            {

                "file_name": "922A4832.DNG",

                "upload_link": "<presigned URL for 922A4832.DNG>"

            },

            {

                "file_name": "922A4818.DNG",

                "upload_link": "<presigned URL for 922A4818.DNG>"

            },

            {

                "file_name": "922A4809.DNG",

                "upload_link": "<presigned URL for 922A4809.DNG>"

            }

        ]

    }

}

 

7. Download photos locally

When Imagen returns the edited files, these are the respective formats: 

File format before edit File format returned after edit
RAW XMP
Note: When editing photos with HDR Merge, the returned format is always DNG, even though the file format before editing was RAW.
DNG DNG with embedded XMP
JPEG JPEG with embedded XMP


Download photos from Imagen’s S3 bucket on AWS with the temporary download links from the response in the previous step. Use any method you like. For sample code in Python, see api_client.py in the Imagen API project in Github.

For more information on downloading files from AWS, see this guide in the AWS documentation.

Export photos for delivery

Imagen API exports all the photos in a project to JPEG format. This step is optional. Some photographers tweak the edits and export them with their editing software. After exporting the photos, you deliver them or upload them to a gallery.

1. Export the photos in the project

Call POST https://api-beta.imagen-ai.com/v1/projects/<PROJECT_UUID>/export. The response includes the project_uuid and a message that the export was successful. If there is an error, email our customer success team.

2. Check the export status

Call GET https://api-beta.imagen-ai.com/v1/projects/<PROJECT_UUID>/export/status. The response includes the status of the export. Possible statuses are:

  • IN PROGRESS: Imagen API is in the process of editing the photos.
  • FAILED: Email the customer success team.
  • COMPLETED: Imagen API has finished exporting the photos to JPEG. 

3. Download exported JPEG photos

Get temporary download links to download exported JPEG photos

After the export status is returned as COMPLETED, call GET https://api-beta.imagen-ai.com/v1/projects/<PROJECT_UUID>/export/get_temporary_download_links. 

In the request, include the exported photos to download in the files_list param. Use list format.

The response includes a temporary link for each photo to Imagen’s S3 bucket on AWS. This link is the AWS presigned URL.

Response example

{

    "data": {

        "files_list": [

            {

                "file_name": "922A4846.JPG",

                "upload_link": "<presigned URL for 922A4846.JPG>"

            },

            {

                "file_name": "922A4832.JPG",

                "upload_link": "<presigned URL for 922A4832.JPG>"

            },

            {

                "file_name": "922A4818.JPG",

                "upload_link": "<presigned URL for 922A4818.JPG>"

            },

            {

                "file_name": "922A4809.JPG",

                "upload_link": "<presigned URL for 922A4809.JPG>"

            }

        ]

    }

}

 

Download exported JPEG photos locally

Download photos from Imagen’s S3 bucket on AWS with the temporary download links from the response in the previous step. Use any method you like. For sample code in Python, see api_client.py in the Imagen API project in Github.

For more information on downloading files from AWS, see this guide in the AWS documentation.

Was this article helpful?

Have more questions? Submit a request