Automate your post-production workflow with Imagen API

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 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. Edit photos – Upload photos to edit them with an AI Profile and AI tools.
  3. 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’  We appreciate your patience.

Supported file formats for editing photos

Imagen API supports these file formats for editing photos:

  • RAW: NEF, CR2, ARW, NRW, CRW, SRF, SR2, ORF, RW2, RAF, PTX, PEF, RWL, SRW, CR3, 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"

            }

        ]

    }

}



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 sample code in Python, see api_client.py in the Imagen API project in Github.

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

 

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>,

  "crop": false,

  "hdr_merge": false,

  "straighten": false,

  "subject_mask": false,

  "photography_type": "NO_TYPE",

  "callback_url": "string",

  "smooth_skin": false,

  "perspective_correction": false

}

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. 

AI tool parameter Description
crop Crops to a 2x3 aspect ratio for optimal composition in many types of photography.
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. JPEG isn’t supported with HDR Merge.
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.
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.

 

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?