Docs

API Documentation

Photo Enhancer API Documentation

© Ideal House AI — All rights reserved.

Base URL: https://api.ideal.house
Version: v1
Updated: 2026-04-17

Overview

The Photo Enhancer API lets you enhance real estate photos asynchronously by choosing a presetId, providing a custom prompt, or combining both.

Current request model:

  • presetId is optional.
  • prompt is optional.
  • presetId and prompt cannot both be empty. At least one of them must be provided.
  • Use imageUrl as the only image input field.
  • imageUrl supports both single-image and multi-image formats.

Workflow:

  1. Call the generate endpoint and get a taskId.
  2. Poll the result endpoint with that taskId.
  3. Read the generated image URL after the task succeeds.

Authentication

All API requests must include your API key in the request header.

HeaderRequiredDescription
APIKEYYesYour API authentication key
Content-TypeYesapplication/json for POST requests

Credits

Each successful task creation deducts credits based on imageSize: 4K deducts 20 credits, and all other sizes deduct 10 credits. If the task later fails, the credits are refunded automatically.

For credit rules, see credits-deduction.md.

Endpoints

1. Create Task

Create a new image enhancement task.

Endpoint

POST /api/v1/photoEnhancer/generate

Request Body

FieldTypeRequiredDescription
presetIdstringNoOptional preset request value. Choose one from Preset Reference.
imageUrlstring | array<string>YesImage input. Supports a single URL string, or a URL array such as ["https://a.jpg", "https://b.jpg"].
promptstringNoOptional custom prompt text.
imageSizestringNoOptional output size. Supported values: 512, 1K, 2K, 4K. If omitted for API calls, the server defaults to 4K.

imageUrl Format

Single image:

{
  "imageUrl": "https://example.com/room.jpg"
}

Multiple images:

{
  "imageUrl": [
    "https://example.com/room_1.jpg",
    "https://example.com/room_2.jpg"
  ]
}

Behavior Notes

  • imageUrl is the only request image field for this API.
  • presetId may be omitted.
  • prompt may be omitted.
  • presetId and prompt cannot both be empty. At least one of them must be provided.
  • If imageUrl is a normal URL string, the task uses one image.
  • If imageUrl is an array, the server parses it into an internal image list.
  • hdr-merge-hdr-merge is the preset that is designed for multiple images.
  • Multiple images generally produce the best results only with hdr-merge-hdr-merge.
  • Other presetId values are not designed for multi-image generation. If you submit multiple images with them, the generated result may not be good. Single-image input is recommended.

Request Examples

cURL

# Single image example
curl -X POST "https://api.ideal.house/api/v1/photoEnhancer/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/exterior.jpg",
    "presetId": "virtual-twilight-warm-sunset-twilight",
    "imageSize": "4K"
  }'

# HDR Merge example - multi-image input
curl -X POST "https://api.ideal.house/api/v1/photoEnhancer/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": [
      "https://example.com/interior_under.jpg",
      "https://example.com/interior_mid.jpg",
      "https://example.com/interior_over.jpg"
    ],
    "presetId": "hdr-merge-hdr-merge",
    "imageSize": "4K"
  }'

# Prompt-only example
curl -X POST "https://api.ideal.house/api/v1/photoEnhancer/generate" \
  -H "APIKEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://example.com/interior.jpg",
    "prompt": "Brighten the room, keep the lighting natural, and make the image listing-ready.",
    "imageSize": "4K"
  }'

Java (OkHttp)

import okhttp3.*;
import java.io.IOException;

public class PhotoEnhancerApiExample {

    private static final String BASE_URL = "https://api.ideal.house";
    private static final String API_KEY  = "your_api_key_here";

    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();

        // Single image example
        String requestBody = """
            {
                "imageUrl": "https://example.com/exterior.jpg",
                "presetId": "virtual-twilight-warm-sunset-twilight",
                "imageSize": "4K"
            }
            """;

