开放建模教程

接口前缀：/openapi/v0.1/open_model
用途：通过 OpenAPI 上传影像 / 雷达数据，以异步方式发起 2D / 3D / 3DGS / LiDAR 模型重建，并下载成果文件。
算法参数含义见算法参数介绍文档。

功能介绍

开放建模模块支持上传 DJI 无人机采集的媒体数据，完成模型重建并获取相应的成果文件。

接口使用流程

1. 媒体上传

2. 启动作业

3. 查询作业状态

4. 下载作业输出结果

一、分步说明

步骤 1：获取上传凭证

POST /openapi/v0.1/open_model/stores/obtain_token

该接口无请求参数，返回 data 如下：

字段	说明
`cloud_name`	云厂商，国内环境固定为 `ali`（阿里云 OSS）
`access_key_id` / `secret_access_key` / `session_token`	临时凭证
`region`	区域
`cloud_bucket_name`	存储桶
`end_point`	访问端点
`store_path`	上传路径模板，形如 `fh/organizations/{orgId}/open_reconstruction/tmp/{uuid}/{fileName}`
`callback_param`	加密透传参数，须原样回传至上传回调
`expire_time`	凭证过期时间戳（秒）

注意事项：

凭证有效期以返回的 expire_time 为准，过期后需重新获取。

store_path 中的 {fileName} 需替换为实际文件名，文件须直接上传至其父目录下（请勿再创建子目录）。

步骤 2：上传原始文件

使用临时凭证初始化阿里云 OSS SDK，将各文件上传至：

path.Dir(store_path) + "/" + 文件名

上传完成后获取对象的 ETag，并去除其外层双引号（"abc" → abc），供上传回调使用。

文件名需保持唯一；同一文件名重复回调将被判重（见 duplicate_skip_file_name_list）。

步骤 3：上传回调

POST /openapi/v0.1/open_model/stores/upload_callback

请求体：

字段	类型	必填	说明
`resource_uuid`	string(uuid)	是	由调用方自行生成的资源 UUID，后续发起重建时复用
`resource_name`	string	否	资源名，最长 255
`callback_param`	string	是	步骤 1 返回的原始值
`files`	array	是	文件列表，单次 1~100 个

files[]：

字段	说明
`name`	文件名（相对 `path.Dir(store_path)`，通常为 basename）
`etag`	步骤 2 获取的 ETag（已去除引号）

返回 data：

字段	说明
`resource_uuid`	资源 UUID
`upload_count`	本次成功登记数量
`file_name_list`	成功登记的文件列表
`duplicate_skip_file_name_list`	判重跳过的文件列表

注意事项：

文件总数超过 100 时，按每分片 100 个文件多次调用，resource_uuid 保持不变。

每次回调时服务端会将文件自临时目录转存至媒体目录并计数，因此回调成功后方视为资源（resource）创建完成。

若文件未真正上传成功，将导致转存失败、计数缺失，最终可能触发素材数量不足（见 FAQ）。

特别说明：同名文件重复上传不会覆盖已登记的原始文件。 服务端将判重并跳过该文件（其名称会出现在 duplicate_skip_file_name_list 中），已登记的原始文件保持不变。不建议通过同名文件覆盖数据；如需替换，请使用新的文件名，或在新的资源（resource）中重新上传。

步骤 4：发起重建任务

POST /openapi/v0.1/open_model/models/reconstruction/start

请求体：

字段	类型	必填	说明
`resource_uuid`	string(uuid)	是	步骤 3 的资源 UUID
`parameter_2d`	string	否	2D 参数（JSON 字符串）
`parameter_3d`	string	否	3D 参数（JSON 字符串）
`parameter_3dgs`	string	否	3DGS 参数（JSON 字符串）
`parameter_lidar`	string	否	LiDAR 参数（JSON 字符串）
`delete_resource_if_finish`	bool	否	全部类型成功后是否删除原资源，默认 false

parameter_2d / parameter_3d / parameter_3dgs / parameter_lidar 均最长 16384 字符。

