API Reference

4 HTTP API Definitions

4.1 Create a single-map reconstruction job

Request parameters

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/start_reconstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
     "accessKey": "y6vera"                  //Required. The API authentication KEY specified when the container was started
    ,"name": "job1"                        //Required. Job name
    ,"inputFolder": "/work/job001/input"    //Required. Path of the input data directory used for reconstruction (the path as mounted inside Docker)
    ,"outputFolder": "/work/job001/output"  //Required. Path of the reconstruction output destination directory (the path as mounted inside Docker)
    ,"hookUrl":"http://localhost:8080/lcc_cloud/job_progress_hook_sample" //Hook URL for execution status synchronization
    ,"quality":"M"                     //Required. Quality: "H" = high, "M" = medium, "L" = low
    ,"maximumGaussianPoint": 8         //Maximum number of Gaussian points, 8-50
    ,"lowMemory":0                //Whether to enable low-memory reconstruction: 0/1. Default is 0 (disabled), 1 enables it
    ,"exposure":0               //Whether to enable exposure optimization: 0/1. Default is 0 (disabled), 1 enables it
    ,"portability":"ON"                //Whether to enable cross-platform optimization: "ON/OFF". Enabled by default
    ,"pointCloudParticipationRate":"H" //PPR feature, "H" = high, "L" = low. Default is high. This is how much the point cloud participates in reconstruction.
    ,"jobQueueEnabled":1               //0: fail immediately if the server is currently busy. 1: allow the job to join the queue and wait its turn. When creating a single-map reconstruction job, this parameter defaults to 0 if omitted
    ,"hdImageFolder": "/work/job001/output"  //Folder for HD supplementary images. This is an advanced feature and requires a license, otherwise the parameter has no effect.
    ,"lccAiConfig":1 // 0 = disabled, 1 = enable AI spatial understanding. Beta feature, currently supports indoor scenes only. This is an advanced feature and requires a license, otherwise it must always be left at 0.
    ,"developerDataOutput":"ON" //Whether to output developer data ("ON" / "OFF"). Defaults to OFF when omitted. This is an advanced feature and requires a license, otherwise the parameter has no effect. See [Appendix: Developer Data]
    ,"createJobFolder":"ON"             //Whether to create a subdirectory named after the job under outputFolder: "ON"/"OFF"
    ,"lioMode":""                        //LIO special mode: "" auto / "0" none / "1" robust / "2" narrow scene
    ,"executionNodes":["192.168.11.11:8080","192.168.11.11:8081"]//In cluster mode, selects which nodes in the cluster may run this job
}'

Note:
1. Mind whether a parameter field is a string or a number; using the wrong type causes a parameter format error.
2. If a required parameter field is missing, adding or running the job will fail.
3. While a reconstruction job runs, the /work directory on the container node needs 5x the size of the input data in free disk space, otherwise the job may fail.

Required (enforced by the code): accessKey, name, inputFolder, outputFolder.
(quality defaults to M; maximumGaussianPoint defaults to 12; hookUrl, hdImageFolder and similar are optional advanced items.)

Response parameters

{
    "code":0,     // 0 means the API call succeeded; any other value means an unexpected error occurred
    "msg":"",     // On error, the message is returned here
    "data":{
        "bizCode": 0,  //Business return code: 0 = started or queued successfully, 1 = another job is running and it cannot start. For other error codes see the bizMsg response
        "bizMsg": "",  //Business processing message
        "jobId":"xxxx" //Current jobID, generated by the system at startup. Whether a job can be recovered depends on whether the database and the related working directories are persisted; it cannot be recovered if the container is deleted without a persisted database
    }
}

List of INPUT data validation error codes

For the error codes and error messages that input data validation can return, see the latest error code list document Appendix - Error Code List.

4.2 Create a multi-map fusion / air-ground fusion reconstruction job

