API指令集說明書

4 HTTP API接口定義

4.1 創建單地圖重建任務

輸入參數

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/start_reconstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
     "accessKey": "y6vera"                  //必須。容器啟動時指定的API鑑權KEY
    ,"name": "job1"                        //必須。任務名稱
    ,"inputFolder": "/work/job001/input"    //必須。重建用input數據目錄的路徑（掛載到Docker內部的路徑）
    ,"outputFolder": "/work/job001/output"  //必須。 重建輸出目的地目錄的路徑（掛載到Docker內部的路徑）
    ,"hookUrl":"http://localhost:8080/lcc_cloud/job_progress_hook_sample" //執行狀態同步的Hook地址
    ,"quality":"M"                     //必須。 質量： "H":高  "M":中  "L":低
    ,"maximumGaussianPoint": 8         //最大高斯點數8-50   
    ,"lowMemory":0                //是否開啟低內存重建: 0/1。默認是0（關閉），1為開啟
    ,"exposure":0               //是否開啟曝光優化: 0/1。默認是0（關閉），1為開啟
    ,"portability":"ON"                //是否開啟跨平台優化: "ON/OFF"。默認是開啟
    ,"pointCloudParticipationRate":"H" //PPR特性，"H":高  "L":低 。默認高。即點雲在重建過程中的參與度。
    ,"jobQueueEnabled":1               //0：如果服務器當前繁忙則直接報錯。1 可加入任務隊列，等待按順序執行。創建單地圖重建任務時，如果不傳此參數，默認值為0
    ,"hdImageFolder": "/work/job001/output"  //高清補拍圖片文件夾。該功能為高級功能，需要授權許可，否則參數無效。
    ,"lccAiConfig":1 // 0 不開啟 1 開啟AI空間理解。內測版功能，目前僅支持室內場景。該功能為高級功能，需要授權許可，否則必須常置為0。
    ,"developerDataOutput":"ON" //是否輸出開發者數據（"ON" / "OFF"）,未輸入時默認OFF。該功能為高級功能，需要授權許可，否則參數無效。參考【附錄：開發者數據】
    ,"createJobFolder":"ON"             //是否在outputFolder下按任務名創建子目錄："ON"/"OFF"
    ,"lioMode":""                        //LIO 特殊模式：""自動 / "0"無 / "1"穩健 / "2"狹窄場景
    ,"executionNodes":["192.168.11.11:8080","192.168.11.11:8081"]//集群模式下，選擇在集群中哪些節點可以運行該任務
}'

注意：
1，注意參數字段的類型是string型還是number型，用錯將導致參數格式錯誤。
2，必須參數字段如果缺失，將會導致任務添加或執行出錯。
3，重建任務執行時，容器節點/work目錄需5倍於input數據大小的磁盤空間，否則有可能導致重建任務出錯。

必填（代碼實際校驗）：accessKey、name、inputFolder、outputFolder。
（quality 缺省按 M；maximumGaussianPoint 缺省 12；hookUrl、hdImageFolder等為可選高級項。）

返回參數

{
    "code":0,     // 0代表API調用成功；其他數值代表發生了不可預知的異常
    "msg":"",     // 異常時此處返回提示信息
    "data":{
        "bizCode": 0,  //業務返回代碼 ：0 啟動或添加隊列成功  1 其他任務執行中,無法啟動。 其他錯誤碼參考bizMsg的返回信息
        "bizMsg": "",  //業務處理提示信息
        "jobId":"xxxx" //當前jobID，啟動時系統生成。任務是否可恢復取決於數據庫和相關工作目錄是否持久化保留；刪除容器且未持久化數據庫時不可恢復
    }
}

INPUT數據檢查錯誤碼一覽表

輸入數據檢查後可能返回的錯誤碼和錯誤信息，請參見最新版錯誤碼列表文檔附錄-錯誤碼列表。

4.2 創建多地圖融合/空地融合的重建任務

