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.

Pricing & Credit System

Active subscription required. To use the Stager AI API, you must maintain an active subscription on your account.

You can purchase any subscription plan that fits your needs. We automatically adjust your API credit quota to match the standard rate of 0.25¢ per photo across all features. This ensures consistent pricing whether you're using the web app or API.

Bonus: Unused monthly credits roll over to the next month, so you can accumulate credits for larger projects or seasonal workloads.

All API operations consume credits from your account. Credits are deducted when processing completes successfully.

HDR Multi-Bracket Merge0.25¢ per final photo

How it works: A bracket group of up to 7 exposure photos counts as 1 final photo for billing purposes. For example, if you upload 5 bracket photos and merge them into 1 final HDR image, you are charged 0.25¢ for that single output.

Example: Processing 10 bracket groups (50 total input photos) results in 10 final merged images = 2.50¢ total cost

AI Staging & Retouching0.25¢ per photo

Applies to virtual staging, lawn replacement, sky replacement, and retouch operations.

Included: First 3 re-renders per photo at no additional cost

Additional renders: Every 3rd render after the initial 3 consumes 1 credit (0.25¢). For example: renders 4, 7, 10, 13, etc. cost 1 credit each

Example: Virtual stage a photo (0.25¢) → re-renders 2, 3, 5, 6 (included) → re-render 4 (0.25¢) → re-render 7 (0.25¢) = 0.75¢ total for 7 renders

Video Generation6 credits per scene

Each scene in your video animation consumes 6 credits.

Scene duration: Each scene lasts 10-15 seconds of animation

Photos per scene: 1 to 5 images (order determines animation sequence)

Example: Creating a video with 4 scenes (e.g., living room, kitchen, bedroom, exterior) = 4 × 6 = 24 credits total. Final video duration: ~50 seconds

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

Single & Multi-Bracket Processing

Process both single images and multi-bracket exposure series through our automated HDR rendering pipeline. Upload anywhere from 1 to 7 exposures per bracket group.

Automatic Structural Modifications

Our processing clusters natively handle the following fixes:

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.

Supported File Formats

Supports all common real estate photography raw formats including Canon (CR3, CR2), Nikon (NEF, NRW), Sony (ARW, SRF), Fujifilm (RAF), Panasonic (RW2), and standard formats (JPEG, PNG, TIFF).

HDR Processing Pipeline

The HDR pipeline automatically processes your bracket series through detection, alignment, blending, and structural corrections to produce a vibrant, perfectly balanced final image.

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

Section 4: AI Video Generation

Capabilities

Automated Real Estate Video Creation

Transform property images into engaging marketing videos with multiple animation styles and effects. Perfect for creating virtual tours, before-and-after comparisons, and dynamic listings.

Floor Plan Rotating Effect: Creates smooth 360° rotations with zoom effects.
Listing Slow Motion: Elegant pan and zoom animations across property images.
Before & After Staging: Side-by-side comparisons of original vs. virtually staged images.
Before & After Renovation: Showcase property transformations and renovations.
Multiple Audio Options: Royalty-free background music library or custom uploads.

1. Upload Video Images

Prerequisite step: Upload property images as multi-part form data. The returned id (image ID) is required when creating video clips and adding frames to your animations.

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

Note: Save the returned id to use when creating video clips. You can upload multiple images and use them in different video projects or multiple times within the same project.

2. Get Audio Library

Retrieves available background music tracks including built-in royalty-free options and user-uploaded custom audio.

GET/api/audio

/ Required Headersstager-api-key: your_api_key_here

/ Response JSON

{
  "data": {
    "items": [
      {
        "id": "audio_001",
        "name": "Corporate Inspirational",
        "url": "https://storage.googleapis.com/.../audio.mp3",
        "isCustom": false
      },
      {
        "id": "custom_audio_123",
        "name": "My Custom Soundtrack",
        "url": "https://storage.googleapis.com/.../custom.mp3",
        "isCustom": true
      }
    ]
  }
}

3. Create Video Project

Initializes a new video project with specified orientation, animation style, and optional background audio.

POST/api/videos

/ Required Headersstager-api-key: your_api_key_here

/ Request Body (JSON)

{
  "title": "Luxury Home Tour - 123 Main St",
  "orientation": "horizontal",
  "videoType": "listingSlowMotion",
  "audioId": "audio_001"
}

/ Response JSON

{
  "data": {
    "id": "video_abc123xyz",
    "title": "Luxury Home Tour - 123 Main St",
    "orientation": "horizontal",
    "videoType": "listingSlowMotion",
    "clips": []
  }
}

orientation values: horizontal, vertical

videoType values: listingSlowMotion, beforeAndAfterStaging, beforeAndAfterStagingRenovation, floorPlanRotatingEffect

