Building with Imagen

AI tool reference for Imagen API

Use this guide along with the Onboarding and Quickstart for Imagen API.

You must edit your photos to use the AI tools

AI tools offer more 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, as the table below explains. Others are geared to specific photography types like real estate or sports.

AI tool parameters

`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.

Default: Boolean false

`crop_aspect_ratio`

Changes the aspect ratio from the default aspect ratio for crop, headshot_crop, and portrait_crop. Example: "crop_aspect_ratio": "2X3"

Default: 2X3

`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. Use crop_aspect_ratio to change the aspect ratio to 1 x 1, 2 x 3, or 5 x 7.

Default: Boolean false

`portrait_crop`

Centers the main subject of each photo and then crops with a 4 x 5 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. Use crop_aspect_ratio to change the aspect ratio to 2 x 3 or 5 x 7.

Default: Boolean false

`hdr_merge`

Important: Only use with real estate photography. 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 real estate for the requirements. With HDR Merge, DNG photos must contain RAW data. DNG photos with JPEG data are not supported.

Default: Boolean false

`hdr_output_compression`

Used with hdr_merge. The default compression is LOSSY, which best balances editing speed with high quality. To remove compression without a significant increase in quality, change this param to LOSSLESS. Processing time will increase dramatically with this compression type. Example: "hdr_output_compression": "LOSSY"

Default: LOSSY

`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.

Default: Boolean false

`sky_replacement`

Important: Only use with real estate photography. Choose between different skies for your photos. Used with sky_replacement_template_id to choose the sky. These changes to the sky are saved in the XMP metadata. When you review the photos, you can adjust the sky in Adobe editing software.

Default: Boolean false

`sky_replacement_template_id`

Important: Only use with real estate photography. Identifier for the sky. To see the choices for a new sky, you need to open the app, create a project for real estate photography, and choose the Sky Replacement AI tool. Keys: 1–12 (Sky 1 through Sky 12). Example: "sky_replacement_template_id": "5"

Default: null

`straighten`

Rotates each photo according to its horizon. It can’t be used together with perspective_correction.

Default: Boolean false

`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.

Default: Boolean false

`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.

Default: Boolean false

`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.

Default: Boolean false

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 by photography type

Real estate

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

School and sports

For school and sports photography, use portrait_crop or headshot_crop.

Weddings & portraits

For weddings and portrait photography, use crop, straighten, smooth_skin, and subject_mask.

General for all types

These AI tools are good for most photography types:

crop
straighten
subject_mask
smooth_skin

Example requests

Real estate — HDR Merge, perspective correction, sky replacement, window pull:

curl -X POST \
  'https://api.imagen-ai.com/v1/projects/$PROJECT_UUID/edit' \
  --header 'x-api-key: $IMAGEN_API_KEY' \
  --header 'Content-Type;' \
  --data '{
    "profile_key": 163322,
    "photography_type": "REAL_ESTATE",
    "hdr_merge": true,
    "perspective_correction": true,
    "sky_replacement": true,
    "sky_replacement_template_id": 5,
    "window_pull": true
  }'
from imagen_sdk import EditOptions, PhotographyType

await client.start_editing(
    project_uuid,
    profile_key=163322,
    photography_type=PhotographyType.REAL_ESTATE,
    edit_options=EditOptions(
        hdr_merge=True,
        perspective_correction=True,
        sky_replacement=True,
        sky_replacement_template_id=5,
        window_pull=True,
    ),
)
const body = {
  profile_key: 163322,
  photography_type: 'REAL_ESTATE',
  hdr_merge: true,
  perspective_correction: true,
  sky_replacement: true,
  sky_replacement_template_id: 5,
  window_pull: true,
};

const res = await fetch(
  `https://api.imagen-ai.com/v1/projects/${projectUuid}/edit`,
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.IMAGEN_API_KEY!,
      'Content-Type': '',
    },
    body: JSON.stringify(body),
  }
);

const { data } = (await res.json()) as { data: EditResponse };
import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

body, _ := json.Marshal(map[string]any{
    "profile_key": 163322,
    "photography_type": "REAL_ESTATE",
    "hdr_merge": true,
    "perspective_correction": true,
    "sky_replacement": true,
    "sky_replacement_template_id": 5,
    "window_pull": true,
})
req, _ := http.NewRequestWithContext(ctx, http.MethodPost,
    "https://api.imagen-ai.com/v1/projects/"+projectUUID+"/edit",
    bytes.NewReader(body),
)
req.Header.Set("x-api-key", os.Getenv("IMAGEN_API_KEY"))
req.Header.Set("Content-Type", "")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
import java.net.URI;
import java.net.http.*;

var body = """
    {
        "profile_key": 163322,
        "photography_type": "REAL_ESTATE",
        "hdr_merge": true,
        "perspective_correction": true,
        "sky_replacement": true,
        "sky_replacement_template_id": 5,
        "window_pull": true
    }
    """;
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.imagen-ai.com/v1/projects/" + projectUuid + "/edit"))
    .header("x-api-key", System.getenv("IMAGEN_API_KEY"))
    .header("Content-Type", "")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
var response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
require 'net/http'
require 'json'
require 'uri'