返回 data（仅包含实际传入参数的类型）：

{
  "model_3d": { "uuid": "....", "status": 12, "sub_error_code": 0 }
}

注意事项：

至少传入一种 parameter_*，否则不会启动任何任务（返回的 data 为空）。

parameter_* 为字符串而非对象：需先将参数对象 json.Marshal（或等价序列化）为字符串后再赋值。

各类型的启动结果相互独立：sub_error_code != 0 表示该类型启动失败（如素材数量不足、并发超限），不影响其他类型。

各类型的素材数量限制与并发限制详见 FAQ。

同一资源（resource，未删除时）可重复发起重建，每次可传入不同的 parameter_*；如无必要，无需重复上传素材或重走完整上传流程，直接复用已有 resource_uuid 调用 start 即可。

步骤 5：轮询任务状态

GET /openapi/v0.1/open_model/models/:model_uuid

返回 data 关键字段：

字段	说明
`model_status`	任务状态（见枚举）
`reconstruction_progress`	重建进度 0~100
`error_code`	重建错误码，0 表示无错误
`model_size`	成果大小（字节）
`zip_status`	压缩包状态
`zip_progress`	压缩进度 0~100
`zip_file_key`	压缩包下载地址（带签名的 URL，有效期 1 小时）

完成判定：

model_status == 15（重建成功）且 zip_status == 2（压缩完成）
=> zip_file_key 可下载

批量查询可使用 GET /openapi/v0.1/open_model/models/list，其中 model_zip_url 即下载地址。

轮询间隔建议：重建耗时与建图张数正相关，约 1000 张素材通常需要 1 小时以上。建议根据素材数量设置轮询间隔（例如每 5~10 分钟一次），请勿使用数秒级的高频轮询。

步骤 6：下载成果

对 zip_file_key / model_zip_url 直接发起 HTTP GET 即可下载（预签名 URL，无需额外鉴权）。该 URL 有效期为 1 小时，过期后需重新查询模型详情以获取新的地址。

步骤 7：清理（可选）

DELETE /openapi/v0.1/open_model/models/:model_uuid
DELETE /openapi/v0.1/open_model/resources/:resource_uuid

或在步骤 4 设置 delete_resource_if_finish = true（仅当所有类型均成功时才删除资源）。

二、完整伪代码（端到端）

三、状态与枚举速查

resource status

值	含义
1	上传成功 ImportSuccess
2	等待删除 WaitingDelete
3	已删除 Deleted

model_status

值	含义
8	重建失败 ReconstructionFailed
12	等待资源中 RequestingResource
13	等待资源失败 RequestingResourceFailed
14	重建中 ReconstructionExecuting
15	重建成功 ReconstructionSuccess
16	重建取消 ReconstructionCanceled

model_type

值	含义
1	2D
2	3D
3	3DGS
4	LiDAR

zip_status

值	含义
0	未开始 Init
1	压缩中 Running
2	压缩完成 Finish
3	压缩失败 Failed

四、常见错误码

错误码	含义 / 处理
223102	组织不匹配，请核对 token 与资源所属组织
223103	资源不存在，请确认 `resource_uuid` 与回调一致
223104	资源已删除
223105	模型不存在
223106	回调文件为空
223107	当前任务状态不允许该操作（如重复停止）
223108	素材数量不符合限制
223109	并发任务数超限
222109	参数非法（`parameter` 为空 / JSON 解析失败）
222101	服务内部错误
229016	存储空间已超出额度限制，需扩容存储套餐
229017	建图张数已超出额度限制，需购买 / 充值建图套餐
229999	通用权益校验未通过（权益 / 额度不足的兜底码）

五、常见问题（FAQ）

Q1：各类型建模对拍摄素材（照片 / 影像）有什么要求？
素材采集质量直接影响重建成功率与成果精度。开放建模 API 本身不校验拍摄质量（只校验文件类型与数量，见 Q2/Q9），因此建议在采集 / 上传前按以下要求自查：

