| Item | Description |
|---|---|
| Base URL | https://global-api.homestyler.com/global/hs/api |
| HTTP method | POST; use PUT for direct file uploads |
| Data format | JSON; raw file content for direct uploads |
| Authentication | HS_OPEN_API_KEY request header |
Authentication & account access
To execute Homestyler OpenAPI requests, supply your personal account's AppKey in the HS_OPEN_API_KEY header.
Get your AppKey
Create and copy your AppKey in the personal management console. Include it in every OpenAPI request:
HS_OPEN_API_KEY: YOUR_APP_KEY
Content-Type: application/json
API calls require an active OpenAPI plan. Some endpoints also require the corresponding membership benefits. Your account's request quotas and generation entitlement limits still apply.
Requests, Responses, and Pagination
Common Request Field
Include the following field in the JSON body of every Personal HTTP API request:
| Field | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Client-generated request identifier. Must be nonblank and no longer than 60 characters. Use a unique value for each request to assist troubleshooting. |
Common Response Structure
| Field | Type | Description |
|---|---|---|
| success | Boolean | Whether the API call succeeded. Does not indicate that an asynchronous task has completed. |
| msgCode | String | Numeric string. "0" on success; see Error Handling for error codes. |
| msgInfo | String | Result description; typically success on success. |
| model | Object / Array / String | Result data. The type depends on the endpoint. Usually empty on failure. |
| traceId | String | Server trace identifier. Retain this value for troubleshooting. |
| requestId | String | The parsed request identifier. May be empty if request parsing or authentication fails early. |
Pagination
| Field | Type | Description |
|---|---|---|
| model.pagingData | Object | Pagination information. |
| model.pagingData.pageNo | Integer | Current page number, starting at 1. |
| model.pagingData.pageSize | Integer | Number of records per page. |
| model.pagingData.total | Long | Total number of matching records. |
| model.pagingData.hasMore | Boolean | Whether additional records exist, based on the total, page number, and page size. |
| model.data | Array | Records on the current page. An empty array if no records are found. |
Quick Start
List Designs
curl --request POST \
'https://global-api.homestyler.com/global/hs/api/project/list' \
--header 'HS_OPEN_API_KEY: <YOUR_APP_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{"requestId":"req-project-list-001","pageNo":1,"pageSize":20}'
On success, read the designs from model.data and pagination information from model.pagingData.
Endpoint Directory
| Category | Method | Path | Operation |
|---|---|---|---|
| Designs | POST | /global/hs/api/project/list |
List designs |
| Designs | POST | /global/hs/api/project/detail |
Get design details |
| Designs | POST | /global/hs/api/project/delete |
Delete a design |
| Floor Plans | POST | /global/hs/api/floorplan/url |
Get an upload URL |
| Floor Plans | POST | /global/hs/api/floorplan/upload |
Submit floor plan recognition |
| Floor Plans | POST | /global/hs/api/floorplan/get |
Get recognition results |
| Floor Plans | POST | /global/hs/api/floorplan/download |
Export a floor plan |
| Floor Plans | POST | /global/hs/api/floorplan/bill/download |
Export a bill of materials |
| AI Deco | POST | /global/hs/api/ai/deco/inspiration/sample-room/list |
List inspiration sample rooms |
| AI Deco | POST | /global/hs/api/ai/deco/submit |
Submit AI Deco |
| AI Deco | POST | /global/hs/api/ai/deco/result |
Get AI Deco results |
| Smart View and Rendering | POST | /global/hs/api/rendering/smart-view/submit |
Submit Smart View generation |
| Smart View and Rendering | POST | /global/hs/api/rendering/smart-view/result |
Get Smart View results |
| Smart View and Rendering | POST | /global/hs/api/rendering/submit |
Submit design rendering |
| Smart View and Rendering | POST | /global/hs/api/rendering/result/batch |
Get rendering tasks in a batch |
| Smart View and Rendering | POST | /global/hs/api/rendering/list |
List rendering resources |
| AI Tools | POST | /global/hs/api/ai/render/submit |
Submit AI Render |
| AI Tools | POST | /global/hs/api/ai/moodboard/submit |
Submit AI Moodboard |
| AI Tools | POST | /global/hs/api/ai/floorplan/submit |
Submit AI Floorplan |
| AI Tools | POST | /global/hs/api/ai/modeler/submit |
Submit AI Modeler |
| AI Tools | POST | /global/hs/api/ai/status |
Get AI task status |
| 3D Viewer | POST | /global/hs/api/project/viewer |
Get a design viewer URL |
See also direct file upload.
Designs
List Designs
POST /global/hs/api/project/list
List designs owned by the user associated with your AppKey.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| pageNo | Integer | Yes | Page number. Minimum: 1. |
| pageSize | Integer | Yes | Records per page. Minimum: 1. |
| name | String | No | Reserved field. Maximum 50 characters. Filtering by name is not currently supported. |
Request example
{
"requestId": "req-project-list-001",
"pageNo": 1,
"pageSize": 20
}
Response data: model
| Field | Type | Description |
|---|---|---|
| pagingData | Object | See Pagination. |
| data | Array | Records on the current page. |
| data[].id | String | Design ID. |
| data[].name | String | Design name. |
| data[].image | String | Design image URL. May be empty. Valid for 30 minutes. |
| data[].lastTimeModified | String | Last modification time, returned as a string. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"pagingData": {
"pageNo": 1,
"pageSize": 20,
"total": 1,
"hasMore": false
},
"data": [
{
"id": "design_example_001",
"name": "Two-Bedroom Apartment",
"image": "https://assets.example.com/design/cover.jpg",
"lastTimeModified": "1794528000000"
}
]
},
"traceId": "trace-example-001",
"requestId": "req-project-list-001"
}
Get Design Details
POST /global/hs/api/project/detail
Retrieve a design owned by the current user. A design that does not exist or belongs to another user is reported as not found.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| id | String | Yes | Design ID. Nonblank; maximum 100 characters. |
Request example
{
"requestId": "req-project-detail-001",
"id": "design_example_001"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| id | String | Design ID. |
| name | String | Design name. |
| description | String | Design description. |
| versionId | String | Design version identifier. Treat it as an opaque identifier, not a timestamp. |
| attr | Object | Design attributes. May be empty. |
| attr.area | Float | Design area. |
| attr.bedRoomNum | Integer | Number of bedrooms. |
| attr.livingRoomNum | Integer | Number of living rooms. |
| attr.bathRoomNum | Integer | Number of bathrooms. |
| attr.style | Object | Style information. May be empty. |
| attr.style.code | String | Style code. |
| attr.style.name | String | Style name. Currently identical to the style code. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"id": "design_example_001",
"name": "Two-Bedroom Apartment",
"description": "Living room, dining area, and bedroom design",
"versionId": "v20261112120000",
"attr": {
"area": 85.5,
"bedRoomNum": 2,
"livingRoomNum": 1,
"bathRoomNum": 1,
"style": {
"code": "Modern",
"name": "Modern"
}
}
},
"traceId": "trace-example-001",
"requestId": "req-project-detail-001"
}
Delete a Design
POST /global/hs/api/project/delete
Delete a design owned by the current user by its ID.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| id | String | Yes | Design ID. Nonblank; maximum 100 characters. |
Request example
{
"requestId": "req-project-delete-001",
"id": "design_example_001"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| result | Boolean | Whether deletion succeeded. Check this field together with the outer success field. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"result": true
},
"traceId": "trace-example-001",
"requestId": "req-project-delete-001"
}
Floor Plans
Get an Upload URL
POST /global/hs/api/floorplan/url
Request a temporary upload URL for a floor plan source file. Floor plan recognition supports IMAGE input. The following example uses PNG.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| fileType | String | Yes | File extension without a leading dot. Supported values: png, jpg, jpeg, webp. Case-sensitive. |
Request example
{
"requestId": "req-floorplan-url-001",
"fileType": "png"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| url | String | Complete temporary URL for PUT upload, including authentication query parameters. Validity is specified by the expiration information in the URL. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"url": "https://upload.example.com/temporary/floorplan.png?OSSAccessKeyId=EXAMPLE&Expires=1800000000&Signature=EXAMPLE"
},
"traceId": "trace-example-001",
"requestId": "req-floorplan-url-001"
}
Usage notes
Obtaining a URL does not upload the file or start recognition.
Upload the File
PUT <complete url returned by Get an Upload URL>
Send the raw file content to the returned upload URL. The HS_OPEN_API_KEY header is not required. Example for PNG:
curl --request PUT '<TEMPORARY_UPLOAD_URL>' \
--header 'Content-Type: image/png' \
--header 'x-oss-object-acl: public-read' \
--data-binary '@/path/to/floorplan.png'
The temporary URL is bound to the HTTP method, file Content-Type, and x-oss-object-acl. Upload the file using the type specified when requesting the URL. Use image/png for PNG, image/jpeg for JPG/JPEG, and image/webp for WEBP. Compatibility with subsequent recognition depends on the supported recognition formats.
After uploading, pass a readable file URL to the recognition endpoint. For a file uploaded with public read access as shown above, remove the upload signature query string to obtain the object URL. Keep the complete signed URL for the PUT request itself. The cover image must also be accessible by URL.
Submit Floor Plan Recognition
POST /global/hs/api/floorplan/upload
Create a design asynchronously from a floor plan image. Use the returned scanId to retrieve recognition results.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| url | String | Yes | Accessible floor plan image URL. Nonblank; maximum 300 characters. |
| type | String | Yes | Must be IMAGE. Case-sensitive. |
| grossArea | Double | Yes | Gross floor area. Must be greater than 0 and supplied as a JSON number. |
| projectName | String | Yes | Name of the generated design. Nonblank; maximum 60 characters. |
| coverImageFileUrl | String | Yes | Accessible design cover image URL. Nonblank; maximum 300 characters. |
Request example
{
"requestId": "req-floorplan-upload-001",
"url": "https://assets.example.com/floorplan.png",
"type": "IMAGE",
"grossArea": 85.5,
"projectName": "Two-Bedroom Apartment",
"coverImageFileUrl": "https://assets.example.com/cover.png"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| scanId | String | Recognition task ID. Use it with Get Recognition Results. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"scanId": "scan_example_001"
},
"traceId": "trace-example-001",
"requestId": "req-floorplan-upload-001"
}
Usage notes
Provide an accessible file URL. Local file paths are not supported. Both the floor plan and cover images must pass image review. If review fails, the API returns 1103 and no recognition task is created.
Get Recognition Results
POST /global/hs/api/floorplan/get
Retrieve the current recognition status. Continue polling while processing is incomplete.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| scanId | String | Yes | scanId returned by the submission endpoint. Nonblank; maximum 100 characters. |
Request example
{
"requestId": "req-floorplan-get-001",
"scanId": "scan_example_001"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| scanId | String | Recognition task ID. |
| status | String | UPLOAD_SUCCESS: uploaded, awaiting recognition; ANALYZING: processing; ANALYZE_SUCCESS: succeeded; ANALYZE_FAIL: failed. |
| designId | String | Generated design ID. May be empty before the design is created. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"scanId": "scan_example_001",
"status": "ANALYZE_SUCCESS",
"designId": "design_example_001"
},
"traceId": "trace-example-001",
"requestId": "req-floorplan-get-001"
}
Export a Floor Plan
POST /global/hs/api/floorplan/download
Export the floor plan of a design owned by the current user.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| designId | String | Yes | Design ID. Must be nonblank. |
| outputType | String | No | Export format. Only png is supported when provided. |
| includeFurniture | Boolean | No | Whether to include furniture. |
Request example
{
"requestId": "req-floorplan-download-001",
"designId": "design_example_001",
"outputType": "png",
"includeFurniture": true
}
Response data: model
| Field | Type | Description |
|---|---|---|
| floorplanUrl | String | URL of the exported floor plan. Valid for 30 minutes. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"floorplanUrl": "https://assets.example.com/export/floorplan.png"
},
"traceId": "trace-example-001",
"requestId": "req-floorplan-download-001"
}
Export a Bill of Materials
POST /global/hs/api/floorplan/bill/download
Export the bill of materials for the current design version.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| designId | String | Yes | Design ID. Must be nonblank. |
| lang | String | No | Output language. Optional; use the values specified for your integration. |
| unit | String | No | Measurement unit. Optional; use the values specified for your integration. |
| filterOptions | String | No | Filter options. Optional; use the format specified for your integration. |
Request example
{
"requestId": "req-floorplan-bill-001",
"designId": "design_example_001"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| model | String | Download URL, returned directly as a string. Valid for 30 minutes. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": "https://assets.example.com/export/bill.xlsx",
"traceId": "trace-example-001",
"requestId": "req-floorplan-bill-001"
}
Usage notes
Omit the optional language, unit, and filter fields unless values have been specified for your integration.
AI Deco and Inspiration Library
List Inspiration Sample Rooms
POST /global/hs/api/ai/deco/inspiration/sample-room/list
Retrieve a paginated list of sample room IDs, English names, and cover images for AI Deco.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| roomCategory | Integer | Yes | Property scope: 1 for an entire home; 2 for a single room. |
| pageNo | Integer | Yes | Page number. Minimum: 1. |
| pageSize | Integer | Yes | Records per page. Range: 1–100. |
Request example
{
"requestId": "req-sample-room-list-001",
"roomCategory": 1,
"pageNo": 1,
"pageSize": 20
}
Response data: model
| Field | Type | Description |
|---|---|---|
| pagingData | Object | See Pagination. |
| data | Array | Records on the current page. |
| data[].id | String | Sample room ID. Use as templateId when submitting AI Deco. |
| data[].enName | String | English name of the sample room. |
| data[].cover | String | Cover image URL. Use the complete URL. Valid for 30 minutes. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"pagingData": {
"pageNo": 1,
"pageSize": 20,
"total": 1,
"hasMore": false
},
"data": [
{
"id": "9063",
"enName": "Modern Apartment",
"cover": "https://cdn.example.com/sample-room/9063.jpg?auth_key=TIMESTAMP-RAND-0-SIGNATURE"
}
]
},
"traceId": "trace-example-001",
"requestId": "req-sample-room-list-001"
}
Submit AI Deco
POST /global/hs/api/ai/deco/submit
Apply the selected sample room to the current version of a design owned by the current user.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| designId | String | Yes | Design ID. Must be nonblank. |
| templateId | String | Yes | Sample room ID from the id field returned by List Inspiration Sample Rooms. Must be nonblank. |
Request example
{
"requestId": "req-deco-submit-001",
"designId": "design_example_001",
"templateId": "9063"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| taskId | String | AI Deco task ID. Use it with Get AI Deco Results. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"taskId": "deco_example_001"
},
"traceId": "trace-example-001",
"requestId": "req-deco-submit-001"
}
Usage notes
Get AI Deco Results
POST /global/hs/api/ai/deco/result
Retrieve the AI Deco task status and the resulting design version on success.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| taskId | String | Yes | Task ID returned by Submit AI Deco. Must be nonblank. |
Request example
{
"requestId": "req-deco-result-001",
"taskId": "deco_example_001"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| status | Integer | -1: processing; 0: succeeded; 1: failed. |
| designId | String | Resulting design ID on success. Empty for other statuses. |
| versionId | String | Resulting design version ID on success. Empty for other statuses. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"status": 0,
"designId": "design_example_001",
"versionId": "v20261112120000"
},
"traceId": "trace-example-001",
"requestId": "req-deco-result-001"
}
Usage notes
Results are valid for 10 minutes.
Smart View and Design Rendering
Submit Smart View Generation
POST /global/hs/api/rendering/smart-view/submit
Generate cameras asynchronously for a design owned by the current user. Returns the task status after submission.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| designId | String | Yes | Design ID. Nonblank; maximum 100 characters. |
Request example
{
"requestId": "req-smart-view-submit-001",
"designId": "design_example_001"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| taskId | String | Smart View task ID. |
| designId | String | Design ID. |
| designVersion | String | Design version used to generate the cameras. Returned on success. |
| status | String | PROCESSING: processing; SUCCESS: succeeded; FAILED: failed. |
| viewerUrl | String | 3D Viewer URL returned on success. Includes token and scene=smart_view. Valid for 60 minutes. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"taskId": "a67a5809-98bd-4b21-9b52-1189cbdb84e1",
"designId": "design_example_001",
"designVersion": null,
"status": "PROCESSING",
"viewerUrl": null
},
"traceId": "trace-example-001",
"requestId": "req-smart-view-submit-001"
}
Get Smart View Results
POST /global/hs/api/rendering/smart-view/result
Poll a Smart View task. A successful response includes a viewer URL for previewing the cameras.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| taskId | String | Yes | Task ID returned by Submit Smart View Generation. Nonblank; maximum 100 characters. |
Request example
{
"requestId": "req-smart-view-result-001",
"taskId": "a67a5809-98bd-4b21-9b52-1189cbdb84e1"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| taskId | String | Smart View task ID. |
| designId | String | Design ID. |
| designVersion | String | Design version used to generate the cameras. Returned on success. |
| status | String | PROCESSING: processing; SUCCESS: succeeded; FAILED: failed. |
| viewerUrl | String | 3D Viewer URL returned on success. Includes token and scene=smart_view. Valid for 60 minutes. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"taskId": "a67a5809-98bd-4b21-9b52-1189cbdb84e1",
"designId": "design_example_001",
"designVersion": "v20261112120000",
"status": "SUCCESS",
"viewerUrl": "https://3dviewer.homestyler.com/api/?token=6505470d-339d-43ab-8d28-b13d3975d491&scene=smart_view"
},
"traceId": "trace-example-001",
"requestId": "req-smart-view-result-001"
}
Usage notes
Task status and results are valid for 10 minutes.
For iframe embedding and obtaining the camera ID for rendering, see the 3D Viewer Integration Guide.
Submit Design Rendering
POST /global/hs/api/rendering/submit
Submit rendering using a specific design version and a Smart View camera. The design ID and version must match those associated with the camera.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| designId | String | Yes | Design ID. Nonblank; maximum 100 characters. |
| designVersion | String | Yes | Design version returned by Smart View. Must be nonblank. |
| cameraId | String | Yes | Smart View camera ID. Nonblank; maximum 100 characters. Valid for 60 minutes. |
| imageSize | String | Yes | 1K, 2K, or 4K. Case-sensitive. |
| aspectRatio | String | No | 1:1, 9:16, 4:3, 3:4, 16:9, 2:1, or 5:6. Defaults to 4:3 when omitted or blank. |
Request example
{
"requestId": "req-render-submit-001",
"designId": "design_example_001",
"designVersion": "v20261112120000",
"cameraId": "a67a5809-98bd-4b21-9b52-1189cbdb84e1_1",
"imageSize": "2K",
"aspectRatio": "4:3"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| taskId | String | Rendering task ID. Use it with Get Rendering Tasks in a Batch. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"taskId": "render_example_001"
},
"traceId": "trace-example-001",
"requestId": "req-render-submit-001"
}
Usage notes
A successful submission means the task was accepted; it may still be queued. Rendering quotas or concurrency limits may prevent submission. Check success and msgCode; for example, 1009 indicates that the maximum number of unfinished rendering tasks has been reached.
Get Rendering Tasks in a Batch
POST /global/hs/api/rendering/result/batch
Retrieve the statuses and results of multiple rendering tasks in one request.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| taskIds | Array<String> | Yes | 1–100 rendering task IDs returned by Submit Design Rendering. Each entry must be nonblank. |
Request example
{
"requestId": "req-render-result-batch-001",
"taskIds": [
"render_example_001"
]
}
Response data: model
| Field | Type | Description |
|---|---|---|
| model | Array | Matching task records. Missing tasks may be omitted. Match records by taskId, not array position. |
| model[].taskId | String | Rendering task ID. |
| model[].status | Integer | 99: queued; 0: processing; 2: succeeded; 3: failed (including timeouts). The final image is available only after rendering succeeds. |
| model[].resultUrl | String | Rendered image URL. Empty before the image is available. Valid for 30 minutes. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": [
{
"taskId": "render_example_001",
"status": 2,
"resultUrl": "https://cdn.example.com/render/result.jpg?auth_key=TIMESTAMP-RAND-0-SIGNATURE"
}
],
"traceId": "trace-example-001",
"requestId": "req-render-result-batch-001"
}
List Rendering Resources
POST /global/hs/api/rendering/list
Retrieve rendering resources for a design owned by the current user.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| projectId | String | Yes | Design ID. Nonblank; maximum 100 characters. |
| pageNo | Integer | Yes | Must be 1. |
| pageSize | Integer | Yes | Range: 1–200. |
| renderType | String | No | image, aerial, or topview. No type filter is applied when omitted. |
Request example
{
"requestId": "req-render-list-001",
"projectId": "design_example_001",
"pageNo": 1,
"pageSize": 20,
"renderType": "image"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| pagingData | Object | See Pagination. |
| data | Array | Records on the current page. |
| data[].renderId | String | Rendering resource ID. |
| data[].url | String | Rendering resource URL. Retain all authentication query parameters. Valid for 30 minutes. |
| data[].renderType | String | Rendering type. |
| data[].subRenderType | String | Rendering subtype. Use the returned value. May be empty. |
| data[].status | Integer | 99: queued; 0: processing; 2: succeeded; 3: failed (including timeouts). The final image is available only after rendering succeeds. |
| data[].createTime | Long | Reserved field. Creation time is not currently provided. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"pagingData": {
"pageNo": 1,
"pageSize": 20,
"total": 1,
"hasMore": false
},
"data": [
{
"renderId": "render_example_001",
"url": "https://cdn.example.com/render/result.jpg?auth_key=TIMESTAMP-RAND-0-SIGNATURE",
"renderType": "image",
"subRenderType": null,
"status": 2,
"createTime": null
}
]
},
"traceId": "trace-example-001",
"requestId": "req-render-list-001"
}
Usage notes
renderType supports image, aerial, and topview. pageNo must be 1, and pageSize must not exceed 200.
AI Tools
Retrieve results for these tools through /ai/status. Do not use /ai/deco/result or /rendering/result/batch for these tasks.
Available templates, tags, and parameter combinations depend on the generation capabilities enabled for your account.
Submission returns a numeric task ID as a String. The query request and response use Long for taskId. Preserve integer precision when handling these identifiers.
Submit AI Render
POST /global/hs/api/ai/render/submit
Submit an AI image rendering task. For rendering from a design and camera, use /rendering/submit instead.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| originImageUrl | String | No | Content reference image URL. Must be accessible and pass URL safety validation. |
| designId | String | No | Design ID to associate with this task. The design must belong to the current user. Supply any reference image separately through originImageUrl. |
| renderType | String | Yes | INDOOR: interior; OUTDOOR: exterior; ANNOTATION: annotated image. Case-sensitive; no default. |
| aspectRatio | String | No | Image aspect ratio: 1:1, 9:16, 4:3, 3:4, or 16:9, using an ASCII colon. Defaults to 16:9 when omitted or blank. |
| imageSize | String | No | 2K or 4K. Defaults to 2K. |
| userPrompt | Array<Object> | No | Prompt entries as a JSON array. Omit or pass an empty array to use the default prompt for the selected renderType. Text and tag entries may be used separately or together. |
| userPrompt[].type | String | Yes, for each entry | text: free text; tag: a tag code for the selected renderType. |
| userPrompt[].value | String | Yes, for each entry | Required and cannot be null. For text, an empty string is allowed. For tag, use a code from the table below for the selected renderType. |
Tag codes
| renderType | Category | Selection | Codes |
|---|---|---|---|
| INDOOR | Lighting | Single | dawn, morning, dusk, night, rainy, cinematic |
| INDOOR | Outdoor view | Single | first_floor_courtyard, suburban_house, apartment_community, city_skyline, european_old_town, forest_lake |
| INDOOR | Extras | Multiple | add_people, add_pets, add_depth_of_field, add_accessories, add_water |
| INDOOR | Holiday | Single | christmas, valentines, super_bowl |
| OUTDOOR | Lighting | Single | dawn, morning, dusk, night, rainy, foggy |
| OUTDOOR | Outdoor view | Single | city_street, suburb_view, city_park, coastal, mountains, forest |
| OUTDOOR | Extras | Multiple | add_people, add_vehicles, enrich_plants, add_depth_of_field |
| OUTDOOR | Season | Single | spring, summer, autumn, winter |
| OUTDOOR | Holiday | Single | valentines, halloween, thanksgiving, christmas |
| ANNOTATION | Drawing style | Single | realistic, watercolor, line_drawing |
| ANNOTATION | Annotation targets | Multiple | lighting, furniture |
Unknown tag codes or codes for another renderType return 1001. Each prompt entry must be an object with type and value.
Request example
{
"requestId": "req-ai-render-submit-001",
"originImageUrl": "https://assets.example.com/room.png",
"designId": "design_example_001",
"userPrompt": [
{
"type": "text",
"value": "A modern living room in bright natural light"
},
{
"type": "tag",
"value": "morning"
}
],
"aspectRatio": "16:9",
"imageSize": "2K",
"renderType": "INDOOR"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| taskId | String | Main task ID as a string. Pass this ID to /ai/status. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"taskId": "180000001"
},
"traceId": "trace-example-001",
"requestId": "req-ai-render-submit-001"
}
Submit AI Moodboard
POST /global/hs/api/ai/moodboard/submit
Generate a moodboard from an image or text.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| templateCode | String | Yes | Preset template code: stylePoster, minimalPresentation, corkboardCollage, comprehensiveDesignBoard, framedCollage, moodGrid, materialBoard, stylingBoard. Nonblank; freeMode and custom templates are not supported. |
| imageUrl | String | No | Content reference image URL. If supplied, generation uses the image; otherwise, provide a nonblank userPrompt for text-based generation. |
| userPrompt | String | Conditional | Plain-text description. Required and nonblank when imageUrl is omitted or blank. |
| aspectRatio | String | No | Image aspect ratio: 1:1, 9:16, 4:3, 3:4, or 16:9, using an ASCII colon. Defaults to 1:1 when omitted or blank. |
| imageSize | String | No | 2K or 4K. Defaults to 2K. |
Request example
{
"requestId": "req-ai-moodboard-submit-001",
"userPrompt": "A living room moodboard with warm white, light oak, and linen",
"templateCode": "stylePoster",
"aspectRatio": "1:1",
"imageSize": "2K"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| taskId | String | Main task ID as a string. Pass this ID to /ai/status. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"taskId": "180000002"
},
"traceId": "trace-example-001",
"requestId": "req-ai-moodboard-submit-001"
}
Submit AI Floorplan
POST /global/hs/api/ai/floorplan/submit
Generate a floor plan from text and layout preferences.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| area | String | No | Area with units, such as 120 m² or 1500 ft². ft², sqft, and sq ft indicate square feet; other unit text is interpreted as square meters. |
| bedrooms | Integer | No | Number of bedrooms. Defaults to 2. |
| bathrooms | Integer | No | Number of bathrooms. Defaults to 1. |
| kitchenType | String | No | open: open kitchen; closed: enclosed kitchen. Defaults to open. |
| extras | String | No | Additional spaces, separated by commas: walk-in closet, laundry room, storage room, utility room, home office, garage, double car garage, pantry, combined living-dining, balcony, media room, gym. |
| userPrompt | String | No | Additional requirements in plain text. |
| styleType | String | No | blackWhite: minimalist black and white; realistic: modern realistic. Defaults to blackWhite. |
Request example
{
"requestId": "req-ai-floorplan-submit-001",
"bedrooms": 2,
"bathrooms": 1,
"userPrompt": "Design a two-bedroom apartment with connected living and dining areas and well-lit bedrooms",
"styleType": "blackWhite",
"area": "120 m²",
"kitchenType": "open",
"extras": "balcony,home office"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| taskId | String | Main task ID as a string. Pass this ID to /ai/status. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"taskId": "180000003"
},
"traceId": "trace-example-001",
"requestId": "req-ai-floorplan-submit-001"
}
Submit AI Modeler
POST /global/hs/api/ai/modeler/submit
Generate a model from an image or text. Retrieve the model result through the AI task status endpoint after processing completes.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| originalImageUrl | String | Conditional | Source image URL. Exactly one of originalImageUrl and userPrompt must be nonblank. The image must pass review. |
| userPrompt | String | Conditional | Plain-text description. Exactly one of userPrompt and originalImageUrl must be nonblank. |
| length | Integer | No | Model length. Use the measurement unit specified for model generation; no unit conversion is applied. |
| width | Integer | No | Model width. Use the measurement unit specified for model generation; no unit conversion is applied. |
| height | Integer | No | Model height. Use the measurement unit specified for model generation; no unit conversion is applied. |
Request example
{
"requestId": "req-ai-modeler-submit-001",
"userPrompt": "A wooden dining chair with a curved backrest"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| taskId | String | Main task ID as a string. Pass this ID to /ai/status. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"taskId": "180000004"
},
"traceId": "trace-example-001",
"requestId": "req-ai-modeler-submit-001"
}
Usage notes
Providing both nonblank inputs, or neither, returns 1001.
Submission returns the main task taskId. Retrieve modelId and glbUrl through the status endpoint. A task ID is not a model ID.
Get AI Task Status
POST /global/hs/api/ai/status
Retrieve main task and subtask details for the user associated with your AppKey.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| taskId | Long | Yes | Positive integer. Use the main task ID returned by an AI tool submission endpoint. |
| lang | String | No | Reserved field. Does not currently set the language of generated results or the preview page. |
Request example
{
"requestId": "req-ai-status-001",
"taskId": 180000001
}
Response data: model
| Field | Type | Description |
|---|---|---|
| taskId | Long | Main task ID. |
| status | Integer | Main task status: 0: waiting; 1: processing; 2: succeeded. Also check each subtask's status. |
| imageResultList | Array | Subtask results. An empty array when no results are available. |
| imageResultList[].subTaskId | Long | Subtask ID. |
| imageResultList[].processStatus | Integer | 0: queued; 1: processing; 2: succeeded; 3: generation failed; 4: entitlement check failed; 5: timed out. |
| imageResultList[].imageUrl | String | Image URL returned after approval. Empty if no image is available or review has not passed. Valid for 30 minutes. |
| imageResultList[].modelId | String | Saved Modeler model ID. Empty if review has not passed or the ID is unavailable. |
| imageResultList[].modelStatus | String | Modeler model status as text. Empty if unavailable. |
| imageResultList[].glbUrl | String | Modeler GLB file URL. Empty if the file is not ready or review has not passed. Valid for 30 minutes. |
| imageResultList[].viewerToken | String | Temporary Modeler preview token. Valid for 60 minutes. |
| imageResultList[].viewerUrl | String | Modeler preview URL available through this query after generation. May be empty. Valid for 60 minutes. For embedding, see the 3D Viewer Integration Guide. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"taskId": 180000001,
"status": 2,
"imageResultList": [
{
"subTaskId": 180000101,
"processStatus": 2,
"imageUrl": "https://cdn.example.com/ai/result.jpg?auth_key=TIMESTAMP-RAND-0-SIGNATURE",
"modelId": null,
"modelStatus": null,
"glbUrl": null,
"viewerToken": null,
"viewerUrl": null
}
]
},
"traceId": "trace-example-001",
"requestId": "req-ai-status-001"
}
Usage notes
The outer success=true indicates that the query succeeded. Check each subtask's processStatus for its generation status. Open the returned viewerUrl to preview the model.
3D Viewer
Get a Design Viewer URL
POST /global/hs/api/project/viewer
Get a 3D preview URL for a design owned by the user associated with your AppKey. Smart View generation is not required.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| requestId | String | Yes | Request identifier. Nonblank; maximum 60 characters. |
| designId | String | Yes | Design ID. Nonblank; maximum 100 characters. Must belong to the current user. |
Request example
{
"requestId": "req-project-viewer-001",
"designId": "design_example_001"
}
Response data: model
| Field | Type | Description |
|---|---|---|
| viewerUrl | String | 3D Viewer URL containing token and scene=design_view. The token is valid for 60 minutes. |
Response example
{
"success": true,
"msgCode": "0",
"msgInfo": "success",
"model": {
"viewerUrl": "https://3dviewer.homestyler.com/api/?token=59f84d7c-96f5-419b-9d59-67219d97064a&scene=design_view"
},
"traceId": "trace-example-001",
"requestId": "req-project-viewer-001"
}
Usage notes
Open the URL to preview the design.
For iframe embedding, URL options, and event handling, see the 3D Viewer Integration Guide.
3D Viewer Integration Guide
Embed 3D Viewer in your page using an iframe. The viewer sends loading status and camera selection events to the parent page through postMessage. The browser must support WebGL.
Obtain a Preview URL
| scene | Preview | viewerUrl source | Smart camera list |
|---|---|---|---|
| smart_view | Smart View | model.viewerUrl from Get Smart View Results |
Supported |
| design_view | Design | model.viewerUrl from Get a Design Viewer URL |
Not supported |
| aimodeler | Generated model | After submitting AI Modeler, retrieve model.imageResultList[].viewerUrl through Get AI Task Status |
Not supported |
Use the complete viewerUrl returned by the API. It already contains token and scene. The viewer page is https://3dviewer.homestyler.com/api/; retain the trailing slash in /api/.
Embed the iframe and Listen for Events
Give the container explicit dimensions. Register the listener before assigning the API's viewerUrl to the iframe's src:
<div style="width: 100%; height: 600px;">
<iframe
id="hs-viewer"
style="width: 100%; height: 100%; border: 0;"
title="Homestyler 3D Viewer"
></iframe>
</div>
function mountViewer(viewerUrl) {
const iframe = document.getElementById('hs-viewer');
const url = new URL(viewerUrl);
const viewerOrigin = url.origin;
const onMessage = (event) => {
// Validate the message origin and the sending iframe.
if (event.origin !== viewerOrigin) return;
if (event.source !== iframe.contentWindow) return;
const message = event.data;
if (!message || typeof message.event !== 'string') return;
switch (message.event) {
case 'loaded':
console.log('Viewer loaded');
break;
case 'camera-selected':
// Use data.id as cameraId when submitting design rendering.
console.log('Selected camera:', message.data);
break;
case 'token-invalid':
console.warn('Preview link is invalid or expired');
break;
case 'error':
case 'source-not-found':
case 'source-not-supported':
console.error('Viewer loading failed:', message);
break;
}
};
window.addEventListener('message', onMessage);
iframe.src = url.toString();
// Call the returned function when the parent component unmounts.
return () => window.removeEventListener('message', onMessage);
}
Validate both event.origin and event.source. If you embed multiple viewers, identify the sending iframe using event.source.
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| token | Yes | Included in the viewerUrl returned by the API. Valid for 60 minutes. |
| scene | Yes | smart_view, design_view, or aimodeler. Case-sensitive; no default. Use the token and scene from the same viewerUrl. |
| autoRotate | No | 1 enables rotation; 0 disables it. Enabled by default for aimodeler and disabled for other scenes. |
| bg | No | Six-digit hexadecimal background color, such as f5f5f5. Encode # as %23 if writing it directly into the URL. |
| camera | No | smart or fit; defaults to fit. Applies only to smart_view. fit shows the entire scene; smart selects the first smart camera after loading. |
Use URL to change optional parameters while preserving the existing query parameters:
const iframe = document.getElementById('hs-viewer');
const url = new URL(viewerUrl);
url.searchParams.set('bg', 'f5f5f5');
url.searchParams.set('autoRotate', '0');
iframe.src = url.toString();
Message Structure and Events
Messages are objects identified by the event field. The fields are listed below. Ignore unknown fields.
| Field | Type | Description |
|---|---|---|
| event | String | Event name. |
| type | String | Optional. Some events return scene or aimodel; these differ from the URL scene values. |
| code | String | Optional. Error code provided by some error events. |
| message | String | Optional. Error message provided by some error events. |
| data | Object / Array | Optional. Structure depends on the event. |
| Event | Trigger | Data |
|---|---|---|
| ready | Viewer initialization completes | No data; type is scene or aimodel. |
| loading | Loading starts or resources finish loading | data.stage is loading or loaded. Use the loaded event as the final completion signal. |
| progress | Loading progress changes | data.percent is a number; data.stage is scene or model. |
| smart-cameras | Smart camera list becomes available | data is a camera array, returned only for smart_view. See the structure below. |
| loaded | Scene or model and initial view are ready | No data; type is scene or aimodel. |
| camera-changed | User clicks a smart camera | data is an object containing id. |
| camera-selected | User clicks a smart camera | data is the full camera object described below. |
| token-missing | URL has no token | No data. |
| token-invalid | Token is invalid, expired, or does not match scene | No fixed structure; usually includes code, message, and data.scene. |
| params-invalid | A parameter is missing or invalid | Usually includes code and message. |
| source-not-found | Scene or model resource does not exist | Usually includes code and message. |
| source-not-supported | scene is unsupported | Usually includes code, message, and data.scene. |
| error | Another loading or rendering error occurs | Usually includes code and message. |
| disposed | Viewer page is about to unload | No data. |
loaded indicates that resources and the initial view are ready; it does not guarantee that the next frame has been drawn. Viewer event code and HTTP API msgCode are separate fields; handle viewer errors according to their events.
Load completion example:
{
"event": "loaded",
"type": "scene"
}
Smart Camera Data and Rendering
When a user clicks a camera, the viewer emits camera-changed followed by camera-selected as the transition animation starts. camera-selected is triggered only by a user click; initial selection with camera=smart does not trigger it. design_view and aimodeler do not emit camera click events.
Fields in camera-selected.data:
| Field | Type | Description |
|---|---|---|
| id | String | Camera ID. Pass as cameraId to Submit Design Rendering. |
| name | String | Optional. Camera name. |
| group | String | Optional. Camera group name. |
| roomId | String | Optional. Room ID. |
| roomTypeDisplayName | String | Optional. Room type display name. |
| camera | Object | Camera parameters. |
| camera.pos | Array<Number> | Camera position. |
| camera.target | Array<Number> | Camera target point. |
| camera.up | Array<Number> | Optional. Up vector. |
| camera.fov | Number | Optional. Field of view. |
| camera.near | Number | Optional. Near clipping plane. |
| camera.far | Number | Optional. Far clipping plane. |
| camera.aspect | Number | Optional. Aspect ratio. |
| camera.pitch | Number | Optional. Pitch. |
{
"event": "camera-selected",
"data": {
"id": "a67a5809-98bd-4b21-9b52-1189cbdb84e1_1",
"name": "Living Room Camera 1",
"group": "Living Room Camera 1",
"roomId": "1",
"roomTypeDisplayName": "Living Room",
"camera": {
"pos": [100.0, 150.0, -200.0],
"target": [0.0, 100.0, 0.0],
"up": [0, 1, 0],
"fov": 60,
"near": 0.1,
"far": 10000,
"aspect": 1.7778,
"pitch": 0
}
}
}
smart-cameras.data is a camera array. Each entry has the following structure, with camera parameters as defined above:
| Field | Type | Description |
|---|---|---|
| id | String | Camera ID. |
| roomId | String | Room ID. |
| roomName | String | Camera or room display name. |
| camera | Object | Camera parameters. |
{
"event": "smart-cameras",
"data": [
{
"id": "a67a5809-98bd-4b21-9b52-1189cbdb84e1_1",
"roomId": "1",
"roomName": "Living Room Camera 1",
"camera": {
"pos": [100.0, 150.0, -200.0],
"target": [0.0, 100.0, 0.0],
"fov": 60,
"near": 0.1,
"far": 10000
}
}
]
}
Listen to camera-changed if you only need the camera ID. Use smart-cameras to display the list before a user clicks. With camera=smart, the first list entry identifies the initial camera. To submit rendering, pass the selected camera's id as cameraId, together with the designId and designVersion returned by Get Smart View Results.
Error Handling and Limitations
- On token-invalid, obtain a valid preview URL and update the iframe's src.
- On error, source-not-found, or source-not-supported, display a message or retry action in the parent page. The viewer hides the progress bar and remains blank without displaying an error dialog.
- Preview URLs contain access credentials. Avoid logging, tracking, or publicly displaying them.
- Panoramic cameras, transparent backgrounds, and material editing are not supported. aimodeler does not support material replacement or SKU editing.
Polling and Failure Handling
- Save the task ID after successful submission and use the query endpoint for that workflow.
- Check the outer
successfield, then the task status. A successful query does not necessarily mean that the task succeeded. - Poll within your rate limit and set a deadline. Do not poll indefinitely while a task is processing.
- Save result identifiers and retrieve required files promptly. Temporary URLs are not permanent resource addresses.
- If a submission times out and its outcome is unknown, do not assume that no task was created. requestId does not provide idempotency guarantees; resubmitting may create another task.
Error Handling
Business errors use the common response structure. The table below lists the main error codes. msgInfo may contain additional validation or failure details.
| msgCode | Meaning | Recommended Action |
|---|---|---|
| "1000" | System error | Retain requestId and traceId. Retry as appropriate for the operation. |
| "1001" | Invalid request parameters or missing authentication information | Check headers, required fields, types, and ranges. |
| "1005" | Plan expired or unavailable | Check your account's service validity period. |
| "1006" | Invalid user information | Check your account information. |
| "1007" | AppKey is invalid or unavailable | Check the AppKey created in your personal management console. |
| "1008" | Endpoint does not exist or is not enabled | Check the endpoint path and access entitlement. |
| "1009" | Too many tasks in progress | Wait for existing tasks to finish before submitting more. |
| "1010" | Design does not exist | Check the design ID. |
| "1011" | Request rate limit exceeded | Reduce request frequency. |
| "1012" | Daily request quota exceeded | Follow your daily quota policy. |
| "1013" | Monthly request quota exceeded | Follow your monthly quota policy. |
| "1014" | Insufficient rendering or AI generation entitlement | Check your account's generation entitlement. |
| "1015" | Operation is too frequent; request cannot be processed at this time | Retry later. |
| "1016" | Account does not meet the endpoint's access requirements | Check that your account has the required membership benefits. |
| "1101" | AI tool submission failed | Retain tracing information for troubleshooting. |
| "1102" | AI tool task query failed | Retain the task ID and query again later. |
| "1103" | Input image did not pass review | Provide a compliant input image. |
| "1401" | Access denied | Check resource ownership and account permissions. |
| "1502" | Data not found, expired, or unavailable | Check the resource ID and account. Regenerate expired cameras or tasks. |
| "1503" | AI scene not supported by this query endpoint | Use the endpoint for the relevant scene. |
| "1506" | Design version does not match the camera version | Use the designVersion associated with the camera. |
msgCode uses the numeric error codes above, returned as strings.
Example response when the rendering task limit is reached:
{
"success": false,
"msgCode": "1009",
"msgInfo": "processing task count exceeded limit",
"model": null,
"traceId": "trace-example-002",
"requestId": "req-render-submit-001"
}

