--- title: "AI tool reference for Imagen API" description: "Every AI tool available in the Imagen API: parameters, default values, mutual exclusivity rules, and genre recommendations." canonical: https://api-docs.imagen-ai.com/docs/ai-tools/ last-updated: 2026-08-27 --- # AI tool reference for Imagen API Use this guide along with the [Onboarding](/docs/onboarding) and [Quickstart](/docs/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`](#hdr_merge), [`perspective_correction`](#perspective_correction), [`sky_replacement`](#sky_replacement), and [`window_pull`](#window_pull). Make sure you don't use the [`straighten`](#straighten) AI tool. ### School and sports For school and sports photography, use [`portrait_crop`](#portrait_crop) or [`headshot_crop`](#headshot_crop). ### Weddings & portraits For weddings and portrait photography, use [`crop`](#crop), [`straighten`](#straighten), [`smooth_skin`](#smooth_skin), and [`subject_mask`](#subject_mask). ### General for all types These AI tools are good for most photography types: - [`crop`](#crop) - [`straighten`](#straighten) - [`subject_mask`](#subject_mask) - [`smooth_skin`](#smooth_skin) ## Example requests **Real estate** - HDR Merge, perspective correction, sky replacement, window pull: ```curl 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 }' ``` ```python 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, ), ) ``` ```typescript import { PhotographyType } from 'imagen-ai-sdk'; await client.startEditing(projectUuid, { profileKey: 163322, photographyType: PhotographyType.REAL_ESTATE, editOptions: { hdr_merge: true, perspective_correction: true, sky_replacement: true, sky_replacement_template_id: 5, window_pull: true, }, }); ``` ```go import imagen "github.com/imagenai/imagen-ai-sdk/sdks/go" edit := imagen.EditRequest{ ProfileKey: 163322, PhotographyType: imagen.PhotographyTypeRealEstate, } edit.HDRMerge = imagen.Bool(true) edit.PerspectiveCorrection = imagen.Bool(true) edit.SkyReplacement = imagen.Bool(true) edit.SkyReplacementTemplateID = imagen.Int(5) edit.WindowPull = imagen.Bool(true) if err := client.StartEditing(ctx, projectUUID, edit); err != nil { log.Fatal(err) } ``` ```java import java.net.URI; 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()); ``` ```ruby 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 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']; ``` ```csharp 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 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 }' ``` ```python 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, ), ) ``` ```typescript import { PhotographyType } from 'imagen-ai-sdk'; await client.startEditing(projectUuid, { profileKey: 5700, photographyType: PhotographyType.WEDDING, editOptions: { crop: true, straighten: true, smooth_skin: true, subject_mask: true, }, }); ``` ```go import imagen "github.com/imagenai/imagen-ai-sdk/sdks/go" edit := imagen.EditRequest{ ProfileKey: 5700, PhotographyType: imagen.PhotographyTypeWedding, } edit.Crop = imagen.Bool(true) edit.Straighten = imagen.Bool(true) edit.SmoothSkin = imagen.Bool(true) edit.SubjectMask = imagen.Bool(true) if err := client.StartEditing(ctx, projectUUID, edit); err != nil { log.Fatal(err) } ``` ```java import java.net.URI; 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()); ``` ```ruby 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 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']; ``` ```csharp 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(); ```