特别注意：单张照片存在问题都可能导致整个任务重建失败，而不只是局部效果变差。 常见的"问题照片"包括：
非 DJI 飞行器拍摄的照片混入：素材中混入手机、相机或其他品牌无人机拍摄的照片（缺少 DJI 专有的 POS/云台姿态等元数据，与航线数据不匹配）；
文件损坏或不完整：如上传中断导致的截断文件、EXIF/XMP 元数据缺失或损坏、非标准编码的 JPG 等。
建议上传前校验素材来源（统一为同一批 DJI 飞行器拍摄）和文件完整性，避免个别问题文件拖累整批建模任务。

类型	素材要求 / 建议
2D 可见光	支持 `JPG`/`JPEG`；若使用视频抽帧，需保证画面清晰、飞行平稳、满足重叠度。采集后请检查曝光、云雾遮挡、照片覆盖范围、RTK 状态与相机内参；建议关闭机身的畸变校正与水印功能。
3D 可见光网格	倾斜摄影参考参数：航高 100m、快门时间 ≤1/400s、俯仰角 -45°、航向重叠 80%、旁向重叠 70%，推荐建筑密集、植被较少的城市场景。该组参数用于相机标定，不能直接等同于全部 3D 任务的统一采集标准。
3DGS / 高斯泼溅	支持普通照片与视频抽帧照片参与重建；暂无专门的航高、拍摄角度或重叠率拍摄建议（服务端张数限制见 Q9：10~4000 张，为准入校验而非拍摄质量建议）。
LiDAR	仅支持大疆禅思激光雷达采集的数据；需检查原始点云及配套标定、IMU、RTK 等文件是否完整（必须文件见 Q2）。采集时需关注扫描模式、点频与航高、惯导标定、RTK/POS 状态及航线参数。

另外两点对素材筛选尤其有用：

L2 素材不建议直接用于纯二维建模：雷达航线默认旁向重叠为 20%，折算到可见光照片约仅 37%，低于二维正射推荐的 70% 旁向重叠；若直接用雷达航线照片做纯二维建模，容易出现效果不佳甚至无法拼接，建议改用「激光点云 + 可见光融合重建」。

LiDAR 融合三维建模采集建议：采用雷达建模模式、倾斜采集，航高约 100m、飞行速度 10m/s，建议重复扫描；点云航向重叠需高于 80%、旁向重叠需高于 40%。

Q2：LiDAR（激光点云）任务需要上传哪些文件？
激光点云任务涉及的文件及其必要性如下：

文件	分类	说明	建模是否必须
`CLC` / `CLI`	系统与校准（内部参数）	激光雷达校准文件、相机校准文件；缺失会导致点云精度下降或分层	必须
`LDR`	激光原始数据（最核心）	激光雷达测量的原始点云数据（距离、角度、强度等）	必须
`IMU`	定位与惯导	惯性测量单元数据（三轴加速度、角速度 / 姿态）	必须
`RTK`	定位与惯导	移动站（飞机）RTK 定位记录	必须
`RTB`	定位与惯导	基站（RTK Base）原始观测数据	必须
`RTL`	RTK 链路信息	RTK 链路信息	必须
`SIG`	系统与校准（内部参数）	数据完整性校验文件	可无（有用）
`MRK`	影像与像控	照片曝光时刻；照片与点云对齐的关键	可无（有用）
`PRT`	系统与校准（内部参数）	飞行任务记录：飞行参数、传感器状态	可无（有用）
`PPK.dat`	定位与惯导	用于 PPK（后处理动态差分）处理的特定信息	可无（有用）
`JPG` / `HEIF`	影像与像控	可见光照片，用于为黑白点云赋色	彩色点云必须
`LDRT`	激光原始数据	激光数据索引文件，协助快速读取 / 对齐 `LDR`	非必须
`RPOS`	定位与惯导	实时差分定位融合后的位姿数据	非必须
`DBG`	系统与校准（内部参数）	调试日志	非必须

必须文件为 CLC、CLI、LDR、IMU、RTK、RTB、RTL，缺任意一个均无法建模。

计数与计费规则（影响张数校验与额度）：