Request parameters

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/start_multi_reconstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey": "y6vera"      //Required. The API authentication KEY specified when the container was started
    ,"name": "job1"            //Required. Job name
    ,"outputFolder": "/work/job001/output"  //Required. Path of the reconstruction output destination directory (the path as mounted inside Docker)
    ,"quality":"M"                     //Required. Quality: "H" = high, "M" = medium, "L" = low
    ,"maximumGaussianPoint": 8         //Maximum number of Gaussian points, 8-50
    ,"exposure":0               //Whether to enable exposure optimization: 0/1. Default is 0 (disabled), 1 enables it
    ,"portability":"ON"                // Whether to enable cross-platform optimization: "ON/OFF". Enabled by default
    ,"pointCloudParticipationRate":"H" // PPR feature, "H" = high, "L" = low. Default is high. This is how much the point cloud participates in reconstruction.
    ,"subTasks":[                        //Required.
        {
            "inputFolder":"/work/indoor-multi/1",   //Required. Path of the input data directory used for reconstruction (the path as mounted inside Docker)
        },
        {
            "inputFolder":"/work/indoor-multi/2",
        },
        ...
    ]
    ,"droneFolder":"/work/multi/4"           //Required for air-ground fusion. Storage directory for drone images; requires license support, otherwise the parameter has no effect.
    ,"hookUrl":"http://localhost:8080/lcc_cloud/job_progress_hook_sample" //Hook URL for execution status synchronization
    ,"jobQueueEnabled":1  //0: fail immediately if the server is currently busy. 1: allow the job to join the queue and wait its turn. When creating a multi-map reconstruction job, this parameter defaults to 1 if omitted
    ,"developerDataOutput":"ON" //Whether to output developer data ("ON" / "OFF"). Defaults to OFF when omitted. This is an advanced feature and requires a license.
    ,"createJobFolder":"ON"             //Whether to create a subdirectory named after the job under outputFolder: "ON"/"OFF"
    ,"lioMode":""                        //LIO special mode: "" auto / "0" none / "1" robust / "2" narrow scene
    ,"multiNodeRun":"ON" //In cluster mode, whether this job may use multi-node parallel computation for acceleration ("ON" / "OFF"). Defaults to "ON" in cluster mode; the parameter has no effect outside cluster mode.
    ,"executionNodes":["192.168.11.11:8080","192.168.11.11:8081"] //In cluster mode, selects which nodes in the cluster may run this job
}'

Note:
1. Mind whether a parameter field is a string or a number; using the wrong type causes a parameter format error.
2. If a required parameter field is missing, adding or running the job will fail.
3. While a reconstruction job runs, the /work directory on the container node needs 5x the size of the input data in free disk space, otherwise the job may fail.

Map fusion only: pass just subTasks[].
Air-ground fusion: additionally add "droneFolder": "/work/multi/drone" (switches to air-ground fusion automatically, requires a license).

Required (enforced by the code): accessKey, name, subTasks[] (1-50 entries); outputFolder must be a writable path.
(quality defaults to M)

Response parameters

{
    "code":0,     // 0 means the API call succeeded; any other value means an unexpected error occurred
    "msg":"",     // On error, the message is returned here
    "data":{
        "bizCode": 0,//Business return code: 0 = started or created successfully, 1 = another job is running and it cannot start. For other error codes see the bizMsg response
        "bizMsg": "", //Business processing message
        "jobId":"xxxx" //Current jobID, generated by the system at startup. Whether a job can be recovered depends on whether the database and the related working directories are persisted; it cannot be recovered if the container is deleted without a persisted database
    }
}

4.3 Check reconstruction status (for polling)

When starting a reconstruction, the execution status can be synchronized automatically through the hookUrl parameter.

You can also poll with this API.

Request parameters

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/check_reconstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey": "y6vera",     //Required. The API authentication KEY specified when the container was started
    "jobId":"xxxx"             //Current jobID. If this parameter is omitted, the status of the current job is returned directly
}

Response parameters

{
    "code":0,     // 0 means the API call succeeded; any other value means an unexpected error occurred
    "msg":"",     // On error, the message is returned here
    "data":{
        "bizCode": 0,//Business return code: 0 = no information for this job, 1 = this job is running, 2 = this job finished normally. Other values indicate an error, see bizMsg for details
        "bizMsg": "", //Business processing message
        "jobId":"xxxx", //Queried jobID
        "jobName":"xxxx",
        "progress":"<progress>" //Progress
    }
}

4.4 Sample HOOK API for reconstruction status synchronization

If you need the image to automatically synchronize the execution status of the current JOB to another business system on a schedule,

build an HTTP POST API on the business system that accepts the request format of this API, and pass its URL as the hookUrl parameter when starting the reconstruction.

Request parameters

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/job_progress_hook_sample' \
--header 'Content-Type: application/json' \
--data-raw '{
        "bizCode": 0,     //1 = job is running, 2 = job finished normally. Other values indicate an error, see bizMsg for details
        "bizMsg": "",     //Business processing message
        "jobId":"xxxx"    //Currently running jobID
        "progress":"<progress>" //Progress
}'

Response parameters

The Hook API may return anything; the LCC system does not process it.

4.5 Restart a reconstruction job

Request parameters

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/resume_reconstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey": "y6vera"      //Required. The API authentication KEY specified when the container was started
   ,"jobId":"xxxx"             //Required. The jobID of the job to restart
}

