API Réparer l'imprimabilité

Réparez un modèle 3D pour l'imprimabilité FDM — corrigez les arêtes non-manifold, les faces dégénérées, les trous et autres problèmes de topology afin que le maillage soit prêt à l'impression.

POST/openapi/v1/print/repair

Créer une tâche de réparation d'imprimabilité

Ce point de terminaison crée une nouvelle tâche de réparation d'imprimabilité. La tâche exécute une réparation de la topology sur un modèle 3D et renvoie une version étanche et prête à l'impression.

Le format de sortie correspond au format d'entrée. Si vous soumettez un .stl via model_url, le champ model_urls.stl de la réponse contiendra le maillage réparé et les autres champs de format seront vides. Le chemin input_task_id lit toujours le GLB de la tâche source, donc la sortie est un .glb.

Paramètres

Seul l'un des paramètres input_task_id ou model_url est requis. Si les deux sont fournis, input_task_id a la priorité.

Les textures existantes sont supprimées pendant la réparation en raison des changements de géométrie. Pour réajouter des textures, utilisez l'API de retexturisation sur le modèle réparé.

  • Name
    model_url
    Type
    string
    Requis
    Description

    URL d'un modèle 3D à réparer. 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).

  • Name
    alpha_thumbnail
    Type
    boolean
    défaut false
    Description

    Lorsqu'il est défini sur true, la tâche génère en plus une version à fond transparent (RGBA) de l'aperçu et la renvoie sous forme de alpha_thumbnail_url dans la réponse GET. Le champ thumbnail_url existant reste inchangé.

Retours

La propriété result de la réponse contient l'id de la tâche de réparation 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 possède une extension de fichier non prise en charge.
    • Fichier de modèle trop volumineux : le corps de model_url a dépassé 100 Mo.
    • Tâche non réussie : la tâche référencée est encore en attente, en cours, ou a échoué.
    • GLB manquant : la tâche référencée n'a pas d'asset GLB à réparer.
  • Name
    401 - Unauthorized
    Description

    L'authentification a échoué. Veuillez vérifier votre clé API.

  • Name
    402 - Payment Required
    Description

    Causes courantes :

    • Forfait gratuit : la création de tâches nécessite un forfait payant. Passez à un forfait supérieur sur la page d'abonnement.
    • Crédits insuffisants : la limite de crédits de l'espace de travail a été atteinte.
  • Name
    404 - Not Found
    Description

    La tâche référencée n'existe pas ou appartient à un autre utilisateur.

  • 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/repair
# Repair an existing task
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

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

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/print/repair/:id

Récupérer une tâche de réparation d'imprimabilité

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

Paramètres

  • Name
    id
    Type
    path
    Description

    L'ID de la tâche de réparation d'imprimabilité à récupérer.

Retours

L'objet Tâche de réparation d'imprimabilité. Le bloc model_urls est vide tant que la tâche n'a pas atteint le statut SUCCEEDED. Seul le champ model_urls correspondant au format d'entrée est renseigné.

Request

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}
DELETE/openapi/v1/print/repair/:id

Supprimer une tâche de réparation d'imprimabilité

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

Paramètres de chemin

  • Name
    id
    Type
    path
    Description

    L'ID de la tâche de réparation d'imprimabilité à supprimer.

Statut de la tâche

Une tâche encore PENDING est supprimée et les crédits consommés au moment de 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 déjà démarrée par le worker ne sont pas remboursables ; supprimer la tâche en cours d'exécution vous ferait donc 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/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/repair/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/repair

Lister les tâches Réparer l'imprimabilité

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

Paramètres

Attributs facultatifs

  • Name
    page_num
    Type
    integer
    Description

    Numéro de page pour la pagination. Commence et vaut par défaut 1.

  • Name
    page_size
    Type
    integer
    Description

    Limite de la taille de page. Vaut 10 éléments par défaut. Le maximum autorisé est 100 éléments.

  • Name
    sort_by
    Type
    string
    Description

    Champ selon lequel trier. Valeurs disponibles :

    • +created_at : Trier par date de création dans l'ordre croissant.
    • -created_at : Trier par date de création dans l'ordre décroissant.

Retours

Renvoie une liste paginée d'objets Tâche Réparer l'imprimabilité.

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-repair",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000030000,
    "expires_at": 1715725401000,
    "task_error": null,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "gltf": "",
      "fbx": "",
      "obj": "",
      "stl": "",
      "usdz": "",
      "3mf": "",
      "mtl": ""
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "texture_urls": [],
    "consumed_credits": 10
  }
]
GET/openapi/v1/print/repair/:id/stream

Diffuser une tâche de réparation de l'imprimabilité en continu

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

Paramètres

  • Name
    id
    Type
    path
    Description

    Identifiant unique de la tâche de réparation de l'imprimabilité à diffuser en continu.

Retours

Retourne un flux d'objets de tâche de réparation de l'imprimabilité sous forme d'événements Server-Sent Events.

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

Request

GET
/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream
curl -N https://api.meshy.ai/openapi/v1/print/repair/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-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}

The Repair Printability Task Object

  • 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 de réparation de l'imprimabilité. La valeur est print-repair.

  • 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 commencé, 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 sur l'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
    model_urls
    Type
    object
    Description

    URLs téléchargeables vers le modèle 3D réparé. Seul le champ correspondant au format d'entrée est renseigné ; les autres champs de format sont des chaînes vides.

    • Name
      glb
      Type
      string
      Description

      URL téléchargeable vers le GLB réparé. Renseigné lorsque l'entrée était un GLB ou lorsque input_task_id était utilisé.

    • Name
      gltf
      Type
      string
      Description

      URL téléchargeable vers le GLTF réparé. Renseigné lorsque l'entrée était un fichier GLTF téléversé.

    • Name
      fbx
      Type
      string
      Description

      URL téléchargeable vers le FBX réparé. Renseigné lorsque l'entrée était un fichier FBX téléversé.

    • Name
      obj
      Type
      string
      Description

      URL téléchargeable vers l'OBJ réparé. Renseigné lorsque l'entrée était un fichier OBJ téléversé.

    • Name
      stl
      Type
      string
      Description

      URL téléchargeable vers le STL réparé. Renseigné lorsque l'entrée était un fichier STL téléversé.

    • Name
      usdz
      Type
      string
      Description

      Réservé pour la sortie USDZ. Toujours une chaîne vide pour les tâches de réparation de l'imprimabilité.

    • Name
      3mf
      Type
      string
      Description

      Réservé pour la sortie 3MF. Toujours une chaîne vide pour les tâches de réparation de l'imprimabilité.

    • Name
      mtl
      Type
      string
      Description

      Réservé pour la sortie MTL. Toujours une chaîne vide pour les tâches de réparation de l'imprimabilité.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL d'une image d'aperçu générée à partir du modèle réparé.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    URL téléchargeable vers une version à fond transparent (RGBA) de thumbnail_url. Présent uniquement lorsque la tâche a été créée avec alpha_thumbnail: true et que l'aperçu transparent a été généré avec succès ; sinon, ce champ est omis.

  • Name
    texture_urls
    Type
    array
    Description

    Toujours un tableau vide. La réparation ne préserve que la géométrie d'entrée et ne régénère pas les textures.

  • Name
    consumed_credits
    Type
    integer
    Description

    Le nombre de crédits consommés par cette tâche. 10 une fois que la tâche a atteint le statut SUCCEEDED. Renvoie 0 pour les tâches FAILED (les crédits sont remboursés en cas d'échec).

The Repair Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}