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进行更大规模的数据重建。