輸入參數

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/start_multi_reconstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey": "y6vera"      //必須。容器啟動時指定的API鑑權KEY
    ,"name": "job1"            //必須。任務名稱
    ,"outputFolder": "/work/job001/output"  //必須。 重建輸出目的地目錄的路徑（掛載到Docker內部的路徑）
    ,"quality":"M"                     //必須。 質量： "H":高  "M":中  "L":低
    ,"maximumGaussianPoint": 8         //最大高斯點數8-50  
    ,"exposure":0               //是否開啟曝光優化: 0/1。默認是0（關閉），1為開啟
    ,"portability":"ON"                // 是否開啟跨平台優化: "ON/OFF"。默認是開啟
    ,"pointCloudParticipationRate":"H" // PPR特性，"H":高  "L":低 。默認高。即點雲在重建過程中的參與度。
    ,"subTasks":[                        //必須。
        {
            "inputFolder":"/work/indoor-multi/1",   //必須。重建用input數據目錄的路徑（掛載到Docker內部的路徑）
        },
        {
            "inputFolder":"/work/indoor-multi/2",
        },
        ...
    ]
    ,"droneFolder":"/work/multi/4"           //空地融合時必須。無人機圖片存儲目錄，需授權支持，否則參數無效。
    ,"hookUrl":"http://localhost:8080/lcc_cloud/job_progress_hook_sample" //執行狀態同步Hook地址
    ,"jobQueueEnabled":1  //0：如果服務器當前繁忙則直接報錯。1 可加入任務隊列，等待按順序執行。創建多地圖重建任務時，如果不傳此參數，默認值為1
    ,"developerDataOutput":"ON" //是否輸出開發者數據（"ON" / "OFF"）,未輸入時默認OFF。該功能為高級功能，需要授權許可。
    ,"createJobFolder":"ON"             //是否在outputFolder下按任務名創建子目錄："ON"/"OFF"
    ,"lioMode":""                        //LIO 特殊模式：""自動 / "0"無 / "1"穩健 / "2"狹窄場景
    ,"multiNodeRun":"ON" //集群模式下，該任務是否允許多節點並行計算加速（"ON" / "OFF"）。集群模式下默認為"ON"，非集群模式下該參數無效。
    ,"executionNodes":["192.168.11.11:8080","192.168.11.11:8081"] //集群模式下，選擇在集群中哪些節點可以運行該任務
}'

注意：
1，注意參數字段的類型是string型還是number型，用錯將導致參數格式錯誤。
2，必須參數字段如果缺失，將會導致任務添加或執行出錯。
3，重建任務執行時，容器節點/work目錄需5倍於input數據大小的磁盤空間，否則有可能導致重建任務出錯。

純地圖融合：只傳 subTasks[]。
空地融合：額外加 "droneFolder": "/work/multi/drone"（自動切空地融合，需授權）。

必填（代碼實際校驗）：accessKey、name、subTasks[]（1–50 個）；outputFolder 需為可寫路徑。
（quality 缺省 M ）

返回參數

{
    "code":0,     // 0代表API調用成功；其他數值代表發生了不可預知的異常
    "msg":"",     // 異常時此處返回提示信息
    "data":{
        "bizCode": 0,//業務返回代碼 ：0 啟動或創建成功  1 其他任務執行中,無法啟動。 其他錯誤碼參考bizMsg的返回信息
        "bizMsg": "", //業務處理提示信息
        "jobId":"xxxx" //當前jobID，啟動時系統生成。任務是否可恢復取決於數據庫和相關工作目錄是否持久化保留；刪除容器且未持久化數據庫時不可恢復
    }
}

4.3 查看重建狀態（輪詢用）

啟動重建時，可以通過hookUrl參數，自動同步執行狀態。

也可以使用本API進行輪詢。

輸入參數

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/check_reconstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey": "y6vera",     //必須。容器啟動時指定的API鑑權KEY
    "jobId":"xxxx"             //當前jobID  如果此參數不傳則返回直接返回當前job的狀態
}

