XGRIDS文档

接口说明

本文所有接口均为 POST，请求体为 JSON，请求头统一为 公共请求头，各接口不再重复列出。响应外层结构见 统一响应结构，各接口的「返回结果」只列出 data 内的业务字段。

域名

区域域名
中国大陆https://open-api-gw.xgrids.cloud/
海外及港澳台地区https://open-api-gw.xgrids.com/

公共请求头

所有接口均需在 Header 中携带以下参数。

参数名含义规则说明是否必须缺省值
APP-ID应用 id申请应用时获取必须无
X-Timestamp请求时间戳秒级时间戳必须无
X-Nonce随机字符串仅允许大小写字母与数字，长度 16 到 32 位。正则 ^[A-Za-z0-9]{16,32}$。推荐 UUID.randomUUID() 去除 -必须无
X-Sign请求签名校验请求是否被篡改并防止重放，生成方式见 签名机制必须无
Content-Type内容类型固定 application/json必须无
language返回消息语言zh-CN 或 en-US可选zh-CN

统一响应结构

所有接口返回统一外层结构。外层 code 只反映接口层处理结果，业务结果须读取 data.bizCode。

名称含义规则说明
code接口处理结果码0 成功，401 权限校验失败，429 请求过于频繁
msg接口处理结果描述—
data业务返回数据—
data.bizCode业务响应码0 为成功，其余见 错误码
data.bizMsg业务报错消息—

注：判断调用是否真正成功，需同时满足 code == 0 且 data.bizCode == 0。

创建任务并获取上传密钥

创建建模任务，同时下发用于上传输入数据的云存储临时凭证。

接口地址

POST /open-apis/spatial-model/v1/model/create

使用限制

项限制
并发上限10 次 / 秒
临时上传凭证有效期12 小时
数据存储区域由申请应用时绑定，无需传入

请求参数

参数名含义规则说明是否必须缺省值
modelName建模任务名称长度小于 50必须无
modelDes任务描述长度小于 200可选空
quality建模参数"1" 快速、"2" 标准、"3" 慢速可选"2"
autoRebuild是否上传完成后自动建模0 仅上传、1 上传完自动建模可选1
tags任务标签集合List<String>，元素数量小于 20可选空

返回结果

名称类型含义
data.modelIdLong服务端生成的建模任务 id
data.paramsObject用于数据上传的临时上传凭证参数
data.params.cloudServiceString接收数据上传的云服务商。OSS 阿里云、AWS 亚马逊、KS3 金山云。每个接入方通常只固定对接一个，无需全部对接
data.params.endpointString云存储服务商的上传地址
data.params.regionString云存储服务商的存储区域
data.params.bucketString云存储服务商的上传桶
data.params.savePathString上传文件的目标目录 Key。该值为 input 目录前缀，在其后按相对路径拼接实际文件 Key
data.params.accessKeyIdString临时访问密钥 AccessKeyId
data.params.accessKeySecretString临时访问密钥 AccessKeySecret
data.params.securityTokenString上传安全令牌 SecurityToken
data.params.requestIdString本次请求 ID

请求示例

POST /open-apis/spatial-model/v1/model/create HTTP/1.1
Host: open-api-gw.xgrids.cloud
APP-ID: your_app_id
X-Timestamp: 1791763200
X-Nonce: a3f91c2d8e7b4a6590fd12cb77ae40d1
X-Sign: 9mQk7xL2vTbR4pNw8sYcA1dHfZ3eJgU6oIyK0rVnBsM=
Content-Type: application/json

{
  "modelName": "设计公社C 外立面",
  "modelDes": "深圳南山，LCC2 场景包",
  "quality": "2",
  "autoRebuild": 1,
  "tags": ["外立面", "南山"]
}

返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizCode": 0,
    "bizMsg": "",
    "modelId": 100231987,
    "params": {
      "cloudService": "AWS",
      "endpoint": "s3.ap-southeast-1.amazonaws.com",
      "region": "ap-southeast-1",
      "bucket": "your-bucket-name",
      "savePath": "prd/spatial-model/{accountId}/{taskCode}/input/",
      "accessKeyId": "ASIA****************",
      "accessKeySecret": "wJalrXUtnFEMI/K7MDENG/bPxRfiCY****",
      "securityToken": "IQoJb3JpZ2luX2VjE****",
      "requestId": "b7f1e2a9-5c43-4d8e-9a10-6f2c3b84d517"
    }
  }
}

任务开始执行

手动触发建模。

接口地址

POST /open-apis/spatial-model/v1/model/start

使用限制

项限制
使用场景仅用于创建任务时 autoRebuild = 0 的场景：
① 只有状态为上传完成（3）的任务能 start，否则返回 100041018；
② input 目录里至少要有 .lcc2 / .ply / .las 中的一种，否则返回 100041019；
③ start 时会冻结积分，余额不足会返回积分错误码
频控同一 modelId 存在 3 秒频控
并发上限10 次 / 秒

