Référence des API

Toutes les API de cette page utilisent POST avec un corps de requête JSON. Chaque requête utilise les En-têtes de requête communs, qui ne sont pas répétés pour chaque API. La structure externe de la réponse est décrite dans Structure de réponse unifiée ; la section « Réponse » de chaque API ne liste que les champs métier contenus dans data.

Domaines

Région	Domaine
Chine continentale	`https://open-api-gw.xgrids.cloud/`
Hors Chine continentale (y compris Hong Kong, Macao et Taïwan)	`https://open-api-gw.xgrids.com/`

En-têtes de requête communs

Chaque API exige les paramètres d'en-tête suivants.

Paramètre	Signification	Règle	Obligatoire	Valeur par défaut
APP-ID	Identifiant de l'application	Obtenu lors de la demande d'application	Oui	Aucune
X-Timestamp	Horodatage de la requête	Horodatage en secondes	Oui	Aucune
X-Nonce	Chaîne aléatoire	Lettres et chiffres uniquement, de 16 à 32 caractères. Expression régulière `^[A-Za-z0-9]{16,32}$`. Il est recommandé d'utiliser `UUID.randomUUID()` sans les `-`	Oui	Aucune
X-Sign	Signature de la requête	Vérifie que la requête n'a pas été altérée et empêche le rejeu. Voir Mécanisme de signature	Oui	Aucune
Content-Type	Type de contenu	Toujours `application/json`	Oui	Aucune
language	Langue des messages de réponse	`zh-CN` ou `en-US`	Non	`zh-CN`

Structure de réponse unifiée

Toutes les API renvoient la même structure externe. Le code externe ne reflète que le résultat de la couche API ; lisez data.bizCode pour connaître le résultat métier.

Nom	Signification	Règle
code	Code de résultat de l'API	`0` succès, `401` échec de l'authentification, `429` trop de requêtes
msg	Description du résultat de l'API	—
data	Données métier	—
data.bizCode	Code de résultat métier	`0` signifie succès ; pour les autres valeurs, voir Codes d'erreur
data.bizMsg	Message d'erreur métier	—

Remarque : un appel n'aboutit que si code == 0 et data.bizCode == 0.

Créer une tâche et obtenir les identifiants d'importation

Crée une tâche de modélisation et délivre des identifiants temporaires de stockage cloud pour importer les données d'entrée.

Point de terminaison

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

Limites

Élément	Limite
Concurrence	10 requêtes / seconde
Validité des identifiants temporaires	12 heures
Région de stockage des données	Liée lors de la demande d'application ; inutile de la transmettre

Paramètres de la requête

Paramètre	Signification	Règle	Obligatoire	Valeur par défaut
modelName	Nom de la tâche de modélisation	Moins de 50 caractères	Oui	Aucune
modelDes	Description de la tâche	Moins de 200 caractères	Non	Vide
quality	Qualité de modélisation	`"1"` rapide, `"2"` standard, `"3"` lente	Non	`"2"`
autoRebuild	Démarrer automatiquement la modélisation après l'importation	`0` importation seule, `1` modélisation automatique après l'importation	Non	`1`
tags	Étiquettes de la tâche	List<String>, moins de 20 éléments	Non	Vide

Réponse

Nom	Type	Signification
data.modelId	Long	Identifiant de la tâche de modélisation généré par le serveur
data.params	Object	Paramètres des identifiants temporaires pour l'importation des données
data.params.cloudService	String	Fournisseur cloud qui reçoit l'importation. `OSS` Alibaba Cloud, `AWS` Amazon, `KS3` Kingsoft Cloud. Chaque intégrateur travaille normalement avec un seul fournisseur fixe ; vous n'avez donc pas besoin de les prendre tous en charge
data.params.endpoint	String	Point de terminaison d'importation du fournisseur de stockage cloud
data.params.region	String	Région de stockage du fournisseur de stockage cloud
data.params.bucket	String	Bucket d'importation du fournisseur de stockage cloud
data.params.savePath	String	Key du répertoire cible des fichiers importés. Il s'agit du préfixe du répertoire `input` ; ajoutez-y le chemin relatif de chaque fichier pour former sa Key réelle
data.params.accessKeyId	String	AccessKeyId temporaire
data.params.accessKeySecret	String	AccessKeySecret temporaire
data.params.securityToken	String	SecurityToken d'importation
data.params.requestId	String	Identifiant de cette requête

Exemple de requête

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

Exemple de réponse

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

Démarrer une tâche