Note:
If the container crashes unexpectedly, the job is aborted but its status cannot be updated to FAIL in time and stays as MODELING.
In that case you can also use this API to force this abnormal job to restart and continue running

Response parameters

{
    "code":0,     // 0 means the API call succeeded; any other value means an unexpected error occurred
    "msg":"",     // On error, the message is returned here
    "data":{
        "bizCode": 0,//Business return code: 0 = success. Other values indicate an error, see bizMsg for details
        "bizMsg": "", //Business processing message
    }
}

4.6 Delete a job that is not running

Request parameters

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/job_delete' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey": "y6vera"      //Required. The API authentication KEY specified when the container was started
   ,"jobId":"xxxx"             //Required. The jobID of the job to restart
}

Response parameters

{
    "code":0,     // 0 means the API call succeeded; any other value means an unexpected error occurred
    "msg":"",     // On error, the message is returned here
    "data":{
        "bizCode": 0,//Business return code: 0 = success. Other values indicate an error, see bizMsg for details
        "bizMsg": "", //Business processing message
    }
}

4.7 Enable or disable automatic job queue execution

Request parameters

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/job_queue_control' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey": "y6vera"     //Required. The API authentication KEY specified when the container was started
   ,"jobQueueControl":"ON"    //"ON" enables it; "OFF" disables it; any other value is ignored and only the current status is returned
}

Response parameters

{
    "code":0,     // 0 means the API call succeeded; any other value means an unexpected error occurred
    "msg":"",     // On error, the message is returned here
    "data":{
        "bizCode": 0,//Business return code: 0 = success. Other values indicate an error, see bizMsg for details
        "bizMsg": "", //Business processing message
        "jobQueueEnabled":true  //Whether the current server automatically processes jobs in the queue
    }
}

4.8 Create an aerial reconstruction job

Request parameters

curl --location --request POST 'http://127.0.0.1:8081/lcc_cloud/start_aerial_reconstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey":"y6vera"    //Required. The API authentication KEY specified when the container was started
    ,"name":"AerialTestJob"   //Required. Job name
    ,"droneFolder":"/data/lcc-test-data/k1/images" //Required. Path of the input drone images (the path as mounted inside Docker)
    ,"outputFolder": "/work/job001/output"          //Required. Path of the reconstruction output destination directory (the path as mounted inside Docker)
    ,"quality":"H"            //Required. Quality: "H" = high, "M" = medium, "L" = low
    ,"maximumGaussianPoint": 8               //Maximum number of Gaussian points, 8-50
    ,"exposure":0               //Whether to enable exposure optimization: 0/1. Default is 0 (disabled), 1 enables it
    ,"portability":"ON"          //Whether to enable cross-platform optimization: "ON"/"OFF", enabled by default
    ,"createJobFolder":"ON"       //Whether to create a subdirectory named after the job under outputFolder: "ON"/"OFF"
    ,"multiNodeRun":"ON"          //In cluster mode, whether multi-node parallel computation is allowed for acceleration
    ,"hookUrl":"http://localhost:8080/lcc_cloud/job_progress_hook_sample" //Hook URL for execution status synchronization
    ,"executionNodes":["192.168.11.11:8080","192.168.11.11:8081"]
}'

Note:
1. Mind whether a parameter field is a string or a number; using the wrong type causes a parameter format error.
2. If a required parameter field is missing, adding or running the job will fail.
3. While a reconstruction job runs, the /work directory on the container node needs 5x the size of the input data in free disk space, otherwise the job may fail.

Required (enforced by the code): accessKey, name, droneFolder, outputFolder (must be writable).
(quality defaults to M.)

Response parameters

{
    "code":0,     // 0 means the API call succeeded; any other value means an unexpected error occurred
    "msg":"",     // On error, the message is returned here
    "data":{
        "bizCode": 0,//Business return code: 0 = success. Other values indicate an error, see bizMsg for details
        "bizMsg": "", //Business processing message
        "jobQueueEnabled":true  //Whether the current server automatically processes jobs in the queue
    }
}

4.9 Force-abort a reconstruction job

Forcibly aborts a running job. Note that because the process is killed, the job ends abnormally and enters the "FAIL" state.

You can restart it later with the [Restart a reconstruction job] API, which resumes from the last successfully completed step.

Request parameters

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/stop_reconstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey": "y6vera"      //Required. The API authentication KEY specified when the container was started
   ,"jobId":"xxxx"             //Required. The jobID of the job to force-abort
}

Response parameters

{
    "code":0,     // 0 means the API call succeeded; any other value means an unexpected error occurred
    "msg":"",     // On error, the message is returned here
    "data":{
        "bizCode": 0,//Business return code: 0 = success. Other values indicate an error, see bizMsg for details
        "bizMsg": "", //Business processing message
    }
}

