Use our quickstart to learn how the Imagen API works and to customize your flow. 

Complete the onboarding

You need to sign up for Imagen, set up your environment, choose an AI Profile, and a few other steps before using this quickstart. See Onboarding.

If you want to use the Imagen API with little coding, here's the SDK in Python.

1. Get a list of available AI Profiles

Get a list of AI Profiles and their keys. Here are the reference API docs for this endpoint.

GET /v1/profiles/ 

Response example 

The response includes the available AI Profiles. Each AI Profile has a profile_key that identifies it. You need this profile_key to edit the photos in your project.

{

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

            }

        ]

    }

}

2. Cull your photos without the API

Cull your photos before uploading them for editing. Culling isn't part of the Imagen API.
 

3. Create a project and get a project ID

We recommend creating a project for each shoot. A project organizes your photos with the AI Profile you chose for editing these photos. Here are the reference API docs for this endpoint.

POST /v1/projects/

Response example

The response is the project_uuid used to identify this project. Use this project_uuid until you export your photos to JPEG.

{

    "data": {

        "project_uuid": "<project_uuid>"

    }

}
 

4. Create temporary upload links to upload photos

You need a temporary link to upload each photo. In the request, in the files_list param, include the file names of the photos to upload. Use list format. Here are the reference API docs for this endpoint.

POST /v1/projects/<PROJECT_UUID>/get_temporary_upload_links

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

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

{

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

            }

        ]

    }

}

5. Upload each photo to its temporary upload link

Upload photos with a PUT request to Imagen’s S3 bucket on AWS.  Use the temporary upload links from the response in the previous step. 

Testing in Postman

• Disable Content-Type in the headers.
• Do not send Content-Type in the query params.

Request header requirements in the code

Add Content-Type to the header with an empty string ("") as its value.
 

6. Edit the photos in your project 

Before sending your photos to edit, you need:

• The value of your project_uuid
• The value of your profile_key. See the response from 1. Get a list of available AI Profiles for your profile_key.
• AI tools. See Imagen AI tools to choose the right tools for your project.
• (Optional) Callback URL. See [Add a callback URL to get status messages]

Here are the reference API docs for this endpoint.

POST /v1/projects/{project_uuid}/edit 

Request example

{

  "profile_key": <profile key>,

  "hdr_merge": true,

  "photography_type": "REAL_ESTATE",

  "callback_url": "string",

  "perspective_correction": true,

  "sky_replacement": true,

  "sky_replacement_template_id": “2”

}

Response example

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

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

Add a callback URL to get status messages

The callback_url is a POST endpoint that Imagen can use to send you status messages. 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:

• Failed: Email the customer success team.
• Completed: Imagen API has finished editing the photos. Continue to one of the following:
  • Get temporary download links to download edited photos or XMPs to tweak edits and export photos with your editing software.
    OR
  • Export photos for delivery to create exported JPEGs for customers.

Response example

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

7. Check the edit status

If you didn’t add a callback URL to your edit request, get the current status of the editing process. Continue calling this endpoint with long polling until the status is Completed.

Here are the reference API docs for this endpoint.

GET /v1/projects/<PROJECT_UUID>/edit/status

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:
  • Get temporary download links to download edited photos or XMPs to tweak edits and export photos with your editing software.
    OR
  • Export photos for delivery to create exported JPEGs for customers.

8. Get temporary download links to download edited photos or XMPs

After receiving a Completed status, get the temporary download links to download the edited photos. 

Here are the reference API docs for this endpoint.

GET /v1/projects/<PROJECT_UUID>/edit/get_temporary_download_links 

Response example

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

{

    "data": {

        "files_list": [

            {

                "file_name": "922A4846.DNG",

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

            },

            {

                "file_name": "922A4832.DNG",

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

            },

            {

                "file_name": "922A4818.DNG",

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

            },

            {

                "file_name": "922A4809.DNG",

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

            }

        ]

    }

}

9. Download edited photos locally

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

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.

Review the edits in Adobe editing software. If you open the photos with the default photo viewer on your computer, you won't see the edits. For help, see:

• Lightroom Classic: My photos are unedited after downloading the edits
• Lightroom: My photos are unedited after downloading the edits
• Photoshop: My photos are unedited after downloading the edits
• Bridge: My photos are unedited after downloading the edits

10. Optional: Export final JPEGs 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 final JPEGs, you deliver them or upload them to a gallery.

1. Export the photos in the project

POST /v1/projects/<PROJECT_UUID>/export 

Here are the reference API docs for this endpoint.

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

If you didn’t add a callback URL in your edit request, get the export status.

GET /v1/projects/<PROJECT_UUID>/export/status. 

Here are the reference API docs for this endpoint.

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. Get temporary download links to download final JPEG photos

Get the temporary download links when the export status is returned as COMPLETED. 

GET /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.

Here are the reference API docs for this endpoint.

Response example

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

{

    "data": {

        "files_list": [

            {

                "file_name": "922A4846.JPG",

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

            },

            {

                "file_name": "922A4832.JPG",

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

            },

            {

                "file_name": "922A4818.JPG",

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

            },

            {

                "file_name": "922A4809.JPG",

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

            }

        ]

    }

}

4. Download final 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.