请求参数

参数名含义规则说明是否必须缺省值
modelId建模任务 id创建任务时返回必须无

返回结果

仅返回 统一响应结构。

请求示例

{
  "modelId": 100231987
}

再次获取上传密钥

上传中断或临时凭证过期时，重新获取临时上传凭证。

接口地址

POST /open-apis/spatial-model/v1/model/sts

使用限制

项限制
临时上传凭证有效期12 小时
频控同一 modelId 存在 3 秒频控，过于频繁返回 10000003
并发上限10 次 / 秒

请求参数

参数名含义规则说明是否必须缺省值
modelId建模任务 id—必须无

返回结果

与 创建任务并获取上传密钥 的返回结果相同（data.modelId 与 data.params.*）。

请求示例

{
  "modelId": 100231987
}

上传状态更新

上报输入数据的上传状态。上传完成后必须调用本接口，否则建模不会启动。

接口地址

POST /open-apis/spatial-model/v1/model/upload_status/update

使用限制

项限制
并发上限10 次 / 秒

请求参数

参数名含义规则说明是否必须缺省值
modelId建模任务 id—必须无
status上传状态1 上传中、2 上传暂停、3 上传成功、4 上传失败必须无
uploadTime上传耗时单位为毫秒，上传成功时建议填写可选空
failedReason失败原因上传失败时建议填写可选空

返回结果

仅返回 统一响应结构。

请求示例

{
  "modelId": 100231987,
  "status": 3,
  "uploadTime": 184620
}

取消重建

仅支持对建模中的任务调用。

  • 仅「建模中」的任务可以取消，取消后任务状态变为「建模失败」。
  • 取消会按已消耗的用量扣除积分，多冻结的积分退回余额。
  • 积分通常在几分钟内完成结算，最长约 10 分钟。

接口地址

POST /open-apis/spatial-model/v1/model/cancel

使用限制

项限制
状态限制仅任务处于建模中（7）时可取消，其他状态返回 100041017
并发上限10 次 / 秒；同一 modelId 存在 3 秒频控，过于频繁返回 10000003

请求参数

参数名含义规则说明是否必须缺省值
modelId建模任务 id—必须无

返回结果

仅返回 统一响应结构。

请求示例

{
  "modelId": 100231987
}

任务列表分页查询

按条件分页查询建模任务。

接口地址

POST /open-apis/spatial-model/v1/model/list

使用限制

项限制
数据范围只返回当前 appId 关联账号下的任务
轮询建议间隔不低于 5 秒
并发上限10 次 / 秒

请求参数

参数名含义规则说明是否必须缺省值
modelName任务名称长度小于 50，模糊查询可选不限
statusList任务状态集合取值见 任务状态机可选不限
startTime开始时间毫秒时间戳，筛选创建时间 ≥ startTime 的记录可选不限
endTime结束时间毫秒时间戳，筛选创建时间 ≤ endTime 的记录可选不限
page.page页码—可选1
page.limit每页数量—可选由服务端定义
page.order排序ASC 正序、DESC 倒序，按创建时间排序可选DESC

返回结果

名称类型含义
data.pageInteger页码
data.limitInteger每页数量
data.totalLong总数
data.dataList数据列表
data.data[].modelIdLong建模任务 id
data.data[].modelNameString任务名称
data.data[].modelDesString任务描述
data.data[].coverString封面地址，建模完成后为模型整体渲染预览图。带签名的临时链接，请勿持久化存储
data.data[].percentDouble建模进度
data.data[].tagsList标签
data.data[].statusInteger任务状态，取值见 任务状态机
data.data[].errorCodeString错误码
data.data[].failedReasonString失败原因
data.data[].createTimeLong创建时间，毫秒时间戳
data.data[].taskSuccessAtLong建模完成时间，毫秒时间戳

请求示例

{
  "modelName": "设计公社",
  "statusList": [7, 8],
  "startTime": 1790899200000,
  "endTime": 1791763200000,
  "page": {
    "page": 1,
    "limit": 20,
    "order": "DESC"
  }
}

任务信息详情查询

批量查询建模任务详情，含建模耗时等统计信息。

接口地址

POST /open-apis/spatial-model/v1/model/detail

使用限制

项限制
批量查询单次最多 50 个 modelId
并发上限10 次 / 秒

请求参数

参数名含义规则说明是否必须缺省值
modelIdList建模任务 id 集合List<Long>，最多同时查询 50 个必须无

返回结果