4.10 Create a video reconstruction job

Request parameters - direct video file input

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/start_video_reconstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
"accessKey":"y6vera",
"quality":"H",                //Required. Quality: "H" = high, "M" = medium, "L" = low
"maximumGaussianPoint":8,    //Maximum number of Gaussian points, 8-50
"name":"video-test",
"samplingFrameRate":1,         //Sampling rate (frames sampled per second): 1 / 2 / 4
"createJobFolder":"ON",
"portability":"ON",         //Whether to enable cross-platform optimization: "ON"/"OFF", enabled by default
"exposure":0,                 //Whether to enable exposure optimization: 0 = disabled, 1 = enabled, default 0 (disabled)
"inputType":"video",         //Required: video = direct video file input
"outputFolder":"/data/lcc_test_data_110/result",
"videoFile1Path":"/data/lcc_test_data_110/video/VID_20250703_102244.mp4"
}'

Request parameters - extracted-frame image directory input

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/start_video_reconstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
"accessKey":"y6vera",
"quality":"H", //Required. Quality: "H" = high, "M" = medium, "L" = low
"maximumGaussianPoint":8,  //Maximum number of Gaussian points, 8-50
"name":"iamges-test",
"samplingFrameRate":1,    //This field is not used in image mode
"createJobFolder":"ON",  
"portability":"ON",     //Whether to enable cross-platform optimization: "ON"/"OFF", enabled by default
"exposure":0,         //Whether to enable exposure optimization: 0 = disabled, 1 = enabled, default 0 (disabled)
"inputType":"image", //Required: image = direct extracted-frame image file input
"outputFolder":"/data/lcc_test_data_110/result",
"inputFolder":"/data/lcc_test_data_110/images" //In image mode the image directory must be passed
}'

Required (enforced by the code): accessKey, outputFolder; video mode also needs videoFile1Path + samplingFrameRate in {1,2,4}, image mode also needs inputFolder.
(Omitting name and quality is not blocked — quality defaults to M, but passing name explicitly is recommended so the job is easy to identify in the job list.)

Response parameters

{
    "code":0,     // 0 means the API call succeeded; any other value means an unexpected error occurred
    "msg":"",     // On error, the message is returned here
    "data":{
        "bizCode": 0,//Business return code: 0 = success. Other values indicate an error, see bizMsg for details
        "bizMsg": "", //Business processing message
    }
}

API usage notes

Authentication

accessKey: required. The request is allowed through only if it is exactly equal to the SERVICE_ACCESS_KEY injected when the container was started (configuration item config_app.AccessKey).
If the server has not configured this KEY (it is empty), requests are allowed through without validation; once it is configured, a mismatch returns {"code":403,"msg":"Http authentication failed"}.

Response envelope

All endpoints return the same envelope:

{
  "code": 0,          // 0 = the call succeeded at the HTTP layer; non-zero = an error reading/parsing/authenticating the request (data is null in that case)
  "msg": "",          // Message on error
  "data": {
    "bizCode": 0,     // Business code: 0 = accepted (started or queued); non-zero = not accepted, see bizMsg for the reason
    "bizMsg": "",     // Business message (STARTED / SCHEDULED / failure reason)
    "jobId": "xxxx"   // ID of this job (may be empty if it was not accepted)
  }
}

`bizCode` semantics

bizCode	Meaning
`0`	Accepted: `bizMsg=STARTED` (started immediately) or `SCHEDULED` (queued, waiting to be scheduled)
non-zero	Not accepted, see `bizMsg` for the reason

Path conventions

inputFolder / outputFolder / droneFolder / hdImageFolder / videoFile*Path are all paths inside the container (the paths mounted into Docker), not host paths.
Input paths must not contain a comma , (validation rejects them).
Reconstruction needs roughly 5x the size of the input data in free /work disk space.

jobId lifecycle

When jobId is omitted, the system generates one (a timestamp plus a 4-character random string, in the form YYYYMMDD-HHMMSS-xxxx); if you pass one, it is used as-is (convenient for caller-defined idempotency IDs).
The jobId is bound to the job record and the output directory; by default the output directory is structured as <outputFolder>/<jobId>/ (see createJobFolder under "Parameter details").

Execution model: synchronous acceptance + asynchronous validation

All API endpoints return as soon as the request is accepted: HTTP returns bizCode=0 quickly, while the actual input data validation, download and reconstruction run in a background coroutine. Therefore successful acceptance does not mean successful reconstruction — you must obtain the real result afterwards by polling check_reconstruction or through the hookUrl callback (which includes buildErrCode/buildErrLog).