返回參數

{
    "code":0,     // 0代表API調用成功；其他數值代表發生了不可預知的異常
    "msg":"",     // 異常時此處返回提示信息
    "data":{
        "bizCode": 0,//業務返回代碼 ：0 未有此job信息   1 此job執行中    2 此job正常結束  其他數值為異常，具體參考bizMsg 
        "bizMsg": "", //業務處理提示信息
        "jobId":"xxxx", //查詢jobID
        "jobName":"xxxx",
        "progress":"進度" //進度
    }
}

4.4 重建狀態同步HOOK API樣例

如果需要鏡像定時自動同步當前JOB的執行狀態到另外的業務系統，

須在業務系統上，按照此API的入參形式構建一個HTTP POST API，並在啟動重建時，將此API的URL作為hookUrl參數傳入。

輸入參數

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執行中    2 job正常結束  其他數值為異常，具體參考bizMsg 
        "bizMsg": "",     //業務處理提示信息
        "jobId":"xxxx"    //當前執行jobID
        "progress":"進度" //進度
}'

返回參數

HookAPI的返回值可任意，LCC系統不做處理。

4.5 重新啟動重建任務

輸入參數

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/resume_reconstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey": "y6vera"      //必須。容器啟動時指定的API鑑權KEY
   ,"jobId":"xxxx"             //必須。要重新啟動的任務jobID
}

註：
容器異常崩潰等情況時，任務異常中止但任務狀態無法及時更新為FAIL，保持為MODELING狀態。
此時也可以採用此API，強制重啟這個異常任務繼續執行

返回參數

{
    "code":0,     // 0代表API調用成功；其他數值代表發生了不可預知的異常
    "msg":"",     // 異常時此處返回提示信息
    "data":{
        "bizCode": 0,//業務返回代碼 ：0 成功  其他數值為異常，具體參考bizMsg 
        "bizMsg": "", //業務處理提示信息
    }
}

4.6 刪除未在執行中的任務

輸入參數

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/job_delete' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey": "y6vera"      //必須。容器啟動時指定的API鑑權KEY
   ,"jobId":"xxxx"             //必須。要重新啟動的任務jobID
}

返回參數

{
    "code":0,     // 0代表API調用成功；其他數值代表發生了不可預知的異常
    "msg":"",     // 異常時此處返回提示信息
    "data":{
        "bizCode": 0,//業務返回代碼 ：0 成功  其他數值為異常，具體參考bizMsg 
        "bizMsg": "", //業務處理提示信息
    }
}

4.7 開啟或關閉自動執行任務隊列

輸入參數

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/job_queue_control' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey": "y6vera"     //必須。容器啟動時指定的API鑑權KEY
   ,"jobQueueControl":"ON"    //"ON"開啟； "OFF"關閉；其他不做處理，只返回當前狀態
}

返回參數

{
    "code":0,     // 0代表API調用成功；其他數值代表發生了不可預知的異常
    "msg":"",     // 異常時此處返回提示信息
    "data":{
        "bizCode": 0,//業務返回代碼 ：0 成功  其他數值為異常，具體參考bizMsg 
        "bizMsg": "", //業務處理提示信息
        "jobQueueEnabled":true  //當前服務器是否會自動處理任務隊列中的任務
    }
}

4.8 創建航拍重建任務

輸入參數