图片：1 张计 1 建图张数 + 存储空间，并参与建模；

.LDR：每 5MB 计 1 建图张数 + 存储空间，并参与建模；

.CLC/.CLI/.IMU/.RTK/.RTB/.RTL/.SIG/.LDRT/.RPOS/.DBG/.PRT：每个文件计 1 建图张数 + 存储空间，并参与建模；

.XMP：仅计存储空间，不计建图张数；仅在开启缩略图建模（is_thumbnail_reconstruction=true）时，才随缩略图参与建模；

NAV/OBS/BIN/MRK/DAT 等 PPK 类文件：不计建图张数、不计存储；

其他未识别文件：不计建图张数、计存储空间。

说明：223108（素材数量限制）按文件个数校验；而计费张数按上述规则换算（.LDR 每 5MB 计 1 张）。因此大容量 .LDR 会快速累积建图张数，容易触发 229017（建图张数额度不足）。

Q3：上传回调 upload_count 小于预期？

name 与实际上传的对象名不一致（应使用 basename，不带子目录）；

etag 含外层双引号，或与对象不匹配；

文件实际未上传成功（转存会静默失败）。

判重跳过的文件会出现在 duplicate_skip_file_name_list 中，属正常现象。

同名文件重复上传不会覆盖原始文件（将被判重跳过），因此不建议通过同名文件覆盖数据；如需替换，请使用新的文件名。

Q4：发起重建返回空 data，未启动任何任务？
未传入任何非空的 parameter_*。请至少传入一种，并确保其字符串非空。

Q5：报 invalid param（222109）？
parameter_* 字符串内部缺少 parameter 键，或其为空对象 {}。parameter 至少需包含一个字段，例如 {"parameter":{"quality_level":1}}。

Q6：JSON 转义报错 / 参数解析失败？
parameter_* 必须为字符串。请通过 obj -> json.Marshal -> string 生成后再放入外层请求体（在 GET / 调试工具中表现为大量 \"）。

Q7：parameter_3d 中设置 generate_obj 不生效？
子格式开关受总开关约束：仅当 output_mesh=true 时纹理模型子格式方生效；点云子格式需 output_pointcloud=true。

Q8：坐标系报错 / 成果坐标系不正确？
无 GPS 数据的工程不能使用地理坐标系，output_geo_desc 请使用默认值（由算法自动确定）或局部坐标系。详见 parameter.md 的“地理坐标系”章节。

Q9：报 media number disqualify（223108）？
素材数量不在允许范围内（见下方限制表）。常见原因如下：

文件未真正上传成功，或上传路径不正确，导致回调未计数；

作业类型与素材不匹配（例如向 LiDAR 任务提交了不含 .LDR、.RTK 等雷达文件的资源）。

各类型素材数量限制（按文件个数计，非计费张数；以实际部署配置为准）：

类型	最小值	最大值
2D	5	20000
3D	5	20000
3DGS	10	4000
LiDAR	5	20000

Q10：报 job exceed limit（223109）？
同时运行的重建任务数已达上限：普通版 2 / 专业版 5 / 企业版 10。请等待已有任务完成，或先调用停止接口。

Q11：报 229016 / 229017？
组织付费额度不足：

229016：存储空间已超出额度限制 → 需扩容存储套餐；

229017：建图张数已超出额度限制 → 需购买 / 充值建图套餐。

校验时机：

存储空间（229016） 在 获取上传凭证 obtain_token、上传回调 upload_callback（首次创建资源时）、发起重建 start 三处均会校验；

建图张数（229017） 于 发起重建 start 时校验。

额度不足时，对应接口将直接失败（如 obtain_token 失败则无法获取上传凭证，start 失败则不会创建任务）；额度恢复后重试即可。

Q12：zip_file_key 为空？
压缩尚未完成。请继续轮询直至 zip_status == 2。注意：model_status == 15 后仍可能处于压缩阶段。

Q13：下载链接 403 / 过期？
预签名 URL 有效期为 1 小时。请重新调用模型详情或列表接口，获取新的 zip_file_key。