Parameter details

`createJobFolder` (ON/OFF, default OFF)

Determines where the output directory lands:

OFF (default): reconstruction results are written directly to outputFolder.
ON: reconstruction results are written to the outputFolder/<jobId>/ subdirectory.

`quality` (H/M/L)

Reconstruction quality tier

H: high — denser sampling, slower, higher video memory usage, finer results.
M: medium (default).
L: low — faster, uses less video memory, coarser results.

The underlying frame-extraction strategy differs between device families (L1/L2 use a frame step, K1/L2Pro use a frame rate), but H is slower and finer, L is faster and lighter.

`maximumGaussianPoint` (number, range 8-50, default 12)

Upper limit on the number of Gaussian points, in millions of points (internally x 1,000,000).

Passing <= 0 → 12 is used automatically.
Passing < 8 → treated internally as 8 (a warning is logged).
Passing > 50 → multi-map/aerial/video reject it outright (error code 0x3404102C); single-map does not reject it explicitly and only truncates it using the video memory formula below.
Whatever you pass, the value is still capped by the GPU video memory formula (values above the cap are truncated to it):

Job type	Gaussian point cap formula (floored, in millions)
Single map (without HD supplementary images) / map fusion / video	`(VRAM GB - 1.5) x 2.304`
HD supplementary images / air-ground fusion / aerial	`(VRAM GB - 4.5) x 2.304`

Example: for a single map on 24 GB of VRAM the cap is approximately (24-1.5) x 2.304 ≈ 51.8, so passing 50 is honored as 50; with 8 GB of VRAM the cap is approximately (8-1.5) x 2.304 ≈ 15, so passing 50 is truncated to 15.

`portability` (ON/OFF, default ON)

"Cross-platform optimization":

ON (default) → spherical harmonics data is not generated, keeping cross-platform compatibility.
OFF → generates spherical harmonics data and turns off cross-platform optimization.

That is, "OFF" is what triggers spherical harmonics generation. If you want spherical harmonics data or higher-quality lighting (and do not mind cross-platform compatibility), pass "OFF"; otherwise keep the default ON.

`pointCloudParticipationRate` (H/L, defaults to the algorithm default)

How much the point cloud participates in reconstruction (PPR):

H: high cohesion
L: low cohesion
Omitted → the default is used (equivalent to H).

`jobQueueEnabled` (0/1) — only effective for single map

This field is currently only meaningful on the single-map endpoint:

Single map =0 (default): if a job is already running on the current node, it fails immediately with LAST TASK STILL IN PROGRESS (bizCode 1) instead of queuing.
Single map =1: when busy, the job joins the queue and waits.

The multi-map/aerial/video endpoints do not read this field: when busy they always queue automatically, regardless of jobQueueEnabled.

`subTasks[]` (required for multi-map)

List of subtasks, 1-50 entries. Each subtask:

Field	Required	Description
`inputFolder`	Y	The scan project directory (path inside the container)

`droneFolder` (multi-map / aerial)

Aerial: required, the drone image directory.
Multi-map: optional; as soon as droneFolder is passed and the directory exists, the job automatically switches from "map fusion" to "air-ground fusion" (no extra switch needed).
Drone image constraints: at least 100 images, JPG/JPEG, resolution >= 1024x768, and they must contain RTK information (air-ground fusion requires RTK images to make up >= 80%).

Video reconstruction input: `inputType` + `videoFile1Path` / `inputFolder`

inputType: "video" (default) or "image".
- video mode: reads videoFile1Path (a single video file).
- image mode: reads inputFolder (an image directory; frame extraction is skipped and the images are used directly as the extracted frames).
samplingFrameRate (sampling frame rate): in video mode it must be one of 1/2/4, otherwise the request is rejected; it is ignored in image mode.

Advanced feature switches

Field	Description	Dependency
`lccAiConfig`	AI spatial understanding - Single map: `1` = smart indoor floor plan. - Multi-map/aerial/video: not supported yet.	Requires a license for the [AI spatial understanding] feature
`developerDataOutput`	Output developer data	Requires a developer data license
`lioMode`	LIO special mode: `""` auto / `"0"` none / `"1"` robust / `"2"` narrow scene	Auto by default
`largeSceneSupport`	Very large scene fusion, default OFF	Beta parameter. For very large scenes where fusion reconstruction fails (for example a total scan duration >300min), set this parameter to ON and retry.
`lowMemory`	0/1	Beta parameter, low-memory mode, default 0 (disabled) If the server has less than 64 GB of memory, set it to 1 to reconstruct larger data sets.