curl --location --request POST 'http://127.0.0.1:8081/lcc_cloud/start_aerial_reconstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey":"y6vera"    //必須。容器啟動時指定的API鑑權KEY
    ,"name":"AerialTestJob"   //必須。任務名稱
    ,"droneFolder":"/data/lcc-test-data/k1/images" //必須。輸入無人機圖片路徑（掛載到Docker內部的路徑）
    ,"outputFolder": "/work/job001/output"          //必須。 重建輸出目的地目錄的路徑（掛載到Docker內部的路徑）
    ,"quality":"H"            //必須。 質量： "H":高  "M":中  "L":低
    ,"maximumGaussianPoint": 8               //最大高斯點數8-50  
    ,"exposure":0               //是否開啟曝光優化: 0/1。默認是0（關閉），1為開啟
    ,"portability":"ON"          //是否開啟跨平台優化："ON"/"OFF"，默認開啟
    ,"createJobFolder":"ON"       //是否在outputFolder下按任務名創建子目錄："ON"/"OFF"
    ,"multiNodeRun":"ON"          //集群模式下是否允許多節點並行計算加速
    ,"hookUrl":"http://localhost:8080/lcc_cloud/job_progress_hook_sample" //執行狀態同步Hook地址
    ,"executionNodes":["192.168.11.11:8080","192.168.11.11:8081"]
}'

注意：
1，注意參數字段的類型是string型還是number型，用錯將導致參數格式錯誤。
2，必須參數字段如果缺失，將會導致任務添加或執行出錯。
3，重建任務執行時，容器節點/work目錄需5倍於input數據大小的磁盤空間，否則有可能導致重建任務出錯。

必填（代碼實際校驗）：accessKey、name、droneFolder、outputFolder（需可寫）。
（quality 缺省 M。）

返回參數

{
    "code":0,     // 0代表API調用成功；其他數值代表發生了不可預知的異常
    "msg":"",     // 異常時此處返回提示信息
    "data":{
        "bizCode": 0,//業務返回代碼 ：0 成功  其他數值為異常，具體參考bizMsg 
        "bizMsg": "", //業務處理提示信息
        "jobQueueEnabled":true  //當前服務器是否會自動處理任務隊列中的任務
    }
}

4.9 強制中止重建任務

強行中止正在執行的任務。注意，此時因為強殺進程，會導致任務異常結束而進入"FAIL"狀態。

但後續可以通過【重新啟動重建任務】API，重新啟動該任務，並從上次成功完成的步驟開始繼續執行。

輸入參數

curl --location --request POST 'http://127.0.0.1:8080/lcc_cloud/stop_reconstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accessKey": "y6vera"      //必須。容器啟動時指定的API鑑權KEY
   ,"jobId":"xxxx"             //必須。要強制中止的任務jobID
}

返回參數

{
    "code":0,     // 0代表API調用成功；其他數值代表發生了不可預知的異常
    "msg":"",     // 異常時此處返回提示信息
    "data":{
        "bizCode": 0,//業務返回代碼 ：0 成功  其他數值為異常，具體參考bizMsg 
        "bizMsg": "", //業務處理提示信息
    }
}

4.10 創建視頻重建任務

輸入參數 - 視頻文件直接輸入

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",                //必須。 質量： "H":高  "M":中  "L":低
"maximumGaussianPoint":8,    //最大高斯點數8-50 
"name":"video-test",
"samplingFrameRate":1,         //採樣頻率（每秒採樣幀數）： 1 / 2 / 4 
"createJobFolder":"ON",
"portability":"ON",         //是否開啟跨平台優化："ON"/"OFF"，默認開啟
"exposure":0,                 //是否開啟曝光優化：0關閉、1開啟，默認0（關閉）
"inputType":"video",         //必須 ： video: 視頻文件直接輸入
"outputFolder":"/data/lcc_test_data_110/result",
"videoFile1Path":"/data/lcc_test_data_110/video/VID_20250703_102244.mp4"
}'

輸入參數 - 視頻抽幀圖片目錄輸入

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", //必須。 質量： "H":高  "M":中  "L":低
"maximumGaussianPoint":8,  //最大高斯點數8-50 
"name":"iamges-test",
"samplingFrameRate":1,    //圖片模式不使用此字段
"createJobFolder":"ON",  
"portability":"ON",     //是否開啟跨平台優化："ON"/"OFF"，默認開啟
"exposure":0,         //是否開啟曝光優化：0關閉、1開啟，默認0（關閉）
"inputType":"image", //必須 ： image: 抽幀圖片文件直接輸入
"outputFolder":"/data/lcc_test_data_110/result",
"inputFolder":"/data/lcc_test_data_110/images" //圖片模式必須傳入圖片目錄
}'

