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

๐Ÿ”Œ
Settings

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

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

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
POST /v2/renders HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 348

{
  "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": false
}
{
  "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 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
POST /v2/renders/{render_id}/variations HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 293

{
  "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": false
}
{
  "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
POST /v2/renders/bulk HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 362

{
  "webhook_url": "https://example.com",
  "wait_for_completion": false,
  "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
POST /v2/renders/variations/bulk HTTP/1.1
Host: api.virtualstagingai.app
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 326

{
  "wait_for_completion": false,
  "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
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
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"
}