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

PreviousCore Concepts NextWebhooks

Last updated 1 month ago

Check API status

get

Returns 200 OK if the API is running

Authorizations

Responses

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.virtualstagingai.app/v2/status' \
  --header 'Authorization: YOUR_API_KEY'

200

No body

API is operational

Get current user details

get

Returns information about the authenticated user including their usage limits

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.virtualstagingai.app/v2/user' \
  --header 'Authorization: YOUR_API_KEY'

200

401

500

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

Successful response

Get all renders

get

Returns all renders for the authenticated user

Authorizations

Query parameters

limitinteger · min: 1 · max: 100 · default: 20optional

cursorstringoptional

Render ID to start after

orderstring · enum · default: "asc"optional

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

Available options:

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.virtualstagingai.app/v2/renders' \
  --header 'Authorization: YOUR_API_KEY'

200

401

500

{
  "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
    }
  ]
}

Successful response

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_variationsboolean · default: falseoptional

variations_limitinteger · min: 1 · max: 100 · default: 20optional

variations_cursorstringoptional

Variation ID to start after

variations_orderstring · enum · default: "asc"optional

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

Available options:

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.virtualstagingai.app/v2/renders/{render_id}' \
  --header 'Authorization: YOUR_API_KEY'

200

401

404

500

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

Successful response

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

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.virtualstagingai.app/v2/renders/{render_id}/variations/{variation_id}' \
  --header 'Authorization: YOUR_API_KEY'

200

401

404

500

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

Successful response

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

image_urlstringrequired

URL for the image to use for the render

webhook_urlstring · uri | nullableoptional

URL to send progress updates to

variation_countinteger · min: 1required

wait_for_completionboolean | nullableoptional

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.virtualstagingai.app/v2/renders' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "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
  }'

200

201

400

401

403

500

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

Render created successfully

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

variation_countinteger · min: 1required

wait_for_completionboolean | nullableoptional

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.virtualstagingai.app/v2/renders/{render_id}/variations' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "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
  }'

200

201

400

401

403

404

500

{
  "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"
      }
    }
  ]
}

Variations created and completed successfully

Create multiple renders in bulk

post

Creates multiple renders with the specified parameters.

Authorizations

Body

webhook_urlstring · uri | nullableoptional

wait_for_completionboolean | nullableoptional

rendersobject[] · min: 1required

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.virtualstagingai.app/v2/renders/bulk' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "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
      }
    ]
  }'

200

201

400

401

403

404

500

{
  "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
    }
  ]
}

Renders created and completed successfully

Create multiple variations in bulk

post

Creates multiple variations for an existing render with different configurations.

Authorizations

Body

wait_for_completionboolean | nullableoptional

rendersobject[] · min: 1required

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.virtualstagingai.app/v2/renders/variations/bulk' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "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"
          }
        }
      }
    ]
  }'

200

201

400

401

403

404

500

{
  "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"
          }
        }
      ]
    }
  ]
}

Variations for renders created and completed successfully

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 the image to analyze

webhook_urlstring · uri | nullableoptional

URL for completion payload

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.virtualstagingai.app/v2/analyze' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "image_url": "text",
    "webhook_url": "https://example.com"
  }'

200

401

404

500

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

Successful response

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

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.virtualstagingai.app/v2/multi-view-compatibility' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "image_urls": [
      "text"
    ]
  }'

200

400

401

500

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

Successful response

Check API status

Get current user details

Get all renders

Get render details

Get variation details

Create a new render

Show child attributes

Show child attributes

Show child attributes

Create new variations

Show child attributes

Show child attributes

Show child attributes

Create multiple renders in bulk

Show child attributes

Create multiple variations in bulk

Show child attributes

Submit an image for a furniture mask generation

Check if two images are compatible for multi-view staging