Q14：建模失败时，如何快速向客服提供信息以定位问题？
排查前建议先自查素材质量：不少建模失败并非接口调用问题，而是素材本身不满足重建要求（如重叠度不足、画面模糊、曝光过曝 / 欠曝、云雾遮挡、RTK 状态异常等），可对照 Q1 的采集要求自查。排除素材问题后仍失败，再按以下方式联系客服。

最直接有效的方式是提供原始素材与请求日志（各请求的 URL / 请求体 / 响应体，尤其是携带 X-Request-Id 的失败请求；原始素材即本次上传的图片 / 雷达文件）。在此基础上，建议再补充以下信息（信息越完整，定位越快）：

项	说明
`X-Request-Id`	最关键。请求头中传入的 ID（服务端会以 `request_id` 记入访问日志）。请在客户端记录失败请求（`start` / 查询 / `upload_callback`）的 ID；未传时服务端会自动生成一个，此时仅能依据时间点与请求路径定位。
`resource_uuid` / `model_uuid`	资源 UUID 与模型 UUID
组织与时间	所属组织、大致发起 / 失败时间（含时区）
完整响应	失败接口的完整返回：`code` / `message`，模型详情中的 `model_status` / `error_code`，以及 `start` 返回的 `sub_error_code`
`parameter_*`	本次 `start` 使用的完整参数 JSON
输入素材概况	作业类型（2D/3D/3DGS/LiDAR）、文件类型与数量、命名规则；LiDAR 请说明是否包含必须文件 `CLC/CLI/LDR/IMU/RTK/RTB/RTL`
原始素材	如需客服复核原始数据，请提供 `resource_uuid`（客服可按此定位到该资源的媒体 / 原始数据）；必要时再另行提供素材文件

建议：客户端为每个请求生成并记录 X-Request-Id（UUID），以便服务端按 request_id 精准检索链路日志。

六、接口清单

方法	路径	说明
POST	`/openapi/v0.1/open_model/stores/obtain_token`	获取上传凭证
POST	`/openapi/v0.1/open_model/stores/upload_callback`	上传回调
GET	`/openapi/v0.1/open_model/resources/:resource_uuid`	资源详情
DELETE	`/openapi/v0.1/open_model/resources/:resource_uuid`	删除资源
GET	`/openapi/v0.1/open_model/resources/list`	资源列表
POST	`/openapi/v0.1/open_model/models/reconstruction/start`	发起重建
POST	`/openapi/v0.1/open_model/models/:model_uuid/reconstruction/stop`	停止重建
GET	`/openapi/v0.1/open_model/models/:model_uuid`	模型详情
GET	`/openapi/v0.1/open_model/models/running`	运行中模型列表
GET	`/openapi/v0.1/open_model/models/list`	模型列表（含下载地址）
DELETE	`/openapi/v0.1/open_model/models/:model_uuid`	删除模型

功能介绍#

接口使用流程#

1. 媒体上传#

2. 启动作业#

3. 查询作业状态#

4. 下载作业输出结果#

一、分步说明#

步骤 1：获取上传凭证#

步骤 2：上传原始文件#

步骤 3：上传回调#

步骤 4：发起重建任务#

步骤 5：轮询任务状态#

步骤 6：下载成果#

步骤 7：清理（可选）#

二、完整伪代码（端到端）#

三、状态与枚举速查#

resource status#

model_status#

model_type#

zip_status#

四、常见错误码#

五、常见问题（FAQ）#

六、接口清单#

功能介绍

接口使用流程

1. 媒体上传

2. 启动作业

3. 查询作业状态

4. 下载作业输出结果

一、分步说明

步骤 1：获取上传凭证

步骤 2：上传原始文件

步骤 3：上传回调

步骤 4：发起重建任务

步骤 5：轮询任务状态

步骤 6：下载成果

步骤 7：清理（可选）

二、完整伪代码（端到端）

三、状态与枚举速查

resource status

model_status

model_type

zip_status

四、常见错误码

五、常见问题（FAQ）

六、接口清单