建模 API

2026-09-20

司空建模 API 说明

OpenAPI 新增建模 API，支持三方快速集成云端建模能力。

  1. 并发数量上限： 标准版套餐2，商业版5，企业版10
  2. 收费策略： 与司空公有云一致，即二维、三维、3DGS分别收费各收一次张数。
  • 支持上传点云数据进行重建，每 5MB 点云模型等价消耗 1 张建图损耗
  • 点云文件，其中LDR文件根据大小计算张数，其他照片等类型文件按张数或文件数计算

  1. 建模支持范围：
    可见光：二维模型、三维点云、三维mesh、3DGS高斯泼溅
    激光点云：L1、L2已支持，L3即将支持

  2. 单次建模上限： 每种建模任务有文件张数限制
    二维模型：最小5张，最大20000张
    三维模型：最小5张，最大20000张
    高斯泼溅：最小5张，最大4000张
    激光点云：最小5张，最大20000张

示例代码

OpenAPI 已经升级到 V2.0，建模 API 接口行为没有变化，仅路由中的“v0.1”变为“v2.0”

  • 如 “/openapi/v0.1/open_model/stores/obtain_token” 变更为 “/openapi/v2.0/open_model/stores/obtain_token”
  • 若您为 OpenAPI V1.0 的用户，仅需保持 “v0.1” 即可

1. 获取上传的凭证

获取存储桶的临时凭证，用于上传建模的媒体文件。

POST /openapi/v2.0/open_model/stores/obtain_token
X-User-Token: xxxxxxxx 
X-Request-ID: yyyyyyyy

接口返回

{
    "code": 0,
    "message": "",
    "data": {
        "cloud_name": "ali",
        "access_key_id": "xxx",
        "secret_access_key": "xx",
        "session_token": "xx",
        "region": "cn-hangzhou",
        "cloud_bucket_name": "xxx",
        "callback_param": "Q1g0Mm1uOUR6ZUJnMlkzb29vUmE0dmNWdnh0b1M1eis0d3B2c0paQmsrUURmT0Z5dHVLblBjbVllYlZ3cnovbE5ZdHRqM2VjMWxDTUwzYVJCTFk0N2tWd2pkSWIwQlU5dHBMZVZkbXJXZ2xJSWFhdHNxWnE2anQrTk9SMzlET0JNUUg0WkdDVDJ0OHNWbC9mMTZ6R01meEp2WGRzMFU4ZFkyMFIyMzJ6Ty9UUWZ2WUhlcEJWYnQ0NjJDdDFISS9Za0FON0srVjdZYnJITXprNHpRS09aSTJMbEZBdkpLNDNlVUd5dmRzMUJSSTVQVVA1VVlWVnEraDlNdkpQbHdSSw==",
        "store_path": "fh/organizations/5a6f9d4b-2a38-4b4b-86f9-3a678da0bf4a/open_reconstruction/tmp/fbe4f0a1-561c-43d1-a880-baf464bed5c6/{fileName}",
        "expire_time": 1768209932,
        "end_point": "https://xxx"
    }
}

2. 上传回调

上传回调，用于上传文件后，通知需要复制的文件资源有哪些。

POST /openapi/v2.0/open_model/stores/upload_callback
X-User-Token: xxxxxxxx
X-Request-ID: yyyyyyyy

接口请求

{
    "resource_uuid": "69e49a97-6a02-4638-b1b5-b9e871b6c51e",
    "resource_name": "测试",
    "callback_param": "Q1g0Mm1uOUR6ZUJnMlkzb29vUmE0dmNWdnh0b1M1eis0d3B2c0paQmsrUURmT0Z5dHVLblBjbVllYlZ3cnovbE5ZdHRqM2VjMWxDTUwzYVJCTFk0N3JTRjg2anc0aklVMEZ5U0FUdUNCbThqNDJMNEdPRkgvMzZBRWZNZDluZHJGNDJWMGxjUHFUMlk1bG9uNVN5eDZON2l5K0NVZUJGZ3Jrdyt5QTB5RXp1eWJESWZqdG5HeGp5QkF2WnRHTFpZc0thVWtTL1I1eVp5M0UrS0VvMGVpTVlLUGpvUzhiUlo4dE1rMk1PY2lUZz0=",
    "files": [
        {
            "name": "DJI_20250721120152_0025_V.jpeg",
            "etag": "69922E94721B338B174C219542370E8E"
        },
        {
            "name": "DJI_20250721120153_0026_V.jpeg",
            "etag": "60C05FF3D620ADA0365F3427F2A43FA7"
        }
    ]
}

接口返回

{
    "code": 0,
        "message": "",
        "data": {
        "resource_uuid": "69e49a97-6a02-4638-b1b5-b9e871b6c51e",
        "upload_count": 2
    }
}
  • etag是存储桶给文件的hash值，用于校验文件是否完整。

获取例子（go代码）

meta, _ := bucket.GetObjectDetailedMeta(key)
etag := strings.Trim(meta.Get("ETag"), "\"")

3.开始重建任务

POST /openapi/v2.0/open_model/models/reconstruction/start
X-User-Token: xxxxxxxx
X-Request-ID: yyyyyyyy

接口请求

{
    "resource_uuid": "69e49a97-6a02-4638-b1b5-b9e871b6c51e",
    "parameter_2d": "",
    "parameter_3d": "{\"parameter\":{\"cut_AOI\":false,\"generate_b3dm\":true,\"generate_las\":false,\"generate_obj\":false,\"generate_osgb\":false,\"generate_ply\":false,\"generate_pnts\":false,\"generate_point_ply\":false,\"global_min_depth\":-1,\"model_simplify\":0.2,\"output_geo_desc\":{\"cs_type\":\"GEO_CS\",\"geo_cs\":\"EPSG:32650\",\"geo_cs_wkt\":\"\",\"override_vertical_cs\":\"\"},\"output_mesh\":true,\"output_ply_with_normals\":false,\"output_pointcloud\":false,\"ply_with_normals_level\":0,\"quality_level\":3,\"stereo_mode\":false,\"usable_memory_GB\":60,\"water_refine\":false}}",
    "parameter_3dgs": "",
    "parameter_lidar": "",
    "delete_resource_if_finish": false
}

接口返回

{
    "code": 0,
    "message": "",
    "data": {
        "model_3d": {
            "uuid": "476954f7-3ad4-4dcf-a03f-2654d5e0d3cc",
            "status": 12,
            "sub_error_code": 0
        }
    }
}

4.获取模型详情

获取模型详情，用于查询模型状态、大小和任务进度。

GET /openapi/v2.0/open_model/models/476954f7-3ad4-4dcf-a03f-2654d5e0d3cc
X-User-Token: xxxxxxxx
X-Request-ID: yyyyyyyy

接口返回

{
    "code": 0,
    "message": "",
    "data": {
        "resource_uuid": "69e49a97-6a02-4638-b1b5-b9e871b6c51e",
        "model_uuid": "476954f7-3ad4-4dcf-a03f-2654d5e0d3cc",
        "model_type": 2,
        "model_status": 9,
        "model_size": 37420969,
        "reconstruction_progress": 100,
        "error_code": 0,
        "zip_status": 2,
        "zip_progress": 100,
        "zip_file_key": "xxxx"
    }
}
Last Updated: