API リファレンス

このページの API はすべて POST メソッドで、リクエストボディは JSON です。すべてのリクエストで共通リクエストヘッダーを使用します。各 API の説明では繰り返し記載しません。レスポンスの外側の構造は統一レスポンス構造を参照してください。各 API の「レスポンス」には data 内の業務フィールドのみを記載しています。

ドメイン

共通リクエストヘッダー

すべての API で以下のヘッダーパラメータが必要です。

統一レスポンス構造

すべての API は同じ外側の構造を返します。外側の code は API 層の結果のみを表します。業務の結果は data.bizCode で確認してください。

注：code == 0 かつ data.bizCode == 0 の場合にのみ、呼び出しは成功です。

タスクを作成してアップロード認証情報を取得

モデリングタスクを作成し、入力データのアップロードに使用するクラウドストレージの一時認証情報を発行します。

エンドポイント

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

制限

リクエストパラメータ

レスポンス

リクエスト例

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

レスポンス例

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

制限

リクエストパラメータ

レスポンス

統一レスポンス構造のみを返します。

リクエスト例

{
  "modelId": 100231987
}

アップロード認証情報の再取得

アップロードが中断された場合や一時認証情報の有効期限が切れた場合に、新しい一時アップロード認証情報を取得します。

エンドポイント

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

制限

リクエストパラメータ

レスポンス

タスクを作成してアップロード認証情報を取得のレスポンスと同じです（data.modelId と data.params.*）。

リクエスト例

{
  "modelId": 100231987
}

アップロードステータスの更新

入力データのアップロードステータスを報告します。アップロード完了後に必ず呼び出してください。呼び出さないとモデリングは開始されません。

エンドポイント

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

制限

リクエストパラメータ

レスポンス

統一レスポンス構造のみを返します。

リクエスト例

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

モデリングのキャンセル

モデリング中のタスクに対してのみ呼び出せます。

• キャンセルできるのはモデリング中ステータスのタスクのみです。キャンセル後、タスクのステータスはモデリング失敗に変わります。
• キャンセル時は、すでに消費した分のクレジットが差し引かれ、凍結されていた残りのクレジットは残高に戻ります。
• クレジットの精算は通常数分以内、最長で約 10 分で完了します。

エンドポイント

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

制限

リクエストパラメータ

レスポンス

統一レスポンス構造のみを返します。

リクエスト例

{
  "modelId": 100231987
}

タスク一覧のページング取得

条件を指定して、モデリングタスクをページ単位で照会します。

エンドポイント

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

制限

リクエストパラメータ

レスポンス

リクエスト例

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

タスク詳細

モデリングタスクの詳細を一括で照会します。モデリング所要時間などの統計情報も含まれます。

エンドポイント

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

制限

リクエストパラメータ

レスポンス

リクエスト例

{
  "modelIdList": [100231987, 100231988]
}

アカウントのクレジット

appId に紐付くアカウントのクレジット残高を照会します。

エンドポイント

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

制限

リクエストパラメータ

業務パラメータはありません。空オブジェクト {} を渡してください。

レスポンス

レスポンス例

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

注：この API はアカウントのクレジット残高の照会のみを行います。モデリングタスクのクレジット課金ルール（差し引きのタイミングと課金基準）は今後のバージョンで定義・公開されます。現行バージョンでは、ここで返される値がモデリング API の呼び出しに影響することはありません。

モデリング結果のダウンロード

モデリング出力物の一時ダウンロードリンクを取得します。出力物の内容はモデリング出力物を参照してください。

エンドポイント

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

制限

リクエストパラメータ

レスポンス

リクエスト例

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

タスクの削除

モデリングタスクと関連データを削除します。

エンドポイント

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

制限

リクエストパラメータ

レスポンス

統一レスポンス構造のみを返します。

リクエスト例

{
  "modelId": 100231987
}

注：削除は元に戻せません。入力データとモデリング出力物もまとめて削除されます。連携側で二重確認を設けてください。