🔌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

Returns 200 OK if the API is running

Authorizations

Responses

200

API is operational

get

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

Returns information about the authenticated user including their usage limits

Authorizations

Responses

200

Successful response

application/json

401

Authentication error

application/json

500

Unexpected server error

application/json

get

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

Returns all renders for the authenticated user

Authorizations

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

401

Authentication error

application/json

500

Unexpected server error

application/json

get

HTTPcURLJavaScriptPython

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

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

Create a new render

post

Creates a new render with the specified parameters. If a webhook_url is provided, status updates will be sent to that URL as the render progresses.

Authorizations

Body

configone ofRequired

or

or

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 · uri | nullableOptional

URL to send progress updates to

variation_countinteger · min: 1Required

wait_for_completionboolean | nullableOptionalDefault: false

Responses

200

Render created successfully

application/json

201

Render created and queued for processing

application/json

400

Validation or business logic error

application/json

401

Authentication error

application/json

403

Forbidden error

application/json

500

Unexpected server error

application/json

post

HTTPcURLJavaScriptPython

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

{
  "config": {
    "type": "staging",
    "add_virtually_staged_watermark": true,
    "add_furniture": {
      "style": "standard",
      "room_type": "living",
      "base_variation_id": "text"
    },
    "multi_view_staging": {
      "image_url": "text"
    },
    "remove_furniture": {
      "mode": "on",
      "mask_url": "text"
    }
  },
  "image_url": "text",
  "webhook_url": "https://example.com",
  "variation_count": 1,
  "wait_for_completion": true
}

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

Get render details

get

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

Authorizations

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

401

Authentication error

application/json

404

Validation or business logic error

application/json

500

Unexpected server error

application/json

get

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": 1,
  "variations": {
    "total_count": 1,
    "next_cursor": "text",
    "items": [
      {
        "id": "text",
        "type": "staging",
        "render_id": "text",
        "created_at": 1,
        "status": "queued",
        "result": {
          "url": "text",
          "optimized_url": "text",
          "thumbnail_url": "text"
        },
        "base_variation_id": "text",
        "eta": 1,
        "config": {
          "type": "legacy_staging",
          "room_type": "living",
          "style": "standard"
        }
      }
    ]
  },
  "eta": 1
}

Get variation details

get

Returns details about a variation including the status and result URL

Authorizations

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

401

Authentication error

application/json

404

Validation or business logic error

application/json

500

Unexpected server error

application/json

get

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": "text",
    "thumbnail_url": "text"
  },
  "base_variation_id": "text",
  "eta": 1,
  "config": {
    "type": "legacy_staging",
    "room_type": "living",
    "style": "standard"
  }
}

Create new variations

post

Create one or more variations for an existing render. If a webhook_url is provided, status updates will be sent to that URL as variations progress.

Authorizations

Path parameters

render_idstringRequired

Body

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 or business logic error

application/json

401

Authentication error

application/json

403

Forbidden error

application/json

404

Validation or business logic error

application/json

500

Unexpected server error

application/json

post

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: 292

{
  "config": {
    "type": "staging",
    "add_virtually_staged_watermark": true,
    "add_furniture": {
      "style": "standard",
      "room_type": "living",
      "base_variation_id": "text"
    },
    "multi_view_staging": {
      "image_url": "text"
    },
    "remove_furniture": {
      "mode": "on",
      "mask_url": "text"
    }
  },
  "variation_count": 1,
  "wait_for_completion": true
}

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

Create multiple renders in bulk

post

Creates multiple renders with the specified parameters.

Authorizations

Body

webhook_urlstring · uri | 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 or business logic error

application/json

401

Authentication error

application/json

403

Forbidden error

application/json

404

Validation or business logic error

application/json

500

Unexpected server error

application/json

post

HTTPcURLJavaScriptPython

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

{
  "webhook_url": "https://example.com",
  "wait_for_completion": true,
  "renders": [
    {
      "config": {
        "type": "staging",
        "add_virtually_staged_watermark": true,
        "add_furniture": {
          "style": "standard",
          "room_type": "living",
          "base_variation_id": "text"
        },
        "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": 1,
      "variations": {
        "total_count": 1,
        "next_cursor": "text",
        "items": [
          {
            "id": "text",
            "type": "staging",
            "render_id": "text",
            "created_at": 1,
            "status": "queued",
            "result": {
              "url": "text",
              "optimized_url": "text",
              "thumbnail_url": "text"
            },
            "base_variation_id": "text",
            "eta": 1,
            "config": {
              "type": "legacy_staging",
              "room_type": "living",
              "style": "standard"
            }
          }
        ]
      },
      "eta": 1
    }
  ]
}

Create multiple variations in bulk

post

Creates multiple variations for an existing render with different configurations.

Authorizations

Body

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 or business logic error

application/json

401

Authentication error

application/json

403

Forbidden error

application/json

404

Validation or business logic error

application/json

500

Unexpected server error

application/json

post

HTTPcURLJavaScriptPython

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

{
  "wait_for_completion": true,
  "renders": [
    {
      "render_id": "text",
      "variation_count": 1,
      "config": {
        "type": "staging",
        "add_virtually_staged_watermark": true,
        "add_furniture": {
          "style": "standard",
          "room_type": "living",
          "base_variation_id": "text"
        },
        "multi_view_staging": {
          "image_url": "text"
        },
        "remove_furniture": {
          "mode": "on",
          "mask_url": "text"
        }
      }
    }
  ]
}

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

Submit an image for a furniture mask generation

post

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

Body

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 · uri | nullableOptional

URL for completion payload

Responses

200

Successful response

application/json

401

Authentication error

application/json

404

Validation or business logic error

application/json

500

Unexpected server error

application/json

post

HTTPcURLJavaScriptPython

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

{
  "image_url": "text",
  "webhook_url": "https://example.com"
}

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

Check if two images are compatible for multi-view staging

post

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

Authorizations

Body

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

Array of two image URLs to check for compatibility

Responses

200

Successful response

application/json

400

Validation or business logic error

application/json

401

Authentication error

application/json

500

Unexpected server error

application/json

post

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": "text"
}