名称类型含义
data.dataListList任务详情信息
data.dataList[].modelIdLong建模任务 id
data.dataList[].modelNameString任务名称
data.dataList[].modelDesString任务描述
data.dataList[].coverString封面地址。带签名的临时链接，请勿持久化存储
data.dataList[].percentDouble建模进度
data.dataList[].tagsList标签
data.dataList[].statusInteger任务状态，取值见 任务状态机
data.dataList[].errorCodeString错误码
data.dataList[].failedReasonString失败原因
data.dataList[].createTimeLong创建时间，毫秒时间戳
data.dataList[].rebuildInfoObject建模信息
data.dataList[].rebuildInfo.qualityString建模参数。1 快速、2 标准、3 慢速
data.dataList[].rebuildInfo.autoRebuildInteger自动建模标志。0 仅上传、1 上传完自动建模
data.dataList[].rebuildInfo.inputTotalSizeLong输入数据大小，单位为字节
data.dataList[].rebuildInfo.outputTotalSizeLong建模产物大小，单位为字节
data.dataList[].rebuildInfo.uploadTimeLong上传时长，毫秒
data.dataList[].rebuildInfo.buildTimeLong建模时长，毫秒
data.dataList[].rebuildInfo.taskStartAtLong建模任务开始时间，毫秒时间戳
data.dataList[].rebuildInfo.taskSuccessAtLong建模任务成功时间，毫秒时间戳
data.dataList[].rebuildInfo.creditObject积分计费信息（只读），用来核对本次建模的扣费依据。该对象一定会返回，还没产生计费数据时，里面的字段为 null
data.dataList[].rebuildInfo.credit.freezeNoString积分冻结单号，格式 SPATIAL_MODELING_{modelId}_{attempt}。调用「任务开始执行」冻结成功后才有值，之前为 null
data.dataList[].rebuildInfo.credit.frozenCreditLong本轮冻结的积分额。开始建模时先按预估冻结；建模中算法估出面积后，如果所需积分更高，会追加冻结，这里显示追加后的总冻结额
data.dataList[].rebuildInfo.credit.actualCreditLong实际扣除的积分。结算前为 null；建模成功或取消重建后，回填按实际消耗算出的扣费额；建模失败释放时为 0
data.dataList[].rebuildInfo.credit.settleStatusString结算状态。FROZEN 已冻结、待结算；SETTLED 已结算扣费（建模成功或取消重建）；RELEASED 已释放、积分全额退回（建模失败等）。未冻结时为 null
data.dataList[].rebuildInfo.credit.attemptInteger建模轮次，从 1 开始。只有重新调用「任务开始执行」时才加 1，平台内部重新派发不会变。每一轮对应一个独立的 freezeNo
data.dataList[].rebuildInfo.credit.areaM2Double算法估算的建模面积，单位平方米，是追加冻结的依据。算法还没上报时为 null

请求示例

{
  "modelIdList": [100231987, 100231988]
}

账户积分查询

查询 appId 关联账号的积分余额。

接口地址

POST /open-apis/spatial-model/v1/credit/info

使用限制

项限制
查询对象appId 关联账号的积分账户，无需传入用户标识
未开通账户从未发生过积分发放时各项余额均返回 0，不视为错误
数据实时性返回查询时刻的实时余额，不做缓存
并发上限10 次 / 秒

请求参数

无业务参数，传空对象 {} 即可。

返回结果

名称类型含义
data.availableCreditLong可用积分，当前可支配的额度
data.frozenCreditLong冻结中积分，已被预扣、尚未结算的额度
data.totalCreditLong总积分，等于 availableCredit 加 frozenCredit

返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizCode": 0,
    "bizMsg": "",
    "availableCredit": 8500,
    "frozenCredit": 1500,
    "totalCredit": 10000
  }
}

注：本接口仅提供账户积分余额查询。建模任务的积分计费规则（扣减时机、计费口径）将在后续版本明确并另行说明，当前版本调用建模相关接口不受本接口返回值影响。

建模成果下载

获取建模产物的临时下载链接。产物构成见 建模产物。

接口地址

POST /open-apis/spatial-model/v1/model/data/download

使用限制

项限制
前置条件任务状态需为建模完成（8）
链接有效性带签名的临时链接，请获取后尽快下载，不要持久化存储
并发上限10 次 / 秒

请求参数

参数名含义规则说明是否必须缺省值
modelId建模任务 id—必须无
type产物类型DXF、GLB、BLEND、RVT可选不传时返回所有已生成的产物：DXF / GLB / BLEND，有 RVT 时一并返回

返回结果

名称类型含义
data.dataListList<String>建模产物下载链接集合。带签名的临时链接，请勿持久化存储

请求示例

{
  "modelId": 100231987,
  "type": "GLB"
}

任务删除

删除建模任务及其关联数据。

接口地址

POST /open-apis/spatial-model/v1/model/del

使用限制

项限制
状态限制任务处于建模中（7）不允许删除
影响范围同时清理已上传的输入数据与建模产物，不可恢复
并发上限10 次 / 秒

请求参数

参数名含义规则说明是否必须缺省值
modelId建模任务 id—必须无

返回结果

仅返回 统一响应结构。

请求示例

{
  "modelId": 100231987
}

注：删除操作不可恢复，输入数据与建模产物会一并清理，建议在业务侧加二次确认。