Démarre la modélisation manuellement.

Point de terminaison

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

Limites

Élément	Limite
Quand l'utiliser	Uniquement lorsque la tâche a été créée avec `autoRebuild = 0` : ① Seules les tâches à l'état Importation terminée (3) peuvent être démarrées ; sinon `100041018` est renvoyé ; ② Le répertoire `input` doit contenir au moins un fichier `.lcc2` / `.ply` / `.las` ; sinon `100041019` est renvoyé ; ③ Le démarrage gèle des crédits ; si le solde est insuffisant, un code d'erreur lié aux crédits est renvoyé
Limitation de fréquence	Un appel toutes les 3 secondes par modelId
Concurrence	10 requêtes / seconde

Paramètres de la requête

Paramètre	Signification	Règle	Obligatoire	Valeur par défaut
modelId	Identifiant de la tâche de modélisation	Renvoyé à la création de la tâche	Oui	Aucune

Réponse

Renvoie uniquement la Structure de réponse unifiée.

Exemple de requête

{
  "modelId": 100231987
}

Obtenir à nouveau les identifiants d'importation

Obtient de nouveaux identifiants temporaires d'importation lorsqu'une importation est interrompue ou que les identifiants temporaires ont expiré.

Point de terminaison

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

Limites

Élément	Limite
Validité des identifiants temporaires	12 heures
Limitation de fréquence	Un appel toutes les 3 secondes par modelId ; `10000003` est renvoyé en cas d'appels trop fréquents
Concurrence	10 requêtes / seconde

Paramètres de la requête

Paramètre	Signification	Règle	Obligatoire	Valeur par défaut
modelId	Identifiant de la tâche de modélisation	—	Oui	Aucune

Réponse

Identique à la réponse de Créer une tâche et obtenir les identifiants d'importation (data.modelId et data.params.*).

Exemple de requête

{
  "modelId": 100231987
}

Mettre à jour l'état d'importation

Signale l'état d'importation des données d'entrée. Vous devez appeler cette API une fois l'importation terminée ; sinon, la modélisation ne démarre pas.

Point de terminaison

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

Limites

Élément	Limite
Concurrence	10 requêtes / seconde

Paramètres de la requête

Paramètre	Signification	Règle	Obligatoire	Valeur par défaut
modelId	Identifiant de la tâche de modélisation	—	Oui	Aucune
status	État d'importation	`1` en cours, `2` suspendue, `3` réussie, `4` échouée	Oui	Aucune
uploadTime	Durée de l'importation	En millisecondes ; recommandé lorsque l'importation réussit	Non	Vide
failedReason	Cause de l'échec	Recommandé lorsque l'importation échoue	Non	Vide

Réponse

Renvoie uniquement la Structure de réponse unifiée.

Exemple de requête

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

Annuler la modélisation

Ne peut être appelée que pour les tâches en cours de modélisation.

Seules les tâches à l'état Modélisation en cours peuvent être annulées. Après l'annulation, la tâche passe à l'état Échec de la modélisation.
L'annulation déduit les crédits correspondant à l'utilisation déjà consommée ; les crédits gelés excédentaires sont restitués au solde.
Les crédits sont généralement réglés en quelques minutes, au maximum environ 10 minutes.

Point de terminaison

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

Limites

Élément	Limite
Restriction d'état	Seules les tâches à l'état Modélisation en cours (7) peuvent être annulées ; les autres états renvoient `100041017`
Concurrence	10 requêtes / seconde ; un appel toutes les 3 secondes par modelId, `10000003` est renvoyé en cas d'appels trop fréquents

Paramètres de la requête

Paramètre	Signification	Règle	Obligatoire	Valeur par défaut
modelId	Identifiant de la tâche de modélisation	—	Oui	Aucune

Réponse

Renvoie uniquement la Structure de réponse unifiée.

Exemple de requête

{
  "modelId": 100231987
}

Liste paginée des tâches

Interroge les tâches de modélisation page par page, avec des filtres.

Point de terminaison

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

Limites

Élément	Limite
Périmètre des données	Renvoie uniquement les tâches du compte associé à l'appId actuel
Interrogation	Intervalle d'au moins 5 secondes
Concurrence	10 requêtes / seconde

Paramètres de la requête

