API Reference

All APIs on this page use POST with a JSON request body. Every request uses the Common request headers, which are not repeated for each API. The outer response structure is described in Unified response structure; the "Response" section of each API lists only the business fields inside data.

Domains

Common request headers

Every API requires the following header parameters.

Unified response structure

All APIs return the same outer structure. The outer code reflects only the API-layer result; read data.bizCode for the business result.

Note: A call is successful only when both code == 0 and data.bizCode == 0.

Create Task and Get Upload Credentials

Creates a modeling task and issues temporary cloud storage credentials for uploading the input data.

Endpoint

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

Limits

Request parameters

Response

Request example

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

{
  "modelName": "Design Commune C Facade",
  "modelDes": "Nanshan, Shenzhen, LCC2 scene package",
  "quality": "2",
  "autoRebuild": 1,
  "tags": ["facade", "nanshan"]
}

Response example

{
  "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"
    }
  }
}

Start Task

Starts modeling manually.

Endpoint

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

Limits

Request parameters

Response

Returns only the Unified response structure.

Request example

{
  "modelId": 100231987
}

Get Upload Credentials Again

Obtains new temporary upload credentials when an upload is interrupted or the temporary credentials have expired.

Endpoint

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

Limits

Request parameters

Response

Same as the response of Create Task and Get Upload Credentials (data.modelId and data.params.*).

Request example

{
  "modelId": 100231987
}

Update Upload Status

Reports the upload status of the input data. You must call this API after the upload completes; otherwise modeling will not start.

Endpoint

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

Limits

Request parameters

Response

Returns only the Unified response structure.

Request example

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

Cancel Modeling

Can only be called for tasks that are being modeled.

• Only tasks in Modeling status can be canceled. After cancellation, the task status changes to Modeling failed.
• Cancellation deducts credits for the usage already consumed; any extra frozen credits are returned to the balance.
• Credits are usually settled within a few minutes, at most about 10 minutes.

Endpoint

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

Limits

Request parameters

Response

Returns only the Unified response structure.

Request example

{
  "modelId": 100231987
}

Paginated Task List

Queries modeling tasks page by page with filters.

Endpoint

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

Limits

Request parameters

Response

Request example

{
  "modelName": "Design Commune",
  "statusList": [7, 8],
  "startTime": 1790899200000,
  "endTime": 1791763200000,
  "page": {
    "page": 1,
    "limit": 20,
    "order": "DESC"
  }
}

Task Details

Queries details of modeling tasks in batches, including statistics such as modeling duration.

Endpoint

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

Limits

Request parameters

Response

Request example

{
  "modelIdList": [100231987, 100231988]
}

Account Credits

Queries the credit balance of the account associated with the appId.

Endpoint

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

Limits

Request parameters

No business parameters. Pass an empty object {}.

Response

Response example

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

Note: This API only queries the account credit balance. The credit billing rules for modeling tasks (deduction timing and billing basis) will be defined and documented in a later version. In the current version, calls to the modeling APIs are not affected by the values returned here.

Download Modeling Results

Gets temporary download links for the modeling outputs. See Modeling outputs for what they contain.

Endpoint

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

Limits

Request parameters

Response

Request example

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

Delete Task

Deletes a modeling task and its associated data.

Endpoint

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

Limits

Request parameters

Response

Returns only the Unified response structure.

Request example

{
  "modelId": 100231987
}

Note: Deletion cannot be undone; input data and modeling outputs are removed together. Add a second confirmation on your side.