lowpoly sera retiré le 30 oct. 2026. Changez de modèle avant ces dates pour éviter les erreurs de requête.

API Analyser l'imprimabilité

Analysez un modèle 3D pour en évaluer l'imprimabilité — étanchéité, volume, trous, arêtes non-manifold et faces dégénérées. Vous pouvez également vérifier l'épaisseur de paroi à la taille à laquelle vous prévoyez d'imprimer.


POST/openapi/v1/print/analyze

Créer une tâche Analyser l'imprimabilité

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

La tâche s'exécute en arrière-plan. Pour connaître la durée habituelle, consultez Durées de traitement.

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 effectué sur celle-ci renverra le résultat de l'analyse sans passer par le worker.

Pour également vérifier l'épaisseur de paroi à la taille d'impression prévue, envoyez printer_type, une taille d'impression, ou les deux. Le résultat est renvoyé dans printability.thin_walls. La vérification de l'épaisseur de paroi prend plus de temps, la tâche n'est donc généralement pas prête immédiatement, même si le modèle a déjà été analysé auparavant.

Paramètres

  • 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).

    Les URL de téléchargement Meshy (assets.meshy.ai/…?Expires=…&Signature=…) sont signées et cessent de fonctionner à l'expires_at de la tâche ; récupérer à nouveau la tâche ne les renouvelle pas. Pour un modèle généré avec Meshy, transmettez plutôt input_task_id. Cela fonctionne tant que la tâche source est conservée (voir Conservation des ressources). Pour réutiliser un modèle après cela, téléchargez-le avant expires_at et envoyez votre propre copie.

  • Name
    printer_type
    Type
    string
    Description

    L'imprimante que vous comptez utiliser. Elle définit l'épaisseur de paroi minimale pour la vérification de l'épaisseur de paroi. Par défaut fdm lorsque vous envoyez une taille d'impression sans le spécifier.

    Valeurs disponibles :

    • fdm : filament, paroi minimale de 1,0 mm.
    • sla : résine, paroi minimale de 0,8 mm.
    • full_color : couleur complète, paroi minimale de 2,0 mm.
  • Name
    intended_print_height_mm
    Type
    number
    Description

    Hauteur de l'impression, en millimètres. Plage : [1, 1000]. Arrondi au millimètre le plus proche. Uniquement pour les entrées GLB.

  • Name
    intended_print_longest_side_mm
    Type
    number
    Description

    Longueur du côté le plus long de l'impression, en millimètres. Plage : [1, 1000]. Arrondi au millimètre le plus proche. Fonctionne avec tous les formats d'entrée.

Valeurs retournées

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

Modes d'échec

  • Name
    400 - Bad Request
    Description

    La requête était inacceptable. 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épassait 100 Mo.
    • Le fichier de modèle n'a pas pu être téléchargé : model_url a renvoyé une erreur, le plus souvent parce qu'une URL de téléchargement Meshy signée a expiré. Récupérer à nouveau la tâche renvoie la même URL avec la même expiration, envoyez donc votre propre copie du fichier, ou utilisez input_task_id tant que la tâche source est encore conservée.
    • Tâche non réussie : la tâche référencée est encore en attente, en cours, ou a échoué.
    • Taille d'impression invalide : intended_print_height_mm ou intended_print_longest_side_mm est en dehors de [1, 1000], ou les deux ont été envoyés.
    • Type d'imprimante inconnu : printer_type n'est pas fdm, sla, ou full_color.
    • Hauteur sur un modèle non GLB : intended_print_height_mm a été envoyé avec un model_url qui n'est pas .glb. Utilisez plutôt intended_print_longest_side_mm.
    • Impossible de dimensionner ce modèle par hauteur : à la hauteur demandée (ou la valeur par défaut de 150 mm), le côté le plus long du modèle serait en dehors de [1, 1000] mm, le modèle est plat, ou sa taille ne peut pas être déterminée. Utilisez plutôt intended_print_longest_side_mm. Pour un model_url au format .glb et certaines tâches input_task_id, cela n'est détecté qu'après le démarrage de la tâche, et la tâche se termine alors en FAILED.
    • Taille STL inutilisable : printer_type a été envoyé sans taille, et le côté le plus long propre au .stl ne peut pas être lu ou est en dehors de [1, 1000] mm. Envoyez intended_print_longest_side_mm.
  • 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 antérieur à 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"
  }'