        // HDR Merge example - multi-image input
        // String requestBody = """
        //     {
        //         "imageUrl": [
        //             "https://example.com/interior_under.jpg",
        //             "https://example.com/interior_mid.jpg",
        //             "https://example.com/interior_over.jpg"
        //         ],
        //         "presetId": "hdr-merge-hdr-merge",
        //         "imageSize": "4K"
        //     }
        //     """;

        // Prompt-only example
        // String requestBody = """
        //     {
        //         "imageUrl": "https://example.com/interior.jpg",
        //         "prompt": "Brighten the room, keep the lighting natural, and make the image listing-ready.",
        //         "imageSize": "4K"
        //     }
        //     """;

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/photoEnhancer/generate")
            .addHeader("APIKEY", API_KEY)
            .addHeader("Content-Type", "application/json")
            .post(RequestBody.create(requestBody, MediaType.parse("application/json")))
            .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println("Response: " + response.body().string());
        }
    }
}

Python (requests)

import requests
BASE_URL = "https://api.ideal.house"
API_KEY  = "your_api_key_here"

headers = {
    "APIKEY": API_KEY,
    "Content-Type": "application/json"
}

# Single image example
payload = {
    "imageUrl": "https://example.com/interior.jpg",
    "presetId": "image-optimization-full-correction-suite",
    "prompt": "Keep the result natural and listing-ready."
}

# HDR Merge example - multi-image input
# payload = {
#     "imageUrl": [
#         "https://example.com/interior_under.jpg",
#         "https://example.com/interior_mid.jpg",
#         "https://example.com/interior_over.jpg"
#     ],
#     "presetId": "hdr-merge-hdr-merge",
#     "imageSize": "4K"
# }

# Prompt-only example
# payload = {
#     "imageUrl": "https://example.com/interior.jpg",
#     "prompt": "Brighten the room, keep the lighting natural, and make the image listing-ready.",
#     "imageSize": "4K"
# }

response = requests.post(
    f"{BASE_URL}/api/v1/photoEnhancer/generate",
    headers=headers,
    json=payload
)

data = response.json()
task_id = data.get("data")
print(f"Task ID: {task_id}")

Node.js (axios)

const axios = require('axios');

const BASE_URL = 'https://api.ideal.house';
const API_KEY  = 'your_api_key_here';