uri = URI("https://api.imagen-ai.com/v1/projects/#{project_uuid}/edit")
req = Net::HTTP::Post.new(uri)
req['x-api-key'] = ENV['IMAGEN_API_KEY']
req['Content-Type'] = ''
req.body = {
  profile_key: 163322,
  photography_type: 'REAL_ESTATE',
  hdr_merge: true,
  perspective_correction: true,
  sky_replacement: true,
  sky_replacement_template_id: 5,
  window_pull: true,
}.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)['data']
<?php
$ch = curl_init('https://api.imagen-ai.com/v1/projects/' . $projectUuid . '/edit');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'x-api-key: ' . getenv('IMAGEN_API_KEY'),
    'Content-Type:',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'profile_key' => 163322,
    'photography_type' => 'REAL_ESTATE',
    'hdr_merge' => true,
    'perspective_correction' => true,
    'sky_replacement' => true,
    'sky_replacement_template_id' => 5,
    'window_pull' => true,
  ]),
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true)['data'];
using System.Net.Http;
using System.Text;
using System.Text.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key",
    Environment.GetEnvironmentVariable("IMAGEN_API_KEY"));

var payload = JsonSerializer.Serialize(new {
    profile_key = 163322,
    photography_type = "REAL_ESTATE",
    hdr_merge = true,
    perspective_correction = true,
    sky_replacement = true,
    sky_replacement_template_id = 5,
    window_pull = true,
});
// Pass "" as the media type to send an empty Content-Type header
var content = new StringContent(payload, Encoding.UTF8, "");
var response = await client.PostAsync(
    $"https://api.imagen-ai.com/v1/projects/{projectUuid}/edit",
    content
);
var json = await response.Content.ReadAsStringAsync();

Weddings & portraits — crop, straighten, smooth skin, subject mask:

curl -X POST \
  'https://api.imagen-ai.com/v1/projects/$PROJECT_UUID/edit' \
  --header 'x-api-key: $IMAGEN_API_KEY' \
  --header 'Content-Type;' \
  --data '{
    "profile_key": 5700,
    "photography_type": "WEDDING",
    "crop": true,
    "straighten": true,
    "smooth_skin": true,
    "subject_mask": true
  }'
from imagen_sdk import EditOptions, PhotographyType

await client.start_editing(
    project_uuid,
    profile_key=5700,
    photography_type=PhotographyType.WEDDING,
    edit_options=EditOptions(
        crop=True,
        straighten=True,
        smooth_skin=True,
        subject_mask=True,
    ),
)
const body = {
  profile_key: 5700,
  photography_type: 'WEDDING',
  crop: true,
  straighten: true,
  smooth_skin: true,
  subject_mask: true,
};

const res = await fetch(
  `https://api.imagen-ai.com/v1/projects/${projectUuid}/edit`,
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.IMAGEN_API_KEY!,
      'Content-Type': '',
    },
    body: JSON.stringify(body),
  }
);

const { data } = (await res.json()) as { data: EditResponse };
import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

body, _ := json.Marshal(map[string]any{
    "profile_key": 5700,
    "photography_type": "WEDDING",
    "crop": true,
    "straighten": true,
    "smooth_skin": true,
    "subject_mask": true,
})
req, _ := http.NewRequestWithContext(ctx, http.MethodPost,
    "https://api.imagen-ai.com/v1/projects/"+projectUUID+"/edit",
    bytes.NewReader(body),
)
req.Header.Set("x-api-key", os.Getenv("IMAGEN_API_KEY"))
req.Header.Set("Content-Type", "")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
import java.net.URI;
import java.net.http.*;

var body = """
    {
        "profile_key": 5700,
        "photography_type": "WEDDING",
        "crop": true,
        "straighten": true,
        "smooth_skin": true,
        "subject_mask": true
    }
    """;
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.imagen-ai.com/v1/projects/" + projectUuid + "/edit"))
    .header("x-api-key", System.getenv("IMAGEN_API_KEY"))
    .header("Content-Type", "")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
var response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
require 'net/http'
require 'json'
require 'uri'

uri = URI("https://api.imagen-ai.com/v1/projects/#{project_uuid}/edit")
req = Net::HTTP::Post.new(uri)
req['x-api-key'] = ENV['IMAGEN_API_KEY']
req['Content-Type'] = ''
req.body = {
  profile_key: 5700,
  photography_type: 'WEDDING',
  crop: true,
  straighten: true,
  smooth_skin: true,
  subject_mask: true,
}.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)['data']
<?php
$ch = curl_init('https://api.imagen-ai.com/v1/projects/' . $projectUuid . '/edit');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'x-api-key: ' . getenv('IMAGEN_API_KEY'),
    'Content-Type:',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'profile_key' => 5700,
    'photography_type' => 'WEDDING',
    'crop' => true,
    'straighten' => true,
    'smooth_skin' => true,
    'subject_mask' => true,
  ]),
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true)['data'];
using System.Net.Http;
using System.Text;
using System.Text.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key",
    Environment.GetEnvironmentVariable("IMAGEN_API_KEY"));

var payload = JsonSerializer.Serialize(new {
    profile_key = 5700,
    photography_type = "WEDDING",
    crop = true,
    straighten = true,
    smooth_skin = true,
    subject_mask = true,
});
// Pass "" as the media type to send an empty Content-Type header
var content = new StringContent(payload, Encoding.UTF8, "");
var response = await client.PostAsync(
    $"https://api.imagen-ai.com/v1/projects/{projectUuid}/edit",
    content
);
var json = await response.Content.ReadAsStringAsync();