Stager AI API v1Developer Reference

Automate Your Real Estate
Photo Editing Workflow

Link your proprietary CRM, database, or photography platform directly into Stager AI. Our API handles heavy lifting like multi-exposure HDR blending, lens fixes, perspective straightening, and smart AI staging enhancements.

Section 1: Setup & Core Utility

Authentication

Need an API Key?

Base URLhttps://api.stagerai.com

API access is open to business accounts and high-volume platforms. To get your production key, shoot us a quick message via the live chat. Every request requires the stager-api-key header.

Section 2: HDR Multi-Bracket Merge Engine

Capabilities

Automatic Structural Modifications

When running raw exposure brackets through our automated multi-bracket rendering pipeline, our processing clusters handle the following fixes natively:

  • HDR Multi-Bracket Blending: Combines up to 7 exposures into a single vibrant image.
  • Lens & Fish-Eye Correction: Unwraps perspective distortions from wide-angle glass optics.
  • Perspective Straightening: Enforces perfect vertical architectural structural balances.
  • Window Pulls: Isolates clipping levels in window highlights to balance exterior illumination values.

1. Create a Project

Every upload cluster must belong to an administrative asset folder wrapper.

POST/api/projects
/ Required Headersstager-api-key: your_api_key_here
/ Request Body (JSON)
{
  "title": "123 Main Street Suite"
}
/ Response JSON
{
  "id": "project_uuid_here",
  "title": "123 Main Street Suite"
}

2. Create an HDR Image Group

Instantiates context wrappers and chooses custom core pipeline behaviors.

POST/api/hdr-image-group
/ Required Headersstager-api-key: your_api_key_here
/ Request Body (JSON)
{
  "projectId": "project_uuid_here",
  "lensCorrection": true,
  "perspectiveCorrection": true,
  "photographerRemoval": true
}
/ Response JSON
{
  "groupId": "group_uuid_here"
}

3. Get a Signed Upload URL

Generates explicit signed access paths per bracket asset. Max 7 photos per group structure.

POST/api/hdr-upload-url
/ Required Headersstager-api-key: your_api_key_here
/ Request Body (JSON)
{
  "projectId": "project_uuid_here",
  "groupId": "group_uuid_here",
  "filename": "living_room_bright.jpg"
}
/ Response JSON
{
  "id": "image_uuid_here",
  "uploadUrl": "https://storage.googleapis.com/...temporary_gcloud_put_url..."
}

4. Process and Merge the Group

Triggers backend async operations to blend exposure frames together.

POST/api/hdr-enhance
/ Required Headersstager-api-key: your_api_key_here
/ Request Body (JSON)
{
  "projectId": "project_uuid_here",
  "groupId": "group_uuid_here"
}
/ Response JSON
{}

5. Check Status & Get the Final Image

Poll endpoint to review completion metrics and capture downloadable URL artifacts.

GET/api/hdr-image-group/:groupId
/ Required Headersstager-api-key: your_api_key_here
/ Response JSON
// If processing:
{
  "status": "processing"
}

// On Complete:
{
  "status": "completed",
  "imageUrl": "https://storage.googleapis.com/stager-final-results/output.jpg"
}

Section 3: AI Staging & Environment Replacement

1. Upload Target Image Asset

Prerequisite step: Upload your base scene photo file as multi-part form data. The returned id (e.g. imageId) is required to trigger all subsequent staging or replacement features.

POST/api/image
/ Required Headersstager-api-key: your_api_key_here
/ Request Body (JSON)
// Multi-part Form Data Form\nFile: binary_image_payload.jpg / .png
/ Response JSON
{
  "success": true,
  "data": {
    "id": "img_71283912739",
    "imageUrl": "https://storage.googleapis.com/stager-resized/cache_file.jpg",
    "width": 1920,
    "height": 1280
  }
}

2. Auto Virtual Staging

Populates empty rooms with interior decor arrangements matched against specific architectural styles and functional footprints.

POST/api/images/:imageId/stage
/ Required Headersstager-api-key: your_api_key_here
/ Request Body (JSON)
{
  "roomType": "LIVING_ROOM", 
  "roomStyle": "modern", 
  "actionType": "subtleStaging", 
  "resolution": "high", 
  "colorTypes": ["classicWhite", "naturalWood"],
  "removeFurniture": false,
  "extraInstructions": "Add a luxury linen sofa assembly"
}
/ Response JSON
{
  "success": true,
  "data": [
    {
      "id": "res_9823192",
      "imageUrl": "https://storage.googleapis.com/.../staged_output.png",
      "width": 1920,
      "height": 1280
    }
  ]
}
Allowed Configuration Parameters:
actionType values: subtleStaging, autoStaging
resolution values: low, high, superHigh
roomType values: LIVING_ROOM, DINING_ROOM, BEDROOM, KITCHEN, KITCHEN_LIVING_AREA, HOME_OFFICE, TERRACE, BALCONY, BATHROOM, EXTERIOR, GAME_ROOM, KIDS_ROOM, GARAGE
roomStyle values: modern, minimalist, scandinavian, industrial, rustic, farmhouse, kidsRoom, coastalModern, luxury, midCentury, bohoChic, japandi
colorTypes values: classicWhite, charcoalGray, matteBlack, beige, espressoBrown, walnut, naturalWood, navyBlue, forestGreen, rusticOak, ivory, steelBlue, ashGray, mahogany

3. Automated Lawn Replacement

Identifies patchy yard structures, weeds, and dirt paths, swapping them out with pristine, freshly cut grass turf extensions.

POST/api/images/:imageId/lawn-replace
/ Required Headersstager-api-key: your_api_key_here
/ Request Body (JSON)
{
  "lawnType": "medium",
  "resolution": "high", 
  "extraInstructions": "Keep the stone pathway intact"
}
/ Response JSON
{
  "success": true,
  "data": [
    {
      "id": "res_8812301",
      "imageUrl": "https://storage.googleapis.com/.../lawn_output.png",
      "width": 1920,
      "height": 1280
    }
  ]
}
Allowed lawnType configurations: light | medium | strong
Resolution values: low, high, superHigh

4. Automated Sky Replacement

Overlays gray or overexposed weather horizons with deep blue skies or stunning twilight backdrops while dynamically adjusting building facade shadows.

POST/api/images/:imageId/sky-replace
/ Required Headersstager-api-key: your_api_key_here
/ Request Body (JSON)
{
  "skyType": "twilight",
  "resolution": "high", 
  "skySubType": "dramatic"
}
/ Response JSON
{
  "success": true,
  "data": [
    {
      "id": "res_1102931",
      "imageUrl": "https://storage.googleapis.com/.../sky_output.png",
      "width": 1920,
      "height": 1280
    }
  ]
}
resolution values: low, high, superHigh
skyType variations: blue (processed via Flux pipelines), twilight (processed via lightning fast rendering systems)
skySubType variations: subtle | middle | dramatic