# Also check wall thickness for a 100 mm tall SLA print
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",
    "printer_type": "sla",
    "intended_print_height_mm": 100
  }'

Response

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

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

Récupérer une tâche d'analyse d'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.

Retourne

L'objet Tâche d'analyse d'imprimabilité. Le champ printability est null jusqu'à ce que la tâche atteigne SUCCEEDED. Lorsque l'épaisseur de paroi a été vérifiée, printability inclut également intended_print et thin_walls.

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
}

Response (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "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 de tâche 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 analyze-printability. La valeur est print-analyze.

  • Name
    status
    Type
    string
    Description

    Statut de la tâche. Les valeurs possibles sont PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progression 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.

  • 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 de l'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é.

      Lorsque l'épaisseur de paroi a été vérifiée, il s'agit de la pire des valeurs entre les vérifications ci-dessus et thin_walls.status. Du pire au meilleur : error, warning, unknown, healthy.

    • 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. Les erreurs sont déclenchées lorsque le modèle n'est pas étanche, possède un volume non positif, ou présente des arêtes non-manifold. Lorsque l'épaisseur de paroi a été vérifiée, les parois trop fines (thin_walls.status vaut error) comptent comme une erreur supplémentaire.

    • Name
      warning_count
      Type
      integer
      Description

      Nombre de problèmes de niveau avertissement. Les avertissements sont déclenché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 limite (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 d'aire nulle ou invalides).

      • Name
        holes
        Type
        integer
        Description

        Nombre de trous (boucles limites) dans le maillage.

    • Name
      intended_print
      Type
      object
      Description

      L'imprimante et la taille utilisées par la vérification de l'épaisseur de paroi. Présent uniquement lorsque l'épaisseur de paroi a été vérifiée.

      • Name
        printer_type
        Type
        string
        Description

        fdm, sla, ou full_color.

      • Name
        height_mm
        Type
        number
        Description

        La hauteur d'impression en millimètres, si l'impression a été dimensionnée par la hauteur. Sinon null.

      • Name
        longest_side_mm
        Type
        number
        Description

        Le côté le plus long de l'impression en millimètres. Lorsqu'il est dimensionné par la hauteur, il est calculé à partir des proportions du modèle.

      • Name
        wall_thickness_mm
        Type
        number
        Description

        L'épaisseur de paroi minimale pour printer_type, en millimètres. Les parois plus fines que cette valeur sont signalées comme trop fines.

      • Name
        dimensions_mm
        Type
        array
        Description

        Les dimensions [largeur, profondeur, hauteur] de l'impression en millimètres. La hauteur peut différer de height_mm d'une fraction de millimètre. null pour une entrée non-GLB, ou si la taille du modèle ne peut pas être déterminée.

    • Name
      thin_walls
      Type
      object
      Description

      Le résultat de l'épaisseur de paroi. Présent uniquement lorsque l'épaisseur de paroi a été vérifiée.

      • Name
        thin_area_ratio
        Type
        number
        Description

        Part de la surface, de 0 à 1, plus fine que intended_print.wall_thickness_mm. null si le modèle n'a pas pu être mesuré.

      • Name
        has_thin_walls
        Type
        boolean
        Description

        true si une partie de la surface est trop fine. Des angles vifs à eux seuls peuvent déclencher cette valeur, utilisez donc status pour décider si les parois doivent être épaissies. null si le modèle n'a pas pu être mesuré.

      • Name
        status
        Type
        string
        Description

        Le verdict d'épaisseur de paroi. L'une des valeurs suivantes :

        • healthy : 5 % ou moins de la surface est trop fine.
        • error : plus de 5 % de la surface est trop fine. Pour épaissir les parois, transmettez l'id de cette tâche à Réparer l'imprimabilité en tant que input_task_id (pour un model_url au format .stl, .fbx, ou .gltf, envoyez plutôt le fichier en tant que model_url).
        • unknown : le modèle n'a pas pu être mesuré. Si la vérification de l'épaisseur de paroi échoue elle-même, la tâche se termine en FAILED.
    • 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
}

The Analyze Printability Task Object (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "consumed_credits": 0
}