🛣️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: the first one will be the staged image, the second one will be the decluttered image. Subsequent variations will create further stagings on top of the existing decluttered image. If "add_furniture" is false and "declutter_mode" is on, only decluttered image will be created. 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.
add_furniture	Boolean	If "declutter_mode" is 'on' this parameter can be set to false to only remove existing furniture and not add new furniture. The output will then only include the decluttered image without any added furniture. Default: true

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