必填（代碼實際校驗）：accessKey、outputFolder；video 模式另需 videoFile1Path + samplingFrameRate∈{1,2,4}，image 模式另需 inputFolder。
（name、quality 缺省不攔截——quality 缺省按 M，但建議顯式傳 name 便於任務列表辨識。）

返回參數

{
    "code":0,     // 0代表API調用成功；其他數值代表發生了不可預知的異常
    "msg":"",     // 異常時此處返回提示信息
    "data":{
        "bizCode": 0,//業務返回代碼 ：0 成功  其他數值為異常，具體參考bizMsg 
        "bizMsg": "", //業務處理提示信息
    }
}

API調用說明

鑑權

accessKey：必須。與容器啟動時注入的 SERVICE_ACCESS_KEY（配置項 config_app.AccessKey）嚴格相等才放行。
若服務端未配置該 KEY（為空），則不校驗直接放行；一旦配置，不匹配返回 {"code":403,"msg":"Http authentication failed"}。

響應包裹

所有接口統一返回：

{
  "code": 0,          // 0=HTTP 層調用成功；非 0=請求讀取/解析/鑑權等異常（此時 data 為 null）
  "msg": "",          // 異常時的提示
  "data": {
    "bizCode": 0,     // 業務碼：0=已受理（啟動或已入隊）；非 0=未受理，原因看 bizMsg
    "bizMsg": "",     // 業務提示（STARTED / SCHEDULED / 失敗原因）
    "jobId": "xxxx"   // 本次任務 ID（受理失敗時可能為空）
  }
}

`bizCode` 語義

bizCode	含義
`0`	已受理：`bizMsg=STARTED`（立即開始）或 `SCHEDULED`（已入隊等待調度）
非 0	未受理，原因見 `bizMsg`

路徑約定

inputFolder / outputFolder / droneFolder / hdImageFolder / videoFile*Path 均為容器內部路徑（掛載進 Docker 的路徑），不是宿主機路徑。
輸入路徑中不能包含英文逗號 ,（會被校驗拒絕）。
重建需要 /work 磁盤空間約為 input 數據的 5 倍以上。

jobId 生命週期

不傳 jobId 時由系統生成（形如 YYYYMMDD-HHMMSS-xxxx 的時間戳 + 4 位隨機串）；傳了則沿用傳入值（便於調用方自定義冪等 ID）。
jobId 與任務記錄、輸出目錄綁定；輸出目錄默認結構為 <outputFolder>/<jobId>/（見「參數詳解」的 createJobFolder）。

執行方式：同步受理 + 異步校驗

API接口都是「受理即返回」：HTTP 很快返回 bizCode=0，真正的輸入數據校驗、下載、重建在後台協程執行。因此受理成功 ≠ 重建成功，後續須通過輪詢 check_reconstruction 或 hookUrl 回調獲取真實結果（含 buildErrCode/buildErrLog）。

參數詳解

`createJobFolder`（ON/OFF，默認 OFF）

決定輸出目錄的落點：

OFF（默認）：重建結果直接寫入 outputFolder。
ON：重建結果寫入 outputFolder/<jobId>/ 子目錄。

`quality`（H/M/L）

重建質量檔位

H：高 — 更密集的採樣，速度慢、顯存佔用高、結果精細。
M：中（缺省）。
L：低 — 更快、更省顯存、結果較粗。

不同設備族的底層抽幀策略不同（L1/L2 走幀步長、K1/L2Pro 走幀率），H 更慢更精細，L 更快更省。

`maximumGaussianPoint`（number，範圍 8–50，缺省 12）

