Virtual Staging AI Docs
  • ๐Ÿš€Getting Started
  • ๐Ÿ›ฃ๏ธEndpoints
  • ๐Ÿ‘ฉโ€๐Ÿ’ปSnippets
  • โ“Help & Support
  • ๐ŸŒก๏ธStatus
  • v2 API
    • ๐Ÿ“Core Concepts
    • ๐Ÿ”ŒEndpoints
    • ๐ŸชWebhooks
Powered by GitBook
On this page
  1. v2 API

Endpoints

PreviousCore ConceptsNextWebhooks

Last updated 24 days ago

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}

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

Schemas

๐Ÿ”Œ

Check API status

get

Returns 200 OK if the API is running

Authorizations
Responses
200
API is operational
get
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
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
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
    }
  ]
}

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 error.
application/json
500
Unexpected server error.
application/json
get
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

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 error.
application/json
500
Unexpected server error.
application/json
get
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"
  }
}

Remove webhook secret

delete

Removes the webhook secret used for HMAC signature verification

Authorizations
Responses
200
Webhook secret removed successfully
application/json
401
Authentication error.
application/json
500
Unexpected server error.
application/json
delete
DELETE /v2/user/webhook-secret HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Accept: */*
{
  "message": "Webhook secret removed successfully"
}
  • GETCheck API status
  • GETGet current user details
  • GETGet all renders
  • POSTCreate a new render
  • GETGet render details
  • GETGet variation details
  • POSTCreate new variations
  • POSTCreate multiple renders in bulk
  • POSTCreate multiple variations in bulk
  • POSTSubmit an image for a furniture mask generation
  • POSTCheck if two images are compatible for multi-view staging
  • POSTCreate or update webhook secret
  • DELETERemove webhook secret
  • Schemas

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

URL to send progress updates to

variation_countinteger ยท min: 1Required
wait_for_completionboolean | nullOptionalDefault: false
Responses
200
Render created successfully
application/json
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
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",
  "webhook_url": null,
  "variation_count": 1,
  "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
}

Create new variations

post

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
Path parameters
render_idstringRequired
Body
configone ofRequired
or
or
variation_countinteger ยท min: 1Required
wait_for_completionboolean | nullOptionalDefault: 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
POST /v2/renders/{render_id}/variations HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 323

{
  "config": {
    "type": "staging",
    "output_resolution": "default",
    "add_virtually_staged_watermark": null,
    "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": 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

Creates multiple renders with the specified parameters.

Authorizations
Body
webhook_urlstring | nullOptional
wait_for_completionboolean | nullOptionalDefault: 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
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

Creates multiple variations for an existing render with different configurations.

Authorizations
Body
wait_for_completionboolean | nullOptionalDefault: 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
POST /v2/renders/variations/bulk HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 356

{
  "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"
        },
        "multi_view_staging": {
          "image_url": "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

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

URL for completion payload

Responses
200
Successful response
application/json
400
Validation error.
application/json
401
Authentication error.
application/json
404
Validation error.
application/json
500
Unexpected server error.
application/json
post
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

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 error.
application/json
401
Authentication error.
application/json
500
Unexpected server error.
application/json
post
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

Sets or updates the webhook secret used for HMAC signature verification

Authorizations
Body
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
400
Validation error.
application/json
401
Authentication error.
application/json
500
Unexpected server error.
application/json
post
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"
}