API Analyser l'imprimabilité

Analysez un modèle 3D pour l'imprimabilité FDM — étanchéité, volume, trous, arêtes non-manifold et faces dégénérées.

POST/openapi/v1/print/analyze

Create an Analyze Printability Task

Ce point de terminaison crée une nouvelle tâche d'analyse de l'imprimabilité. La tâche évalue un modèle 3D et rapporte ses métriques d'imprimabilité.

Si la tâche d'entrée dispose déjà d'une imprimabilité mise en cache, la tâche retournée est immédiatement prête et le premier GET sur celle-ci renverra le résultat de l'analyse sans passer par le worker.

Paramètres

Un seul des paramètres input_task_id ou model_url est requis. Si les deux sont fournis, input_task_id a la priorité.

Name
input_task_id
Type
string
Requis
Description
L'ID d'une tâche réussie que vous possédez. Types de tâches pris en charge : Image en 3D, Multi-image en 3D, Texte en 3D, Remaillage, et Retexturisation. La tâche doit utiliser Meshy 6 ou une version plus récente (y compris Meshy 7) et doit avoir un statut SUCCEEDED.

Name
model_url
Type
string
Requis
Description
URL d'un modèle 3D à analyser. Formats pris en charge : .glb, .gltf, .obj, .fbx, .stl. Taille de fichier maximale : 100 Mo. Doit utiliser http, https, ou une URL data: (les URL data contournent les vérifications d'extension).

Retours

La propriété result de la réponse contient l'id de la tâche d'analyse de l'imprimabilité nouvellement créée.

Modes d'échec

Name
400 - Bad Request
Description
La requête était irrecevable. Causes courantes :
- Paramètre manquant : ni input_task_id ni model_url n'a été fourni.
- UUID invalide : input_task_id n'est pas un UUID valide.
- URL de modèle invalide : model_url est mal formée, utilise un schéma non pris en charge, ou a une extension de fichier non prise en charge.
- Fichier de modèle trop volumineux : le corps de model_url dépasse 100 Mo.
- Tâche non réussie : la tâche référencée est encore en attente, en cours, ou a échoué.
Name
401 - Unauthorized
Description
L'authentification a échoué. Veuillez vérifier votre clé API.
Name
403 - Forbidden
Description
La tâche existe mais appartient à un autre utilisateur.
Name
404 - Not Found
Description
Causes courantes :
- La tâche n'existe pas ou a été supprimée.
- La tâche utilise un modèle plus ancien que Meshy 6, ou son mode ne produit pas d'asset 3D.
- Le fichier de modèle sous-jacent n'est plus disponible dans le stockage.
Name
429 - Too Many Requests
Description
Vous avez dépassé votre quota de tâches en attente ou votre limite de débit.

Request

POST

/openapi/v1/print/analyze

# Analyze an existing task
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Or analyze a model URL directly
curl https://api.meshy.ai/openapi/v1/print/analyze \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb"
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/print/analyze/:id

Récupérer une tâche Analyser l'imprimabilité

Ce point de terminaison récupère une tâche d'analyse d'imprimabilité par son ID.

Paramètres

Name
id
Type
path
Description
L'ID de la tâche d'analyse d'imprimabilité à récupérer.

Retours

L'objet Tâche d'analyse d'imprimabilité. Le champ printability est null jusqu'à ce que la tâche atteigne SUCCEEDED.

Request

GET

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

DELETE/openapi/v1/print/analyze/:id

Supprimer une tâche d'analyse d'imprimabilité

Ce point de terminaison supprime définitivement une tâche d'analyse d'imprimabilité ainsi que son résultat mis en cache. Cette action est irréversible.

Paramètres de chemin

Name
id
Type
path
Description
L'ID de la tâche d'analyse d'imprimabilité à supprimer.

Statut de la tâche

Une tâche qui est encore PENDING est supprimée et les crédits consommés à la création sont remboursés.

Une tâche déjà IN_PROGRESS ne peut pas être supprimée : la requête est rejetée avec 409 Conflict et la tâche continue de s'exécuter. Les crédits d'une tâche que le worker a déjà commencé à traiter ne sont pas remboursables, donc la supprimer en cours d'exécution vous ferait perdre à la fois les crédits et le résultat. Attendez qu'elle atteigne l'état SUCCEEDED, FAILED ou CANCELED, puis supprimez-la.

Une tâche dans un état final (SUCCEEDED, FAILED ou CANCELED) est supprimée sans remboursement.

Retours

Retourne 200 OK en cas de succès, ou 409 Conflict lorsque la tâche est IN_PROGRESS.

Request

DELETE

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

GET/openapi/v1/print/analyze

Lister les tâches d'analyse d'imprimabilité

Ce point de terminaison vous permet de récupérer une liste de tâches d'analyse d'imprimabilité.

Paramètres

Attributs optionnels

Name
page_num
Type
integer
Description
Numéro de page pour la pagination. Commence et est par défaut à 1.
Name
page_size
Type
integer
Description
Limite de taille de page. Par défaut à 10 éléments. Le maximum autorisé est de 100 éléments.
Name
sort_by
Type
string
Description
Champ selon lequel trier. Valeurs disponibles :
- +created_at: Trier par date de création par ordre croissant.
- -created_at: Trier par date de création par ordre décroissant.

Retours

Retourne une liste paginée d'objets de tâche d'analyse d'imprimabilité.