audioId: Optional. Use ID from audio library endpoint. If omitted, template default will be used.

5. Get Video Details

Retrieves complete video project details including all clips, images, and rendering status.

GET/api/videos/:videoId

/ Required Headersstager-api-key: your_api_key_here

/ Response JSON

{
  "data": {
    "id": "video_abc123xyz",
    "title": "Luxury Home Tour - 123 Main St",
    "videoUrl": "https://storage.googleapis.com/.../final_video.mp4",
    "clips": [
      {
        "id": "clip_001",
        "order": 0,
        "videoUrl": "https://storage.googleapis.com/.../clip_001.mp4",
        "images": [
          {
            "id": "img_123",
            "imageId": "img_uuid",
            "url": "https://storage.googleapis.com/.../thumbnail.jpg",
            "isGeneration": false
          }
        ]
      }
    ]
  }
}

6. Create Video Clip

Adds a new clip (sequence of images) to an existing video project. Each image is a frame in the animation.

POST/api/videos/:videoId/clips

/ Required Headersstager-api-key: your_api_key_here

/ Request Body (JSON)

{
  "images": [
    { "id": "img_123", "order": 0 },
    { "id": "img_124", "order": 1 },
    { "id": "img_125", "order": 2 }
  ],
  "customInstructions": "Add smooth transitions between rooms"
}

/ Response JSON

{
  "data": {
    "id": "clip_001"
  }
}

Note: Image IDs must be previously uploaded to your project. Order determines frame sequence in the animation.

7. Render Video

Initiates background processing to generate the final video file from all clips and images. Processing is async; use the progress endpoint to monitor status.

POST/api/videos/:videoId/render

/ Required Headersstager-api-key: your_api_key_here

/ Request Body (JSON)

{}

/ Response JSON

{
  "data": {}
}

Note: Rendering happens asynchronously. Poll the progress endpoint to track completion. Typical render time: 5-30 minutes depending on video length and complexity.

8. Check Video Progress

Polls rendering status and retrieves progress metrics, video URL, and file size for completed renders.

GET/api/videos/:videoId/progress

/ Required Headersstager-api-key: your_api_key_here

/ Response JSON

// While processing:
{
  "status": "progress",
  "progress": 45
}

// When complete:
{
  "status": "done",
  "url": "https://storage.googleapis.com/.../final_video.mp4",
  "size": 125000000
}

// On error:
{
  "status": "error",
  "message": "Render failed: insufficient memory"
}

Recommendation: Poll this endpoint every 5-10 seconds to track rendering progress. Returns one of three states: "progress" (with percentage), "done" (with video URL and file size), or "error" (with error message).

9. Edit Clip

Updates an existing clip's images, order, or custom instructions. Changes automatically reset render status requiring a new render call.

PUT/api/videos/:videoId/clips/:clipId

/ Required Headersstager-api-key: your_api_key_here

/ Request Body (JSON)

{
  "images": [
    { "id": "img_123", "order": 0 },
    { "id": "img_126", "order": 1 }
  ],
  "customInstructions": "Updated smooth transitions"
}

/ Response JSON

{
  "data": {
    "success": true
  }
}

10. Delete Clip

Removes a clip from the video project. Video will need re-rendering after deletion.

DELETE/api/videos/:videoId/clips/:clipId

/ Required Headersstager-api-key: your_api_key_here

/ Response JSON

{
  "data": {
    "success": true
  }
}

Video Generation Pipeline

The video pipeline transforms your image sequences into polished marketing videos. Each scene (1-5 images) generates a 10-15 second video segment with smooth animations, synchronized audio, and professional effects.

Automate Your Real Estate Photo Editing Workflow

Pricing & Credit System

Section 1: Setup & Core Utility

Need an API Key?

Section 2: HDR Multi-Bracket Merge Engine

Single & Multi-Bracket Processing

Automatic Structural Modifications

Supported File Formats

HDR Processing Pipeline

1. Create a Project

2. Create an HDR Image Group

3. Get a Signed Upload URL

4. Process and Merge the Group

5. Check Status & Get the Final Image

Section 3: AI Staging & Environment Replacement

1. Upload Target Image Asset

2. Auto Virtual Staging

3. Automated Lawn Replacement

4. Automated Sky Replacement

Section 4: AI Video Generation

Automated Real Estate Video Creation

1. Upload Video Images

2. Get Audio Library

3. Create Video Project

4. List Video Projects

5. Get Video Details

6. Create Video Clip

7. Render Video

8. Check Video Progress

9. Edit Clip

10. Delete Clip

Video Generation Pipeline

Automate Your Real Estate
Photo Editing Workflow