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
}

注：刪除操作不可恢復，輸入數據與建模產物會一併清理，建議在業務側加二次確認。