Request

GET

/openapi/v1/print/analyze

curl https://api.meshy.ai/openapi/v1/print/analyze?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-analyze",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "expires_at": 1715725401000,
    "task_error": null,
    "printability": {
      "_version": "v1",
      "status": "warning",
      "issue_count": 1,
      "error_count": 0,
      "warning_count": 1,
      "metrics": {
        "is_watertight": true,
        "volume": 1.316167354292668,
        "non_manifold_edges": 0,
        "degenerate_faces": 43242,
        "holes": 0
      },
      "evaluated_at": 1700000001000
    },
    "consumed_credits": 0
  }
]

GET/openapi/v1/print/analyze/:id/stream

Diffuser une tâche d'analyse d'imprimabilité

Ce point de terminaison diffuse en temps réel les mises à jour d'une tâche d'analyse d'imprimabilité à l'aide des Server-Sent Events (SSE).

Paramètres

Name
id
Type
path
Description
Identifiant unique de la tâche d'analyse d'imprimabilité à diffuser.

Retours

Retourne un flux d'objets de tâche d'analyse d'imprimabilité sous forme de Server-Sent Events.

Chaque trame transporte l'objet complet de la tâche pour l'étape en cours — la même structure que celle renvoyée par le point de terminaison Get — ainsi, tant que la tâche est PENDING ou IN_PROGRESS, les champs de sortie ne sont simplement pas encore renseignés (null, [] ou {}) et finished_at est null. Le bloc printability n'est envoyé qu'une fois la tâche parvenue à l'état SUCCEEDED.

Request

GET

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

L'objet Task Analyser l'imprimabilité

Name
id
Type
string
Description
Identifiant unique de la tâche. Bien que nous utilisions un UUID k-sortable pour les identifiants de tâche comme détail d'implémentation, vous ne devez pas faire d'hypothèses sur le format de l'id.
Name
type
Type
string
Description
Type de la tâche d'analyse d'imprimabilité. La valeur est print-analyze.
Name
status
Type
string
Description
Statut de la tâche. Les valeurs possibles sont l'une de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress de la tâche. Si la tâche n'a pas encore démarré, cette propriété sera 0. Une fois la tâche réussie, elle deviendra 100.
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches précédentes.
La valeur de ce champ n'a de sens que si le statut de la tâche est PENDING.
Name
created_at
Type
timestamp
Description
Horodatage de la création de la tâche, en millisecondes.
Name
started_at
Type
timestamp
Description
Horodatage du démarrage de la tâche, en millisecondes. Si la tâche n'a pas encore démarré, cette propriété sera 0.
Name
finished_at
Type
timestamp
Description
Horodatage de la fin de la tâche, en millisecondes. Si la tâche n'est pas encore terminée, cette propriété sera 0.
Name
expires_at
Type
timestamp
Description
Horodatage de l'expiration du résultat de la tâche dans le système, en millisecondes. 0 si la tâche n'est pas encore terminée.
Name
task_error
Type
object
Description
Informations d'erreur si la tâche a échoué. Cette propriété est null si la tâche n'a pas échoué. Voir Erreurs pour plus de détails.
- Name
  message
  Type
  string
  Description
  Message d'erreur décrivant ce qui s'est mal passé.
Name
printability
Type
object
Description
Résultat de l'évaluation d'imprimabilité. null jusqu'à ce que la tâche atteigne SUCCEEDED.
- Name
  _version
  Type
  string
  Description
  Version du schéma du résultat d'imprimabilité. Actuellement v1.
- Name
  status
  Type
  string
  Description
  Statut global. L'une des valeurs suivantes :
  
  healthy : aucune erreur et aucun avertissement.
  
  warning : au moins un avertissement, aucune erreur.
  
  error : au moins une erreur.
  
  unknown : le modèle n'a pas pu être analysé.
- Name
  issue_count
  Type
  integer
  Description
  Nombre total de problèmes, égal à error_count + warning_count.
- Name
  error_count
  Type
  integer
  Description
  Nombre de problèmes de niveau erreur. Des erreurs sont levées lorsque le modèle n'est pas étanche, a un volume non positif, ou présente des arêtes non-manifold.
- Name
  warning_count
  Type
  integer
  Description
  Nombre de problèmes de niveau avertissement. Des avertissements sont levés lorsque le modèle contient des faces dégénérées ou des trous.
- Name
  metrics
  Type
  object
  Description
  Métriques brutes de géométrie renvoyées par l'évaluateur.
  Name
  is_watertight
  Type
  boolean
  Description
  true lorsque le maillage n'a aucune arête de bord (c'est-à-dire qu'il est fermé).
  Name
  volume
  Type
  number
  Description
  Volume du modèle en mètres cubes.
  Name
  non_manifold_edges
  Type
  integer
  Description
  Nombre d'arêtes non-manifold.
  Name
  degenerate_faces
  Type
  integer
  Description
  Nombre de faces dégénérées (faces à aire nulle ou invalides).
  Name
  holes
  Type
  integer
  Description
  Nombre de trous (boucles de bord) dans le maillage.
- Name
  evaluated_at
  Type
  timestamp
  Description
  Horodatage du calcul de l'analyse, en millisecondes depuis l'epoch.
Name
consumed_credits
Type
integer
Description
Toujours 0. Ce point de terminaison est gratuit.

The Analyze Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}