Paramètre	Signification	Règle	Obligatoire	Valeur par défaut
modelName	Nom de la tâche	Moins de 50 caractères, correspondance approximative	Non	Tous
statusList	États de la tâche	Valeurs dans Machine à états de la tâche	Non	Tous
startTime	Heure de début	Horodatage en millisecondes ; filtre les enregistrements créés à partir de startTime	Non	Tous
endTime	Heure de fin	Horodatage en millisecondes ; filtre les enregistrements créés jusqu'à endTime	Non	Tous
page.page	Numéro de page	—	Non	1
page.limit	Taille de page	—	Non	Définie par le serveur
page.order	Ordre de tri	`ASC` croissant, `DESC` décroissant, par date de création	Non	`DESC`

Réponse

Nom	Type	Signification
data.page	Integer	Numéro de page
data.limit	Integer	Taille de page
data.total	Long	Nombre total
data.data	List	Liste des données
data.data[].modelId	Long	Identifiant de la tâche de modélisation
data.data[].modelName	String	Nom de la tâche
data.data[].modelDes	String	Description de la tâche
data.data[].cover	String	URL de la couverture ; une fois la modélisation terminée, il s'agit de l'aperçu de rendu global du modèle. Lien temporaire signé, ne le conservez pas
data.data[].percent	Double	Progression de la modélisation
data.data[].tags	List	Étiquettes
data.data[].status	Integer	État de la tâche ; valeurs dans Machine à états de la tâche
data.data[].errorCode	String	Code d'erreur
data.data[].failedReason	String	Cause de l'échec
data.data[].createTime	Long	Date de création, horodatage en millisecondes
data.data[].taskSuccessAt	Long	Date de fin de la modélisation, horodatage en millisecondes

Exemple de requête

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

Détails de la tâche

Interroge par lots les détails des tâches de modélisation, y compris des statistiques comme la durée de modélisation.

Point de terminaison

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

Limites

Élément	Limite
Requête par lots	Jusqu'à 50 modelIds par requête
Concurrence	10 requêtes / seconde

Paramètres de la requête

Paramètre	Signification	Règle	Obligatoire	Valeur par défaut
modelIdList	Identifiants des tâches de modélisation	List<Long>, jusqu'à 50 à la fois	Oui	Aucune

Réponse

Nom	Type	Signification
data.dataList	List	Détails des tâches
data.dataList[].modelId	Long	Identifiant de la tâche de modélisation
data.dataList[].modelName	String	Nom de la tâche
data.dataList[].modelDes	String	Description de la tâche
data.dataList[].cover	String	URL de la couverture. Lien temporaire signé, ne le conservez pas
data.dataList[].percent	Double	Progression de la modélisation
data.dataList[].tags	List	Étiquettes
data.dataList[].status	Integer	État de la tâche ; valeurs dans Machine à états de la tâche
data.dataList[].errorCode	String	Code d'erreur
data.dataList[].failedReason	String	Cause de l'échec
data.dataList[].createTime	Long	Date de création, horodatage en millisecondes
data.dataList[].rebuildInfo	Object	Informations de modélisation
data.dataList[].rebuildInfo.quality	String	Qualité de modélisation. `1` rapide, `2` standard, `3` lente
data.dataList[].rebuildInfo.autoRebuild	Integer	Indicateur de modélisation automatique. `0` importation seule, `1` modélisation automatique après l'importation
data.dataList[].rebuildInfo.inputTotalSize	Long	Taille des données d'entrée, en octets
data.dataList[].rebuildInfo.outputTotalSize	Long	Taille des résultats de modélisation, en octets
data.dataList[].rebuildInfo.uploadTime	Long	Durée de l'importation, en millisecondes
data.dataList[].rebuildInfo.buildTime	Long	Durée de la modélisation, en millisecondes
data.dataList[].rebuildInfo.taskStartAt	Long	Date de début de la modélisation, horodatage en millisecondes
data.dataList[].rebuildInfo.taskSuccessAt	Long	Date de réussite de la modélisation, horodatage en millisecondes
data.dataList[].rebuildInfo.credit	Object	Informations de facturation des crédits (lecture seule), pour vérifier le montant facturé pour cette modélisation. Cet objet est toujours renvoyé ; ses champs valent null tant qu'aucune donnée de facturation n'existe
data.dataList[].rebuildInfo.credit.freezeNo	String	Numéro de gel des crédits, au format `SPATIAL_MODELING_{modelId}_{attempt}`. N'a de valeur qu'après le gel réussi des crédits par Démarrer une tâche ; null auparavant
data.dataList[].rebuildInfo.credit.frozenCredit	Long	Crédits gelés pour ce cycle. Une estimation est gelée au démarrage de la modélisation ; si l'algorithme estime ensuite une surface nécessitant davantage de crédits, des crédits supplémentaires sont gelés et ce champ affiche le total après l'augmentation
data.dataList[].rebuildInfo.credit.actualCredit	Long	Crédits réellement déduits. Null avant le règlement ; après la réussite ou l'annulation de la modélisation, contient le montant facturé selon l'utilisation réelle ; 0 en cas de libération après l'échec de la modélisation
data.dataList[].rebuildInfo.credit.settleStatus	String	État du règlement. `FROZEN` gelé, en attente de règlement ; `SETTLED` réglé et facturé (modélisation réussie ou annulée) ; `RELEASED` libéré, crédits intégralement remboursés (échec de la modélisation, etc.). Null en l'absence de gel
data.dataList[].rebuildInfo.credit.attempt	Integer	Cycle de modélisation, à partir de 1. N'augmente de 1 que lorsque Démarrer une tâche est appelée à nouveau ; une nouvelle répartition interne par la plateforme ne le modifie pas. Chaque cycle a son propre freezeNo
data.dataList[].rebuildInfo.credit.areaM2	Double	Surface de modélisation estimée par l'algorithme, en mètres carrés ; base du gel supplémentaire. Null tant que l'algorithme ne l'a pas transmise

