🛣️Endpoints

A directory of all Virtual Staging AI API endpoints.

Test your setup

GET https://api.virtualstagingai.app/v1/ping

Use this endpoint to test that your setup is working correctly. Returns some data about your account.

Headers

Name	Type	Description
Authorization	String	Set to "Api-Key {your_api_key_here}"

200: OK Success

Returns:

{
    userObj: {
        email: "...",
        uid: "..."
    },
    "photoLimit": 123,
    "photosUsedThisPeriod": 19
}

Create a new render

POST https://api.virtualstagingai.app/v1/render/create

This is the main endpoint of the API. Takes in a photo and virtually stages it.

Maximum concurrency per API account: 50.

Headers

Name	Type	Description
Authorization*	String	Set to "Api-Key {your_api_key_here}"

Request Body

Name	Type	Description
image_url*	String	URL of the image to add furniture to. If not provided, a "image"
room_type*	String	The type of room in the uploaded photo. Must be one of: [ "living", "bed", "kitchen", "dining", "bathroom", "home_office" ]
style*	String	The desired style of furnishing. Must be one of the following: ["modern", "scandinavian", "industrial", "midcentury", "luxury", "farmhouse", "coastal", "standard"]
resolution	String	Resolution of the output image. Must be 4k or full-hd
file	File	Form data field to pass an image directly (if not using image_url). If you're using this, the other arguments have to be sent via URL query parameters.
wait_for_completion	Boolean	If false, you'll get a response like {render_id} instantly and can look up your the state of your render using GET /v1/render. Default: true
add_virtually_staged_watermark	String	Adds a small "Virtually Staged" disclaimer in the lower right corner of the rendered image
declutter_mode	String	Can be: 'off' (default): don't perform decluttering. 'auto' : perform decluttering if furniture has been detected. 'on': always perform decluttering. If decluttering gets performed, two outputs will be created from this one create-render call: first will be the staged image, second will be the decluttered image. Subsequent variations will create further stagings on top of the existing decluttered image. If "wait_for_completion" is true and decluttering was performed, the "removal_output" will be set to an Image URL in the returned value.
declutter_mask_url	String	URL of a black-and-white image to use as a mask for decluttering instead of automatically generating a mask. Use this if you want to allow your users to draw their own mask to decide which furniture gets removed and which doesn't.

200: OK Success

Returns:

{
    result_image_url: string, // only if "wait_for_completion" was set to true
    render_id: string,
    removal_output: string // only if "wait_for_completion" was set to true and decluttering was performed
}

Store the Render ID if you wish to create further variations for this photo, or look up the render state using GET /v1/render

405: Method Not Allowed When using an HTTP method different than POST

401: Unauthorized Either your API key is invalid, or an error occurred during authentication

403: Forbidden Authentication succeeded but you don't have a plan with API access, or have used up your renders.

400: Bad Request Invalid value for some parameter (body will contain an explanation)

Get an existing render

GET https://api.virtualstagingai.app/v1/render

Use this to retrieve information about an existing render (e.g. show your users progress after starting a render with wait_for_completion=false).

This is available right after a render is created, even if the render status is rendering, so you can get the render info even if the render isn't done yet.

Query Parameters

Name	Type	Description
render_id*	String	The render ID returned from /v1/render/create

Headers

Name	Type	Description
Authorization*	String	Set to "Api-Key {your_api_key_here}"

200: OK Success

Returns:

{
    "render_id": "...",
    "status": "rendering" | "done" | "error",
    "created_at": 1685742540902, // epoch timestamp
    "outputs": string[], // will contain output image urls if status == "done". Will an entry for each new variation.
    "progress": 0.7432000000000001 // number 0-1
    "outputs_room_types": string[],
    "outputs_styles": string[]
}

405: Method Not Allowed Using different method than GET

401: Unauthorized API key invalid or not provided

403: Forbidden Authentication succeeded but your account doesn't have a plan with API access

404: Not Found Render not found

400: Bad Request No Render ID provided

Create a variation for an existing render

POST https://api.virtualstagingai.app/v1/render/create-variation

Creates a variation for an existing render. The render has to have been created using /v1/render/create beforehand.

All the same settings (room_type, etc.) from the first call will be used.

The render has to be in status done to start a new variation. The maximum amount of variations per render is 20.

Query Parameters

Name	Type	Description
render_id	String	The render ID returned from /v1/render/create

Headers

Name	Type	Description
Authorization*	String	Set to "Api-Key {your_api_key_here}"

Request Body

Name	Type	Description
wait_for_completion	Boolean	If false, you'll get a response like {render_id} instantly and the result output will be added to the outputs array in the render object. So when you retrieve the render object using GET /v1/render, the last element of outputs will contain the url to your new variation.
roomType	String	The type of room for the new variations. Must be one of: living, bed, kitchen, dining, bathroom, home_office.
style	String	The desired style of furnishing for the new variation. Must be in the following array: ["standard", "modern", "scandinavian", "industrial", "mid-century modern", "coastal", "american", "southwestern", "farmhouse", "luxury"]
add_virtually_staged_watermark	boolean
switch_to_queued_immediately	boolean	If true, will immediately switch render into "queued" status, then into "rendering" once the photo starts rendering.

200: OK

Returns:

{
    result_image_url: string, // only if "wait_for_completion" was set to true
    render_id: string
}

Store the Render ID if you wish to create further variations for this photo, or look up the render state using GET /v1/render.

If wait_for_completion was false, only the render_id will be returned and you'll have to look up the render state using GET /v1/render. Then, the output image of your variation will be appended to the outputs array and status will be rendering until the variation is done.

405: Method Not Allowed You're using a method other than POST

401: Unauthorized API Key invalid or not provided

403: Forbidden Authentication succeeded but your account doesn't have a plan with API access

400: Bad Request render_id not provided, or an invalid parameter provided in the request body

404: Not Found Render with the passed ID not found

500: Internal Server Error Unknown Error; reach out to support

Get available room types & styles

GET https://api.virtualstagingai.app/v1/options

Returns the available styles and room types. They need to be passed into other endpoints exactly as the same strings as returned here.

Headers

Name	Type	Description
Authorization*	String	Set to "Api-Key {your_api_key_here}"

200: OK

Returns:

{
    "styles": [
        "modern",
        "scandinavian",
        "industrial",
        "midcentury",
        "luxury",
        "farmhouse",
        "coastal",
        "standard"
    ],
    "roomTypes": [
        "living",
        "bed",
        "kitchen",
        "dining",
        "bathroom",
        "home_office"
    ]
}