Referencia de la API

Todas las API de esta página usan POST con un cuerpo de solicitud JSON. Cada solicitud usa las Cabeceras de solicitud comunes, que no se repiten en cada API. La estructura externa de la respuesta se describe en Estructura de respuesta unificada; la sección «Respuesta» de cada API solo enumera los campos de negocio dentro de data.

Dominios

Cabeceras de solicitud comunes

Todas las API requieren los siguientes parámetros de cabecera.

Estructura de respuesta unificada

Todas las API devuelven la misma estructura externa. El code externo solo refleja el resultado de la capa de API; consulta data.bizCode para conocer el resultado de negocio.

Nota: Una llamada solo es correcta cuando se cumplen code == 0 y data.bizCode == 0.

Crear tarea y obtener las credenciales de carga

Crea una tarea de modelado y emite credenciales temporales de almacenamiento en la nube para subir los datos de entrada.

Endpoint

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

Límites

Parámetros de la solicitud

Respuesta

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Iniciar tarea

Inicia el modelado manualmente.

Endpoint

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

Límites

Parámetros de la solicitud

Respuesta

Solo devuelve la Estructura de respuesta unificada.

Ejemplo de solicitud

{
  "modelId": 100231987
}

Obtener de nuevo las credenciales de carga

Obtiene nuevas credenciales temporales de carga cuando una carga se interrumpe o las credenciales temporales han caducado.

Endpoint

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

Límites

Parámetros de la solicitud

Respuesta

Igual que la respuesta de Crear tarea y obtener las credenciales de carga (data.modelId y data.params.*).

Ejemplo de solicitud

{
  "modelId": 100231987
}

Actualizar el estado de carga

Notifica el estado de carga de los datos de entrada. Debes llamar a esta API cuando termine la carga; de lo contrario, el modelado no se iniciará.

Endpoint

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

Límites

Parámetros de la solicitud

Respuesta

Solo devuelve la Estructura de respuesta unificada.

Ejemplo de solicitud

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

Cancelar el modelado

Solo se puede llamar para tareas que se están modelando.

• Solo se pueden cancelar las tareas en estado Modelando. Tras la cancelación, el estado de la tarea pasa a Modelado fallido.
• La cancelación descuenta los créditos del uso ya consumido; los créditos congelados sobrantes se devuelven al saldo.
• Los créditos suelen liquidarse en pocos minutos, como máximo en unos 10 minutos.

Endpoint

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

Límites

Parámetros de la solicitud

Respuesta

Solo devuelve la Estructura de respuesta unificada.

Ejemplo de solicitud

{
  "modelId": 100231987
}

Lista paginada de tareas

Consulta las tareas de modelado página a página con filtros.

Endpoint

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

Límites

Parámetros de la solicitud

Respuesta

Ejemplo de solicitud

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

Detalles de tareas

Consulta por lotes los detalles de las tareas de modelado, incluidas estadísticas como la duración del modelado.

Endpoint

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

Límites

Parámetros de la solicitud

Respuesta

Ejemplo de solicitud

{
  "modelIdList": [100231987, 100231988]
}

Créditos de la cuenta

Consulta el saldo de créditos de la cuenta asociada al appId.

Endpoint

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

Límites

Parámetros de la solicitud

Sin parámetros de negocio. Pasa un objeto vacío {}.

Respuesta

Ejemplo de respuesta

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

Nota: Esta API solo consulta el saldo de créditos de la cuenta. Las reglas de facturación de créditos de las tareas de modelado (momento del descuento y base de facturación) se definirán y documentarán en una versión posterior. En la versión actual, los valores devueltos aquí no afectan a las llamadas a las API de modelado.

Descargar los resultados del modelado

Obtiene enlaces de descarga temporales para los resultados del modelado. Consulta Resultados del modelado para saber qué contienen.

Endpoint

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

Límites

Parámetros de la solicitud

Respuesta

Ejemplo de solicitud

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

Eliminar tarea

Elimina una tarea de modelado y sus datos asociados.

Endpoint

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

Límites

Parámetros de la solicitud

Respuesta

Solo devuelve la Estructura de respuesta unificada.

Ejemplo de solicitud

{
  "modelId": 100231987
}

Nota: La eliminación no se puede deshacer; los datos de entrada y los resultados del modelado se eliminan a la vez. Añade una segunda confirmación en tu sistema.