高斯點數量上限，單位是百萬點（內部 × 1,000,000）。

傳入 <= 0 → 自動取 12。
傳入 < 8 → 內部按 8 處理（記警告）。
傳入 > 50 → 多地圖/航拍/視頻會直接拒絕（錯誤碼 0x3404102C）；單地圖不顯式拒絕，只按下方顯存公式截斷。
無論傳多少，最終仍受 GPU 顯存公式 上限約束（超過則按上限截斷）：

任務類型	高斯點上限公式（向下取整，單位百萬）
單地圖（無高清補拍）/ 地圖融合 / 視頻	`(顯存GB - 1.5) × 2.304`
高清補拍 / 空地融合 / 航拍	`(顯存GB - 4.5) × 2.304`

例：24GB 顯存的單地圖，上限 ≈ (24−1.5)×2.304 ≈ 51.8 → 傳 50 也按 50；顯存 8GB 時上限 ≈ (8−1.5)×2.304 ≈ 15，傳 50 會被截斷到 15。

`portability`（ON/OFF，缺省 ON）

「跨平台優化」：

ON（默認）→ 不生成球諧數據，保持跨平台兼容。
OFF → 生成球諧數據，關閉跨平台優化。

即「OFF」才觸發球諧數據生成。如果想要球諧數據/更高質量光照（且不介意跨平台兼容性），傳 "OFF"；否則保持默認 ON。

`pointCloudParticipationRate`（H/L，缺省按算法默認）

點雲在重建中的參與度（PPR）：

H：高粘連
L：低粘連
不傳 → 走默認（等同 H）。

`jobQueueEnabled`（0/1）—— 僅單地圖生效

該字段目前只在單地圖接口有意義：

單地圖 =0（默認）：若當前節點有任務在跑，直接報 LAST TASK STILL IN PROGRESS（bizCode 1），不排隊。
單地圖 =1：忙時加入隊列等待。

多地圖/航拍/視頻接口不讀取此字段：它們忙時總是自動入隊，不受 jobQueueEnabled 影響。

`subTasks[]`（多地圖必填）

子任務列表，1–50 個。每個子任務：

字段	必填	說明
`inputFolder`	Y	該掃描工程目錄（容器內路徑）

`droneFolder`（多地圖/航拍）

航拍：必填，無人機圖片目錄。
多地圖：選填；只要傳了 droneFolder 且目錄存在，任務即自動從「地圖融合」切換為「空地融合」（無需額外開關）。
無人機圖片約束：最少 100 張、JPG/JPEG、分辨率 ≥ 1024×768、需含 RTK 信息（空地融合要求 RTK 圖片佔比 ≥ 80%）。

視頻重建輸入：`inputType` + `videoFile1Path` / `inputFolder`

inputType："video"（默認）或 "image"。
- video 模式：讀 videoFile1Path（單個視頻文件）。
- image 模式：讀 inputFolder（圖片目錄，跳過抽幀，直接把圖片當抽幀結果）。
samplingFrameRate（採樣幀率）：video 模式下必須為 1/2/4 之一，否則拒絕；image 模式忽略。

高級功能開關

字段	說明	依賴
`lccAiConfig`	AI 空間理解 - 單地圖：`1` = 室內智能戶型圖。 - 多地圖/航拍/視頻：暫不支持。	需【AI 空間理解】功能的授權
`developerDataOutput`	輸出開發者數據	需開發者數據授權
`lioMode`	LIO 特殊模式：`""`自動 / `"0"`無 / `"1"`穩健 / `"2"`狹窄場景	默認自動
`largeSceneSupport`	超大場景融合，默認OFF	內測參數，對於融合重建失敗的超大場景（例如總掃描時長 >300min ）可以將此參數設置為 ON 重試。
`lowMemory`	0/1	內測參數，低內存模式，默認 0（關閉）如果服務器內存低於64G ，可以設置為1進行更大規模的數據重建。