async function createPhotoEnhancerTask() {
  try {
    const response = await axios.post(
      `${BASE_URL}/api/v1/photoEnhancer/generate`,
      {
        imageUrl: 'https://example.com/interior.jpg',
        presetId: 'image-quality-correction-ai-photo-sharpening',
        imageSize: '4K'

        // HDR Merge example - multi-image input:
        // imageUrl: [
        //   'https://example.com/interior_under.jpg',
        //   'https://example.com/interior_mid.jpg',
        //   'https://example.com/interior_over.jpg'
        // ],
        // presetId: 'hdr-merge-hdr-merge',
        // imageSize: '4K'

        // Prompt-only example:
        // imageUrl: 'https://example.com/interior.jpg',
        // prompt: 'Brighten the room, keep the lighting natural, and make the image listing-ready.',
        // imageSize: '4K'
      },
      {
        headers: {
          'APIKEY': API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('Task ID:', response.data.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

createPhotoEnhancerTask();

Success Response

{
  "code": 0,
  "message": "success",
  "data": 1234567890123456789
}
FieldTypeDescription
codeinteger0 means success
messagestringResponse message
datalongGenerated task id

2. Get Task Result

Get the current task status and output.

Endpoint

GET /api/v1/photoEnhancer/result

Query Parameters

ParameterTypeRequiredDescription
taskIdlongYesTask id returned by the generate endpoint

Request Examples

cURL

curl -X GET "https://api.ideal.house/api/v1/photoEnhancer/result?taskId=1234567890123456789" \
  -H "APIKEY: your_api_key_here"

Java (OkHttp)

import okhttp3.*;
import java.io.IOException;

public class PhotoEnhancerResultExample {

    private static final String BASE_URL = "https://api.ideal.house";
    private static final String API_KEY  = "your_api_key_here";

    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();
        long taskId = 1234567890123456789L;

        Request request = new Request.Builder()
            .url(BASE_URL + "/api/v1/photoEnhancer/result?taskId=" + taskId)
            .addHeader("APIKEY", API_KEY)
            .get()
            .build();

        try (Response response = client.newCall(request).execute()) {
            System.out.println("Response: " + response.body().string());
        }
    }
}

Python (requests)

import requests
import time

BASE_URL = "https://api.ideal.house"
API_KEY  = "your_api_key_here"

headers = {
    "APIKEY": API_KEY
}

task_id = 1234567890123456789

while True:
    response = requests.get(
        f"{BASE_URL}/api/v1/photoEnhancer/result",
        headers=headers,
        params={"taskId": task_id}
    )

    data = response.json()
    result = data.get("data", {})
    status = result.get("status")

    print(f"Status: {status}, Progress: {result.get('percentage')}%, Queue: {result.get('waitNumber')}")

    if status in ("Success", "Failed"):
        break

    time.sleep(3)

if status == "Success":
    print("Result URL:", result["output"]["resultUrl"])
else:
    print("Task failed")

Node.js (axios)

const axios = require('axios');

const BASE_URL = 'https://api.ideal.house';
const API_KEY  = 'your_api_key_here';

async function pollResult(taskId) {
  const headers = { 'APIKEY': API_KEY };

  while (true) {
    const response = await axios.get(
      `${BASE_URL}/api/v1/photoEnhancer/result`,
      {
        headers,
        params: { taskId }
      }
    );

    const result = response.data.data;
    const { status, percentage, waitNumber } = result;

    console.log(`Status: ${status} | Progress: ${percentage}% | Queue: ${waitNumber}`);

    if (['Success', 'Failed'].includes(status)) {
      if (status === 'Success') {
        console.log('Result URL:', result.output.resultUrl);
        console.log('Size:', result.output.width, 'x', result.output.height);
      } else {
        console.log('Task failed');
      }
      break;
    }

    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

pollResult(1234567890123456789n);

Response Example

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1234567890123456789,
    "status": "Success",
    "waitNumber": 0,
    "percentage": 100,
    "input": {
      "imageUrl": [
        "https://example.com/interior_under.jpg",
        "https://example.com/interior_mid.jpg",
        "https://example.com/interior_over.jpg"
      ],
      "imageUrls": [
        "https://example.com/interior_under.jpg",
        "https://example.com/interior_mid.jpg",
        "https://example.com/interior_over.jpg"
      ],
      "prompt": "Keep the result natural and listing-ready.",
      "presetId": "hdr-merge-hdr-merge",
      "imageSize": "4K",
      "isApiCall": true,
      "modelType": "Pro",
      "model": "NanoBanana"
    },
    "output": {
      "resultUrl": "https://cdn.ideal.house/output/photo_enhancer_result.jpg",
      "width": 3840,
      "height": 2880
    }
  }
}

Response Fields

FieldTypeDescription
idlongTask unique identifier
statusstringCurrent task status
waitNumberintegerNumber of tasks ahead in queue
percentageintegerTask progress from 0 to 100
inputobjectOriginal request data stored with the task
input.imageUrlstring | array<string>Original request value sent by the client
input.imageUrlsarray<string>Server-normalized internal image list
input.promptstringOptional custom prompt text
input.presetIdstring | nullOptional preset request value
input.imageSizestringRequested image size. Supported values: 512, 1K, 2K, 4K
outputobject | nullOutput object when the task succeeds
output.resultUrlstringFinal image URL
output.widthintegerOutput width in pixels
output.heightintegerOutput height in pixels

Task Status

StatusDescription
UnprocessedTask has been created but has not started yet
ProcessingTask is currently running
SuccessTask finished successfully
FailedTask failed

Polling recommendation: poll every 3 to 5 seconds.

Preset Reference

Summary:

  • Public categories: 11
  • Public presets from config: 136
  • Extra API preset: 1
  • Total documented request values: 137
  • Request field: presetId

Extra API Preset

Preset Name (EN)Request Value (presetId)Notes
HDR Mergehdr-merge-hdr-mergeRecommended for multi-image input such as bracketed exposure merging

Image Optimization (image-optimization)

Preset Name (EN)Request Value (presetId)
Full Correction Suiteimage-optimization-full-correction-suite
Real Estate Photo Editingimage-optimization-real-estate-photo-editing
MLS Photo Enhancementimage-optimization-mls-photo-enhancement
Single Exposure Editingimage-optimization-single-exposure-editing
Social Media Photo Optimizationimage-optimization-social-media-photo-optimization
Glare and Reflection Reductionimage-optimization-glare-and-reflection-reduction
Exposure Balancingimage-optimization-exposure-balancing

Image Quality & Correction (image-quality-correction)

Preset Name (EN)Request Value (presetId)
360 VR Enhanced Tourimage-quality-correction-360-vr-enhanced-tour
AI Photo Sharpeningimage-quality-correction-ai-photo-sharpening
Real Estate Photo Editingimage-quality-correction-real-estate-photo-editing
Compression Artifact Fiximage-quality-correction-compression-artifact-fix
Lens Distortion Correctionimage-quality-correction-lens-distortion-correction
Image Upscalingimage-quality-correction-image-upscaling
Noise Reductionimage-quality-correction-noise-reduction
Perspective Correctionimage-quality-correction-perspective-correction
Auto Crop & Straightenimage-quality-correction-auto-crop-straighten
Chromatic Aberration Fiximage-quality-correction-chromatic-aberration-fix
Vignette Removalimage-quality-correction-vignette-removal
MLS Photo Resizeimage-quality-correction-mls-photo-resize

Exterior Enhancement (exterior-enhancement)

Preset Name (EN)Request Value (presetId)
Drone & Aerialexterior-enhancement-drone-aerial
Drivewayexterior-enhancement-driveway
Curb Appealexterior-enhancement-curb-appeal
Exterior Colorexterior-enhancement-exterior-color
Exterior Photoexterior-enhancement-exterior-photo
Lawn & Yardexterior-enhancement-lawn-yard
Poolexterior-enhancement-pool
Fence & Gateexterior-enhancement-fence-gate
Landscapingexterior-enhancement-landscaping
Roofexterior-enhancement-roof

Interior Enhancement (interior-enhancement)

Preset Name (EN)Request Value (presetId)
Window Pullinterior-enhancement-window-pull
Occupied to Vacantinterior-enhancement-occupied-to-vacant
Enhance Hardwood Floors Photointerior-enhancement-enhance-hardwood-floors-photo
Interior Photointerior-enhancement-interior-photo
Flash Ambient Blending Real Estateinterior-enhancement-flash-ambient-blending-real-estate
Ceiling Light & Hot Spot Fixinterior-enhancement-ceiling-light-hot-spot-fix

Lighting, Color & Exposure (lighting-color-exposure)

Preset Name (EN)Request Value (presetId)
Balance Highlight Shadow Real Estatelighting-color-exposure-balance-highlight-shadow-real-estate
Brighten Dark Interior Photolighting-color-exposure-brighten-dark-interior-photo
Brighten Dark Real Estate Photolighting-color-exposure-brighten-dark-real-estate-photo
Brightness Enhancerlighting-color-exposure-brightness-enhancer
Cozy Warm Interior Editinglighting-color-exposure-cozy-warm-interior-editing
Enhance Brightness Of Photolighting-color-exposure-enhance-brightness-of-photo
Enhance Natural Light Interiorlighting-color-exposure-enhance-natural-light-interior
Exposure Balancinglighting-color-exposure-exposure-balancing
Mixed Lighting Fixlighting-color-exposure-mixed-lighting-fix
Flat Photo Contrast Fixlighting-color-exposure-flat-photo-contrast-fix
Fluorescent Light Color Fixlighting-color-exposure-fluorescent-light-color-fix
How To Brighten Dark Photoslighting-color-exposure-how-to-brighten-dark-photos
Contrast Enhancementlighting-color-exposure-contrast-enhancement
Increase Brightness Listing Photolighting-color-exposure-increase-brightness-listing-photo
Interior Exposure Balancinglighting-color-exposure-interior-exposure-balancing
Lift Dark Shadows Real Estatelighting-color-exposure-lift-dark-shadows-real-estate
Overexposed Window Fixlighting-color-exposure-overexposed-window-fix
Color Correctionlighting-color-exposure-color-correction
Highlight Recoverylighting-color-exposure-highlight-recovery
Shadow Recoverylighting-color-exposure-shadow-recovery
Reduce Highlights In My Image To Balance Exposurelighting-color-exposure-reduce-highlights-in-my-image-to-balance-exposure
Color Cast Removallighting-color-exposure-color-cast-removal
Tungsten Daylight Mix Correctionlighting-color-exposure-tungsten-daylight-mix-correction
Warm Tone Enhancementlighting-color-exposure-warm-tone-enhancement
Cool Tone Enhancementlighting-color-exposure-cool-tone-enhancement
White Balance Fix Interior Photolighting-color-exposure-white-balance-fix-interior-photo
Turn On Lightslighting-color-exposure-turn-on-lights
Vibrance & Saturation Boostlighting-color-exposure-vibrance-saturation-boost
Natural Light Enhancementlighting-color-exposure-natural-light-enhancement

Sky Replacement (sky-replacement)

Preset Name (EN)Request Value (presetId)
Blue Sky / Clear Skysky-replacement-blue-sky-clear-sky
Sunrise Skysky-replacement-sunrise-sky
Cloudy Skysky-replacement-cloudy-sky
Partly Cloudysky-replacement-partly-cloudy
Dramatic Cloudssky-replacement-dramatic-clouds
Sunset Skysky-replacement-sunset-sky
Soft Sunsetsky-replacement-soft-sunset
Dramatic Sunsetsky-replacement-dramatic-sunset
Luxury Sunset Tonessky-replacement-luxury-sunset-tones
Fix Gray Sky Real Estatesky-replacement-fix-gray-sky-real-estate
Golden Hour Skysky-replacement-golden-hour-sky
Night Sky / Starry Skysky-replacement-night-sky-starry-sky
Sky Replacementsky-replacement-sky-replacement

Virtual Twilight (virtual-twilight)

Preset Name (EN)Request Value (presetId)
Bright Marketing Twilightvirtual-twilight-bright-marketing-twilight
Day To Dusk Photo Conversionvirtual-twilight-day-to-dusk-photo-conversion
Deep Blue Twilightvirtual-twilight-deep-blue-twilight
Light Subtle Twilightvirtual-twilight-light-subtle-twilight
Luxury Twilightvirtual-twilight-luxury-twilight
Midnight Blue Twilightvirtual-twilight-midnight-blue-twilight
Warm Sunset Twilightvirtual-twilight-warm-sunset-twilight

Weather & Seasonal Editing (weather-seasonal-editing)

Preset Name (EN)Request Value (presetId)
Golden Hourweather-seasonal-editing-golden-hour
Blue Hourweather-seasonal-editing-blue-hour
Haze & Fog Removalweather-seasonal-editing-haze-fog-removal
Harsh Sunlight & Shadow Fixweather-seasonal-editing-harsh-sunlight-shadow-fix
Overcast To Sunnyweather-seasonal-editing-overcast-to-sunny
Rain & Wet Weather Fixweather-seasonal-editing-rain-wet-weather-fix
Spring Enhancementweather-seasonal-editing-spring-enhancement
Summer Enhancementweather-seasonal-editing-summer-enhancement
Night to Dayweather-seasonal-editing-night-to-day
Fall Foliageweather-seasonal-editing-fall-foliage
Snow / Winter Conditionsweather-seasonal-editing-snow-winter-conditions
Full Season Change / Season Swapweather-seasonal-editing-full-season-change-season-swap
Snow Removalweather-seasonal-editing-snow-removal

Holiday Decorations (holiday-decorations)

Preset Name (EN)Request Value (presetId)
Christmas Exteriorholiday-decorations-christmas-exterior
Christmas Interiorholiday-decorations-christmas-interior
Easter Exteriorholiday-decorations-easter-exterior
Easter Interiorholiday-decorations-easter-interior
Halloween Exteriorholiday-decorations-halloween-exterior
Halloween Interiorholiday-decorations-halloween-interior
New Year Exteriorholiday-decorations-new-year-exterior
New Year Interiorholiday-decorations-new-year-interior
Thanksgiving Dining Roomholiday-decorations-thanksgiving-dining-room
Thanksgiving Exteriorholiday-decorations-thanksgiving-exterior
Thanksgiving Interiorholiday-decorations-thanksgiving-interior
Fourth of July / Independence Dayholiday-decorations-fourth-of-july-independence-day
Hanukkah Interiorholiday-decorations-hanukkah-interior
Spring / Ramadan Decorationsholiday-decorations-spring-ramadan-decorations
Valentine's Day Bedroomholiday-decorations-valentine-s-day-bedroom
Valentine's Day Exteriorholiday-decorations-valentine-s-day-exterior
Valentine's Day Interiorholiday-decorations-valentine-s-day-interior

Fire in Fireplace (fire-in-fireplace)

Preset Name (EN)Request Value (presetId)
Add Fire To Fireplacefire-in-fireplace-add-fire-to-fireplace
Bright Marketing Firefire-in-fireplace-bright-marketing-fire
Modern Clean Firefire-in-fireplace-modern-clean-fire
Subtle Natural Firefire-in-fireplace-subtle-natural-fire
Traditional Cozy Firefire-in-fireplace-traditional-cozy-fire
Vibrant Showcase Firefire-in-fireplace-vibrant-showcase-fire

Object & Element Specific (object-element-specific)

Preset Name (EN)Request Value (presetId)
Crack & Wall Repairobject-element-specific-crack-wall-repair
Floor Reflection Real Estateobject-element-specific-floor-reflection-real-estate
People & Pet Removalobject-element-specific-people-pet-removal
Trash Can Removalobject-element-specific-trash-can-removal
Remove Carsobject-element-specific-remove-cars
Clutter Removalobject-element-specific-clutter-removal
Date Stamp Removalobject-element-specific-date-stamp-removal
Sign Removalobject-element-specific-sign-removal
Glare Removalobject-element-specific-glare-removal
Mirror Reflection Fixobject-element-specific-mirror-reflection-fix
Remove Power Linesobject-element-specific-remove-power-lines
Stain Removalobject-element-specific-stain-removal
Watermark Removalobject-element-specific-watermark-removal
Window Reflection Removalobject-element-specific-window-reflection-removal
TV Screen Fixobject-element-specific-tv-screen-fix
Wire & Cable Removalobject-element-specific-wire-cable-removal

Error Responses

All errors use this structure:

{
  "code": 5002,
  "message": "Invalid API Key",
  "data": null
}
CodeNameDescription
1001FAILEDGeneric request failure
1003INTERNAL_ERRORInternal server error
1011PARAM_ERRORMissing or invalid request parameter
5002API_KEY_INVALIDInvalid or missing API key
9010SCAN_TEXT_ERRORPrompt text failed review
9038PROHIBITED_CONTENTGenerated image content was rejected
9051COINS_NOT_ENOUGHInsufficient credits

For the full common error list, see error-codes.md.

1. POST /api/v1/photoEnhancer/generate
   -> receive taskId

2. Wait 3 to 5 seconds

3. GET /api/v1/photoEnhancer/result?taskId={taskId}
   -> inspect status

4. If status is Success
   -> read output.resultUrl

5. If status is Unprocessed or Processing
   -> continue polling

© Ideal House AI — All rights reserved.

Object Remover APIVirtual Staging API