Introduction
The Collov Virtual Staging API enables developers to integrate AI-powered room transformations into their applications, allowing you to virtually redesign spaces or clear rooms entirely from uploaded images.
With just a few API calls, you can:

Room Declutter
Automatically remove all furniture and decorations while preserving walls, floors, and architectural features.

Virtual Staging
Automatically remove all furniture and decorations while preserving walls, floors, and architectural features.
These APIs are designed to support asynchronous task processing:
- You initiate a task with a Send Task API.
- You periodically poll the Get Result API using the returned uuid (for staging) or id (for empty room tasks) until the status is SUCCESS.
This workflow ensures you can process high-quality AI-generated results without blocking client operations, while respecting rate limits (10 requests/sec) and concurrency limits (2 active tasks).
Whether you're building a real estate platform, an interior design tool, or a property management solution, the Collov Virtual Staging API provides a scalable, programmatic way to create photorealistic room transformations at scale.
Tutorial
Before you start
- Auth: Send
apiKey: YOUR_API_KEYin headers. - Content-Type:
multipart/form-datafor both "send task" and "get result" endpoints (per spec). - Async task process: Send → get a task token (uuid or id) → poll until status: SUCCESS or FAILED.
- Rate limit: 10 requests per second; concurrency limit: 2. If you receive HTTP 429, implement exponential back‑off and retry.
Virtual Staging: Render a designed room
Send task
POSThttps://api.collov.ai/flair/enterpriseApi/vst/generateImgOnCommon
Form fields:
uploadUrl(string, required) – public URL to the original imageroomType(enum, required) – one of the room types abovestyle(enum, required) – one of the styles aboveemptyRoomUrl(string, optional) – if you already cleared the room, pass its URL to stage on top of it
Sample curl:
Set API_KEY in the environment first before running the curl:
Python (requests):
JavaScript (fetch):
Poll for result
GEThttps://api.collov.ai/flair/enterpriseApi/vst/getRecord
Query parameter:
uuid(string, required) – from step 1A response
Sample curl:
Set API_KEY in the environment first before running the curl:
Python (Poll pattern):
JavaScript (Poll pattern):
What you'll use from the result:
data.status→ SUCCESS/PENDING/FAILEDdata.aiGenerateRecord.generateUrl→ final rendered image URLdata.prompt,data.roomType,data.style,data.durationTime→ metadata
Room Clearing: Create an "empty room" (remove furniture)
Send task
POSThttps://api.collov.ai/flair/enterpriseApi/vst/generateEmptyRoom
Form fields:
uploadUrl(string, required) – public URL to the original image
Sample curl:
Set API_KEY in the environment first before running the curl:
Response gives you numeric id (store this; you'll poll with it).
Poll for result
GEThttps://api.collov.ai/flair/enterpriseApi/vst/getEmptyRoomRecord
Query parameter
id(integer, required) – from step 2A
Sample curl:
Set API_KEY in the environment first before running the curl:
Python (Poll pattern):
Recommended workflow
- (Optional) Clear room first
- Send generateEmptyRoom → poll getEmptyRoomRecord → get emptyRoomUrl.
- Stage the room
- Send generateImgOnCommon with:
- uploadUrl: your original image URL
- emptyRoomUrl: the cleared image URL from step 1 (improves control/consistency)
- roomType, style
- Poll getRecord using uuid.
- Use aiGenerateRecord.generateUrl as your final render.
- Send generateImgOnCommon with:
Robustness & production tips
- Backoff on 429: exponential backoff (e.g., 1s, 2s, 4s, … up to 30s).
- Timeouts: client-side timeout per poll (e.g., 3–5 minutes) and total job timeout.
- Validate enums: force lowercase & whitelist room types/styles; reject early if invalid.
- Id/UUID storage:
- Room design API uses uuid to poll.
- Empty room API uses numeric id to poll.
- Security: uploadUrl/emptyRoomUrl should be on a public CDN/S3 with read access. Don't pass private URLs that require signed headers (unless they're presigned).
- Watermark & mode: Responses may include watermark, proMode, etc.—log them if you need auditing.
- Concurrency: Keep at most 2 active tasks per account to avoid throttling; queue client-side if needed.
API Reference
Async AI-Rendered Room Design (Send Task)
Initiate a task to take a picture and render a given type of room with instructed design style. The process will modify the furnitures, decorations in the room, but will maintain the room structure as unchanged.
POSThttps://api.collov.ai/flair/enterpriseApi/vst/generateImgOnCommon
Request Headers:
| Field | Value | Description |
|---|---|---|
| apiKey | YOUR_API_KEY | The API key you retrieved from the enterprise API center. |
| Content-Type | multipart/form-data | Data Exchange Format. |
Request Body:
| Field | Type | Is Required | Description |
|---|---|---|---|
| uploadUrl | String | Yes | The image provided for the process. |
| roomType | String enum | Yes | One of the value from below, must be lower case: game room, kitchen, living room, outdoor, bedroom, studio, conference room, home office, home gym, dining room, laundry room, bathroom, spa room, kids room, open living and dining room |
| style | String enum | Yes | One of the value from below, must be lower case: scandinavian, luxury, industrial, coastal, transitional, farmhouse, mid-century, modern |
| emptyRoomUrl | String | No | Provide if you'd like the generation to happen in a cleared room. |
Sample Response:
Async Regenerate AI-Rendered Room Design (Send Task)
Re-render a previously processed room image with same parameters (e.g., style, seed) while preserving the original room structure.
Each source image initially submitted to the Async AI‑Rendered Room Design API receives up to 20 free calls to this regeneration API. After that, further requests fail and you must restart a series of generations with a call to the Async AI‑Rendered Room Design API.
POSThttps://api.collov.ai/flair/enterpriseApi/vst/reGenerateImgOnCommon
Request Headers:
| Field | Value | Description |
|---|---|---|
| apiKey | YOUR_API_KEY | The API key you retrieved from the enterprise API center. |
| Content-Type | multipart/form-data | Data Exchange Format. |
Request Body:
| Field | Type | Is Required | Description |
|---|---|---|---|
| uuid | String | Yes | The uuid generated from the initial AI-generation API call for the source image. |
Sample Response:
Design Result Retrieval (Get Result)
This API endpoint allows repeated queries to retrieve results from both generation APIs:
- The Async AI-Rendered Room Design endpoint;
- The Async Regeneration AI-Rendered Room Design endpoint;
The response bodies from the getRecord call are nearly identical for both generation scenarios, with one key difference:
- For the initial Async AI-Rendered Room Design, the generateRecordList field contains only a single GenerateRecord.
- For each subsequent Async Regeneration AI-Rendered Room Design call, an additional GenerateRecord is appended to this list, ordered by request time.
GEThttps://api.collov.ai/flair/enterpriseApi/vst/getRecord
Request Headers:
| Field | Value | Description |
|---|---|---|
| apiKey | YOUR_API_KEY | The API key you retrieved from enterprise API center. |
Query Parameter:
| Field | Type | Is Required | Description |
|---|---|---|---|
| uuid | String | Yes | The UUID returned from the task initiation API call that happens earlier. |
Sample Response:
Async AI-Powered Room Clearing (Send Task)
POSThttps://api.collov.ai/flair/enterpriseApi/vst/generateEmptyRoom
Request Headers:
| Field | Value | Description |
|---|---|---|
| apiKey | YOUR_API_KEY | The API key you retrieved from enterprise API center. |
| Content-Type | multipart/form-data | Data Exchange Format. |
Request Body:
| Field | Type | Is Required | Description |
|---|---|---|---|
| uploadUrl | String | Yes | The image provided for the process. |
Sample Response:
Room Clearing Result Retrieval (Get Result)
Retrieve the result of the room clearing task by repeatedly querying this API.
GEThttps://api.collov.ai/flair/enterpriseApi/vst/getEmptyRoomRecord
Request Headers:
| Field | Value | Description |
|---|---|---|
| apiKey | YOUR_API_KEY | The API key you retrieved from enterprise API center. |
Query Parameter:
| Field | Type | Is Required | Description |
|---|---|---|---|
| id | Integer | Yes | The id returned from the task initiation API call that happens earlier. |
Sample Response:
Async AI-Powered Photo Chat Editing (Send Task)
POSThttps://api.collov.ai/flair/enterpriseApi/edit/generate
Request Headers:
| Field | Value | Description |
|---|---|---|
| apiKey | YOUR_API_KEY | The API key you retrieved from enterprise API center. |
| Content-Type | multipart/form-data | Data Exchange Format. |
Request Body:
| Field | Type | Is Required | Description |
|---|---|---|---|
| uploadUrl | String | Yes | The image provided for the process. |
| prompt | String | Yes | Edit Content. |
Sample Response:
Photo Chat Edit Result Retrieval (Get Result)
Retrieve the result of the photo chat edit task by repeatedly querying this API.
GEThttps://api.collov.ai/flair/enterpriseApi/vst/getEmptyRoomRecord
Request Headers:
| Field | Value | Description |
|---|---|---|
| apiKey | YOUR_API_KEY | The API key you retrieved from enterprise API center. |
Query Parameter:
| Field | Type | Is Required | Description |
|---|---|---|---|
| uuid | String | Yes | The uuid returned from the task initiation API call that happens earlier. |
Sample Response:
Async AI Virtual Tool (Send Task)
POSThttps://api.collov.ai/flair/enterpriseApi/vgs/task
Request Headers:
| Field | Value | Description |
|---|---|---|
| apiKey | YOUR_API_KEY | The API key you retrieved from enterprise API center. |
| Content-Type | multipart/form-data | Data Exchange Format. |
Request Body:
| Field | Type | Is Required | Description |
|---|---|---|---|
| images | array | Yes | {"imageUrl": "https://d17axom7zrjq3q.cloudfront.net/20250901/d535b795-54ff-4d3d-89bb-4bf810326ae1.png","width": 768,"height": 769} |
| resolution | String | Yes | One of the value from below: 1080p、720p |
| orientation | String | Yes | One of the value from below:Landscape、Portrait、Square |
| font | String | No | One of the value from below:Oswald、Amatic、GreatVibes、OpenSans、Montserrat、Playfair |
| music | String | No | One of the value from below:Embrace、Future_Design、Waterfall、Happy_Holiday、Summer_Ukulele |
| intro | String | No | Text overlay on video |
| profileUrl | String | No | Personal profile picture |
| logoUrl | String | No | Company logo image |
| agentName | String | No | Agent Name |
| phoneNumber | String | No | mobile phone number |
| String | No |
Sample Response:
AI Virtual Tool Result Retrieval (Get Result)
Retrieve the result of the AI virtual tool task by repeatedly querying this API.
GEThttps://api.collov.ai/flair/enterpriseApi/vgs/loadVideoInfo
Request Headers:
| Field | Value | Description |
|---|---|---|
| apiKey | YOUR_API_KEY | The API key you retrieved from enterprise API center. |
Query Parameter:
| Field | Type | Is Required | Description |
|---|---|---|---|
| taskId | String | Yes | The taskId returned from the task initiation API call that happens earlier. |
Sample Response:
Resources
Limits
Rate limit
All enterprise APIs are rate limited to 10 requests per second. Exceeding this rate limit will result in an HTTP error 429.
Concurrency limit
All enterprise APIs have a concurrency limit of 2.
Terms of Use
Please refer to our terms of use for API usage guidelines.
Privacy Policy
Our privacy policy explains how we handle your data.