Overview

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:

http
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
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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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
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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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:

html
<div style="width: 100%; height: 600px;">
  <iframe
    id="hs-viewer"
    style="width: 100%; height: 100%; border: 0;"
    title="Homestyler 3D Viewer"
  ></iframe>
</div>
js
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:

js
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:

json
{
  "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.
json
{
  "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.
json
{
  "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

  1. Save the task ID after successful submission and use the query endpoint for that workflow.
  2. Check the outer success field, then the task status. A successful query does not necessarily mean that the task succeeded.
  3. Poll within your rate limit and set a deadline. Do not poll indefinitely while a task is processing.
  4. Save result identifiers and retrieve required files promptly. Temporary URLs are not permanent resource addresses.
  5. 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:

json
{
  "success": false,
  "msgCode": "1009",
  "msgInfo": "processing task count exceeded limit",
  "model": null,
  "traceId": "trace-example-002",
  "requestId": "req-render-submit-001"
}