🔌Endpoints

The v2 API is available at the base URL https://api.virtualstagingai.app/v2.

The same API key can be used for both the v1 and v2 API. You can find or generate your API key in the Settings section of your Virtual Staging AI account.

Authenticate all requests by including an Authorization Header with the value (case sensitive):

Authorization: Api-Key {your_api_key_here}

Check API status

get

https://api.virtualstagingai.app/v2https://us-central1-furniture-ai.cloudfunctions.net/apiV2

/status

Returns 200 OK if the API is running

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication. Use the format: Api-Key ${key}.

Responses

200

API is operational

No content

get

/status

HTTPcURLJavaScriptPython

GET /v2/status HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Accept: */*

200

API is operational

No content

Get current user details

get

https://api.virtualstagingai.app/v2https://us-central1-furniture-ai.cloudfunctions.net/apiV2

/user

Returns information about the authenticated user including their usage limits

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication. Use the format: Api-Key ${key}.

Responses

200

Successful response

application/json

401

Authentication error.

application/json

500

Unexpected server error.

application/json

get

/user

HTTPcURLJavaScriptPython

GET /v2/user HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "user": {
    "email": "text",
    "uid": "text"
  },
  "photoLimit": {
    "staging": 1,
    "imageEditing": 1
  },
  "photosUsedThisPeriod": {
    "staging": 1,
    "imageEditing": 1
  }
}

Get all renders

get

https://api.virtualstagingai.app/v2https://us-central1-furniture-ai.cloudfunctions.net/apiV2

/renders

Returns all renders for the authenticated user

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication. Use the format: Api-Key ${key}.

Query parameters

limitinteger · min: 1 · max: 100OptionalDefault: 20

cursorstringOptional

Render ID to start after

orderstring · enumOptional

The order in which to display renders. Based on their creation date.

Default: descPossible values:

Responses

200

Successful response

application/json

total_countnumberOptional

The total number of completed variations for this render.

next_cursorstring · nullableOptional

The cursor to use to get the next page of renders.

401

Authentication error.

application/json

500

Unexpected server error.

application/json

get

/renders

HTTPcURLJavaScriptPython

GET /v2/renders HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "total_count": 1,
  "next_cursor": null,
  "items": [
    {
      "id": "text",
      "created_at": 1,
      "queued_at": null,
      "variations": {
        "total_count": 1,
        "next_cursor": null,
        "items": [
          {
            "id": "text",
            "type": "staging",
            "render_id": "text",
            "created_at": 1,
            "status": "queued",
            "result": {
              "url": "text",
              "optimized_url": null,
              "thumbnail_url": null
            },
            "base_variation_id": "text",
            "eta": null,
            "config": {
              "type": "legacy_staging",
              "room_type": "living",
              "style": "standard"
            }
          }
        ]
      },
      "eta": null
    }
  ]
}

Deprecated styles: Please note that the hamptons, american, and southwestern styles have been deprecated, and now are mapped to other existing styles. The API will continue to support their use, but they may be removed in future versions

Create a new render

post

https://api.virtualstagingai.app/v2https://us-central1-furniture-ai.cloudfunctions.net/apiV2

/renders

Create a new render with either a single configuration or multiple configurations.

Single Config Format: Use this for creating a single render with one configuration. Multi Config Format: Use this for creating a single render with multiple configurations. This can be used to generate variations with different room styles, furniture etc. without having to make a new request.

Examples

Single Config (Staging)

{
  "config": {
    "type": "staging",
    "add_furniture": {
      "room_type": "living",
      "style": "modern"
    }
  },
  "image_url": "https://example.com/image.jpg",
  "variation_count": 3,
  "wait_for_completion": false
}

Multi Config (Multiple Staging Variations)

{
  "configs": [
    {
      "type": "staging",
      "add_furniture": {
        "room_type": "living",
        "style": "modern"
      },
      "variation_count": 2
    },
    {
      "type": "staging",
      "add_furniture": {
        "room_type": "living",
        "style": "scandinavian"
      },
      "variation_count": 1
    }
  ],
  "image_url": "https://example.com/image.jpg",
  "wait_for_completion": true
}

Single Config (Day to Dusk)

{
  "config": {
    "type": "daytodusk",
    "sky_style": "golden"
  },
  "image_url": "https://example.com/image.jpg",
  "variation_count": 1
}

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication. Use the format: Api-Key ${key}.

Body

application/json

or

Responses

200

Render created successfully

application/json

idstringRequired

Unique identifier for this render.

created_atnumberRequired

Creation timestamp (epoch milliseconds).

queued_atnumber · nullableOptional

Timestamp when the render was queued for processing (epoch milliseconds).

etanumber · nullableRequired

Estimated time remaining for the first variation to complete (epoch milliseconds timestamp).

201

Render created and queued for processing

application/json

400

Validation error.

application/json

401

Authentication error.

application/json

403

Forbidden error.

application/json

500

Unexpected server error.

application/json

post

/renders

HTTPcURLJavaScriptPython

POST /v2/renders HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 334

{
  "config": {
    "type": "staging",
    "output_resolution": "default",
    "add_virtually_staged_watermark": null,
    "add_furniture": {
      "style": "standard",
      "room_type": "living"
    },
    "multi_view_staging": {
      "image_url": "text"
    },
    "remove_furniture": {
      "mode": "on",
      "mask_url": "text"
    }
  },
  "image_url": "text",
  "variation_count": 1,
  "webhook_url": null,
  "wait_for_completion": false
}

{
  "id": "text",
  "created_at": 1,
  "queued_at": null,
  "variations": {
    "total_count": 1,
    "next_cursor": null,
    "items": [
      {
        "id": "text",
        "type": "staging",
        "render_id": "text",
        "created_at": 1,
        "status": "queued",
        "result": {
          "url": "text",
          "optimized_url": null,
          "thumbnail_url": null
        },
        "base_variation_id": "text",
        "eta": null,
        "config": {
          "type": "legacy_staging",
          "room_type": "living",
          "style": "standard"
        }
      }
    ]
  },
  "eta": null
}

Get render details

get

https://api.virtualstagingai.app/v2https://us-central1-furniture-ai.cloudfunctions.net/apiV2

/renders/{render_id}

Returns details about a render including the status, variations, and result URL

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication. Use the format: Api-Key ${key}.

Path parameters

render_idstringRequired

The ID of the render to get details for

Query parameters

include_variationsbooleanOptionalDefault: false

variations_limitinteger · min: 1 · max: 100OptionalDefault: 20

variations_cursorstringOptional

Variation ID to start after

variations_orderstring · enumOptional

The order in which to display variations. Based on their creation date.

Default: ascPossible values:

Responses

200

Successful response

application/json

idstringRequired

Unique identifier for this render.

created_atnumberRequired

Creation timestamp (epoch milliseconds).

queued_atnumber · nullableOptional

Timestamp when the render was queued for processing (epoch milliseconds).

etanumber · nullableRequired

Estimated time remaining for the first variation to complete (epoch milliseconds timestamp).

401

Authentication error.

application/json

404

Validation error.

application/json

500

Unexpected server error.

application/json

get

/renders/{render_id}

HTTPcURLJavaScriptPython

GET /v2/renders/{render_id} HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "id": "text",
  "created_at": 1,
  "queued_at": null,
  "variations": {
    "total_count": 1,
    "next_cursor": null,
    "items": [
      {
        "id": "text",
        "type": "staging",
        "render_id": "text",
        "created_at": 1,
        "status": "queued",
        "result": {
          "url": "text",
          "optimized_url": null,
          "thumbnail_url": null
        },
        "base_variation_id": "text",
        "eta": null,
        "config": {
          "type": "legacy_staging",
          "room_type": "living",
          "style": "standard"
        }
      }
    ]
  },
  "eta": null
}

Get variation details

get

https://api.virtualstagingai.app/v2https://us-central1-furniture-ai.cloudfunctions.net/apiV2

/renders/{render_id}/variations/{variation_id}

Returns details about a variation including the status and result URL

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication. Use the format: Api-Key ${key}.

Path parameters

render_idstringRequired

The ID of the base render

variation_idstringRequired

The ID of the variation to get details for

Responses

200

Successful response

application/json

idstringRequired

Unique identifier for this variation.

typestring · enumOptional

Type of variation (staging, removal, etc.).

Possible values:

render_idstringRequired

ID of the parent render this variation belongs to.

created_atnumberRequired

Creation timestamp (epoch milliseconds).

statusstring · enumRequired

Current status of the variation.

Possible values:

resultone ofOptional

Result images (only present when status is 'done').

or

base_variation_idstringOptional

ID of the removal variation used as base, if this staging variation used a removal variation as its base.

etanumber · nullableRequired

Estimated time remaining for the variation to complete (epoch milliseconds timestamp).

configone ofOptional

Configuration used to generate this variation.

or

or

or

401

Authentication error.

application/json

404

Validation error.

application/json

500

Unexpected server error.

application/json

get

/renders/{render_id}/variations/{variation_id}

HTTPcURLJavaScriptPython

GET /v2/renders/{render_id}/variations/{variation_id} HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "id": "text",
  "type": "staging",
  "render_id": "text",
  "created_at": 1,
  "status": "queued",
  "result": {
    "url": "text",
    "optimized_url": null,
    "thumbnail_url": null
  },
  "base_variation_id": "text",
  "eta": null,
  "config": {
    "type": "legacy_staging",
    "room_type": "living",
    "style": "standard"
  }
}

Create new variations

post

https://api.virtualstagingai.app/v2https://us-central1-furniture-ai.cloudfunctions.net/apiV2

/renders/{render_id}/variations

Create one or more variations for an existing render. Status updates will be sent to the webhook_url specified in the render if one was provided.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication. Use the format: Api-Key ${key}.

Path parameters

render_idstringRequired

Body

application/json

configone ofRequired

or

or

variation_countinteger · min: 1Required

wait_for_completionboolean · nullableOptionalDefault: false

Responses

200

Variations created and completed successfully

application/json

201

Variations created and processing started

application/json

400

Validation error.

application/json

401

Authentication error.

application/json

403

Forbidden error.

application/json

404

Validation error.

application/json

500

Unexpected server error.

application/json

post

/renders/{render_id}/variations

HTTPcURLJavaScriptPython

POST /v2/renders/{render_id}/variations HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 281

{
  "config": {
    "type": "staging",
    "output_resolution": "default",
    "add_virtually_staged_watermark": null,
    "add_furniture": {
      "style": "standard",
      "room_type": "living",
      "base_variation_id": "text"
    },
    "remove_furniture": {
      "mode": "on",
      "mask_url": "text"
    }
  },
  "variation_count": 1,
  "wait_for_completion": false
}

{
  "variations": [
    {
      "id": "text",
      "type": "staging",
      "render_id": "text",
      "created_at": 1,
      "status": "queued",
      "result": {
        "url": "text",
        "optimized_url": null,
        "thumbnail_url": null
      },
      "base_variation_id": "text",
      "eta": null,
      "config": {
        "type": "legacy_staging",
        "room_type": "living",
        "style": "standard"
      }
    }
  ]
}

Create multiple renders in bulk

post

https://api.virtualstagingai.app/v2https://us-central1-furniture-ai.cloudfunctions.net/apiV2

/renders/bulk

Creates multiple renders with the specified parameters.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication. Use the format: Api-Key ${key}.

Body

application/json

webhook_urlstring · nullableOptional

wait_for_completionboolean · nullableOptionalDefault: false

Responses

200

Renders created and completed successfully

application/json

201

Renders created and queued for processing

application/json

400

Validation error.

application/json

401

Authentication error.

application/json

403

Forbidden error.

application/json

404

Validation error.

application/json

500

Unexpected server error.

application/json

post

/renders/bulk

HTTPcURLJavaScriptPython

POST /v2/renders/bulk HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 348

{
  "webhook_url": null,
  "wait_for_completion": false,
  "renders": [
    {
      "config": {
        "type": "staging",
        "output_resolution": "default",
        "add_virtually_staged_watermark": null,
        "add_furniture": {
          "style": "standard",
          "room_type": "living"
        },
        "multi_view_staging": {
          "image_url": "text"
        },
        "remove_furniture": {
          "mode": "on",
          "mask_url": "text"
        }
      },
      "image_url": "text",
      "variation_count": 1
    }
  ]
}

{
  "renders": [
    {
      "id": "text",
      "created_at": 1,
      "queued_at": null,
      "variations": {
        "total_count": 1,
        "next_cursor": null,
        "items": [
          {
            "id": "text",
            "type": "staging",
            "render_id": "text",
            "created_at": 1,
            "status": "queued",
            "result": {
              "url": "text",
              "optimized_url": null,
              "thumbnail_url": null
            },
            "base_variation_id": "text",
            "eta": null,
            "config": {
              "type": "legacy_staging",
              "room_type": "living",
              "style": "standard"
            }
          }
        ]
      },
      "eta": null
    }
  ]
}

Create multiple variations in bulk

post

https://api.virtualstagingai.app/v2https://us-central1-furniture-ai.cloudfunctions.net/apiV2

/renders/variations/bulk

Creates multiple variations for an existing render with different configurations.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication. Use the format: Api-Key ${key}.

Body

application/json

wait_for_completionboolean · nullableOptionalDefault: false

Responses

200

Variations for renders created and completed successfully

application/json

201

Variations for renders created and processing started

application/json

400

Validation error.

application/json

401

Authentication error.

application/json

403

Forbidden error.

application/json

404

Validation error.

application/json

500

Unexpected server error.

application/json

post

/renders/variations/bulk

HTTPcURLJavaScriptPython

POST /v2/renders/variations/bulk HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 314

{
  "wait_for_completion": false,
  "renders": [
    {
      "render_id": "text",
      "variation_count": 1,
      "config": {
        "type": "staging",
        "output_resolution": "default",
        "add_virtually_staged_watermark": null,
        "add_furniture": {
          "style": "standard",
          "room_type": "living",
          "base_variation_id": "text"
        },
        "remove_furniture": {
          "mode": "on",
          "mask_url": "text"
        }
      }
    }
  ]
}

{
  "results": [
    {
      "id": "text",
      "type": "staging",
      "render_id": "text",
      "created_at": 1,
      "status": "queued",
      "result": {
        "url": "text",
        "optimized_url": null,
        "thumbnail_url": null
      },
      "base_variation_id": "text",
      "eta": null,
      "config": {
        "type": "legacy_staging",
        "room_type": "living",
        "style": "standard"
      }
    }
  ]
}

Submit an image for a furniture mask generation

post

https://api.virtualstagingai.app/v2https://us-central1-furniture-ai.cloudfunctions.net/apiV2

/analyze

Submits an image for analysis to generate a furniture mask. If a webhook_url is provided, completion status will be sent to that URL.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication. Use the format: Api-Key ${key}.

Body

application/json

image_urlstringRequired

URL for an image, either HTTP/HTTPS URL or base64 encoded data URL.

Pattern: ^(https?:\/\/[^\s]+|data:image\/[a-zA-Z+]+;base64,[A-Za-z0-9+/=]+)$

webhook_urlstring · nullableOptional

URL for completion payload

Responses

200

Successful response

application/json

idstringRequired

Unique identifier for this analysis.

created_atnumberRequired

Creation timestamp (epoch milliseconds).

result_urlstringRequired

URL of the analysis result image.

percentage_maskednumberOptional

Percentage of the image that was identified as furniture.

statusstring · enumRequired

Status of the analysis.

Possible values:

400

Validation error.

application/json

401

Authentication error.

application/json

404

Validation error.

application/json

500

Unexpected server error.

application/json

post

/analyze

HTTPcURLJavaScriptPython

POST /v2/analyze HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "image_url": "text",
  "webhook_url": null
}

{
  "id": "text",
  "created_at": 1,
  "result_url": "text",
  "percentage_masked": 1,
  "status": "done"
}

Check if two images are compatible for multi-view staging

post

https://api.virtualstagingai.app/v2https://us-central1-furniture-ai.cloudfunctions.net/apiV2

/multi-view-compatibility

Analyzes two images to determine if they can be used together for multi-view staging.

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication. Use the format: Api-Key ${key}.

Body

application/json

image_urlsstring[] · min: 2 · max: 2Required

Array of two image URLs to check for compatibility.

Responses

200

Successful response

application/json

compatiblebooleanRequired

Whether the images are compatible for multi-view staging.

hard_rejectedbooleanRequired

Whether the multi-view staging was hard rejected. If true, multi-view staging is not possible. If false but compatible is false, multi-view staging is possible but the result may not be as good.

rejection_reasonstring · nullableOptional

Reason for rejection if images are not compatible.

400

Validation error.

application/json

401

Authentication error.

application/json

500

Unexpected server error.

application/json

post

/multi-view-compatibility

HTTPcURLJavaScriptPython

POST /v2/multi-view-compatibility HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "image_urls": [
    "text"
  ]
}

{
  "compatible": true,
  "hard_rejected": true,
  "rejection_reason": null
}

Create or update webhook secret

post

https://api.virtualstagingai.app/v2https://us-central1-furniture-ai.cloudfunctions.net/apiV2

/user/webhook-secret

Sets or updates the webhook secret used for HMAC signature verification

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication. Use the format: Api-Key ${key}.

Body

application/json

webhook_secretstring · min: 1Required

The webhook secret to use for HMAC signature verification

Pattern: ^[a-zA-Z0-9_-]+$

Responses

200

Webhook secret updated successfully

application/json

messagestringOptionalExample: Webhook secret updated successfully

400

Validation error.

application/json

401

Authentication error.

application/json

500

Unexpected server error.

application/json

post

/user/webhook-secret

HTTPcURLJavaScriptPython

POST /v2/user/webhook-secret HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "webhook_secret": "text"
}

{
  "message": "Webhook secret updated successfully"
}

Remove webhook secret

delete

https://api.virtualstagingai.app/v2https://us-central1-furniture-ai.cloudfunctions.net/apiV2

/user/webhook-secret

Removes the webhook secret used for HMAC signature verification

Authorizations

ApiKeyAuth

AuthorizationstringRequired

API key authentication. Use the format: Api-Key ${key}.

Responses

200

Webhook secret removed successfully

application/json

messagestringOptionalExample: Webhook secret removed successfully

401

Authentication error.

application/json

500

Unexpected server error.

application/json

delete

/user/webhook-secret

HTTPcURLJavaScriptPython

DELETE /v2/user/webhook-secret HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Accept: */*

{
  "message": "Webhook secret removed successfully"
}

Schemas