Exemple de requête

{
  "modelIdList": [100231987, 100231988]
}

Crédits du compte

Interroge le solde de crédits du compte associé à l'appId.

Point de terminaison

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

Limites

Élément	Limite
Cible de la requête	Le compte de crédits du compte associé à l'appId ; aucun identifiant utilisateur n'est nécessaire
Compte non ouvert	Si aucun crédit n'a jamais été attribué, tous les soldes valent 0 ; ce n'est pas considéré comme une erreur
Fraîcheur	Renvoie le solde en temps réel au moment de la requête, sans cache
Concurrence	10 requêtes / seconde

Paramètres de la requête

Aucun paramètre métier. Transmettez un objet vide {}.

Réponse

Nom	Type	Signification
data.availableCredit	Long	Crédits disponibles, utilisables immédiatement
data.frozenCredit	Long	Crédits gelés, réservés mais pas encore réglés
data.totalCredit	Long	Total des crédits, égal à availableCredit plus frozenCredit

Exemple de réponse

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

Remarque : cette API interroge uniquement le solde de crédits du compte. Les règles de facturation des crédits pour les tâches de modélisation (moment de la déduction et base de facturation) seront définies et documentées dans une version ultérieure. Dans la version actuelle, les appels aux API de modélisation ne dépendent pas des valeurs renvoyées ici.

Télécharger les résultats de modélisation

Obtient des liens de téléchargement temporaires pour les résultats de modélisation. Pour leur contenu, voir Résultats de modélisation.

Point de terminaison

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

Limites

Élément	Limite
Condition préalable	La tâche doit être à l'état Modélisation terminée (8)
Validité des liens	Liens temporaires signés ; téléchargez peu après les avoir obtenus et ne les conservez pas
Concurrence	10 requêtes / seconde

Paramètres de la requête

Paramètre	Signification	Règle	Obligatoire	Valeur par défaut
modelId	Identifiant de la tâche de modélisation	—	Oui	Aucune
type	Type de résultat	`DXF`, `GLB`, `BLEND`, `RVT`	Non	S'il est omis, tous les résultats générés sont renvoyés : DXF / GLB / BLEND, ainsi que RVT s'il est disponible

Réponse

Nom	Type	Signification
data.dataList	List<String>	Liens de téléchargement des résultats de modélisation. Liens temporaires signés, ne les conservez pas

Exemple de requête

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

Supprimer une tâche

Supprime une tâche de modélisation et les données associées.

Point de terminaison

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

Limites

Élément	Limite
Restriction d'état	Les tâches à l'état Modélisation en cours (7) ne peuvent pas être supprimées
Impact	Supprime également les données d'entrée importées et les résultats de modélisation ; opération irréversible
Concurrence	10 requêtes / seconde

Paramètres de la requête

Paramètre	Signification	Règle	Obligatoire	Valeur par défaut
modelId	Identifiant de la tâche de modélisation	—	Oui	Aucune

Réponse

Renvoie uniquement la Structure de réponse unifiée.

Exemple de requête

{
  "modelId": 100231987
}

Remarque : la suppression est irréversible ; les données d'entrée et les résultats de modélisation sont supprimés ensemble. Prévoyez une seconde confirmation de votre côté.