API d'impression multicolore

Convertir des modèles 3D au format 3MF multicolore pour l'impression 3D, avec une palette de couleurs configurable allant jusqu'à 16 couleurs.

POST/openapi/v1/print/multi-color

Créer une tâche d'impression 3D multicolore

Ce point de terminaison crée une nouvelle tâche d'impression 3D multicolore. La tâche convertit un modèle 3D en un fichier 3MF multicolore adapté à l'impression 3D.

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
    model_url
    Type
    string
    Requis
    Description

    URL accessible publiquement ou Data URI d'un modèle 3D. Nous prenons actuellement en charge les formats .glb et .fbx.

  • Name
    max_colors
    Type
    integer
    défaut 4
    Description

    Nombre maximum de couleurs dans la palette de sortie.

    Plage valide : 1 à 16.

  • Name
    style
    Type
    string
    défaut realistic
    Description

    Style de couleur visuel du fichier 3MF généré.

    Valeurs disponibles :

    • realistic : Échantillonne les couleurs directement à partir de la texture du modèle pour un détail fin et photoréaliste. Produit un fichier plus volumineux.
    • cartoon : Aplati les couleurs en régions uniformes et nettes pour un rendu stylisé. Produit un fichier plus léger.

    L'entrée doit contenir des informations de couleur : realistic nécessite une texture de couleur de base unique avec des coordonnées UV sur chaque partie du maillage ; cartoon accepte également les couleurs par sommet. Les modèles sans texture (blancs) sont rejetés — voir model_missing_texture.

Retours

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

Modes d'échec

  • Name
    400 - Bad Request
    Description

    La requête était inacceptable. Causes courantes :

    • Paramètre manquant : soit model_url, soit input_task_id doit être fourni.
    • Format de modèle invalide : model_url pointe vers un fichier avec une extension non prise en charge (seuls .glb et .fbx sont pris en charge).
    • URL inaccessible : model_url n'a pas pu être téléchargé.
    • Tâche d'entrée invalide : input_task_id doit faire référence à une tâche réussie.
    • max_colors invalide : la valeur doit être comprise entre 1 et 16.
    • style invalide : la valeur doit être realistic ou cartoon.
    • Aucune source de couleur : le modèle d'entrée n'a pas de texture de couleur de base (realistic en nécessite une seule, avec des UV, sur chaque partie du maillage) et pas de couleurs de sommet (cartoon accepte l'un ou l'autre). Texturez d'abord le modèle, ou utilisez cartoon pour les modèles à couleurs de sommet. Les téléversements .fbx sont vérifiés après que la tâche les ait normalisés et échouent avec model_missing_texture à la place.
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

    Crédits insuffisants pour effectuer cette tâche.

  • Name
    429 - Too Many Requests
    Description

    Vous avez dépassé votre limite de débit.

Request

POST
/openapi/v1/print/multi-color
# Convert a 3D model to multi-color 3MF for printing
curl https://api.meshy.ai/openapi/v1/print/multi-color \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "max_colors": 8
  }'

Response

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

Récupérer une tâche d'impression 3D multicolore

Ce point de terminaison récupère une tâche d'impression 3D multicolore par son ID.

Paramètres

  • Name
    id
    Type
    path
    Description

    L'ID de la tâche d'impression 3D à récupérer.

Retours

L'objet Tâche d'impression 3D.

Request

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}
DELETE/openapi/v1/print/multi-color/:id

Supprimer une tâche d'impression 3D multicolore

Ce point de terminaison supprime définitivement une tâche d'impression 3D multicolore, y compris tous les modèles et données associés. Cette action est irréversible.

Paramètres de chemin

  • Name
    id
    Type
    path
    Description

    L'ID de la tâche d'impression 3D multicolore à supprimer.

Statut de la tâche

Une tâche qui est 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 que le worker a déjà commencé à traiter ne sont pas remboursables, donc la supprimer en cours d'exécution vous coûterait à la fois les crédits et le résultat. Attendez qu'elle atteigne SUCCEEDED, FAILED ou CANCELED, puis supprimez-la.

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

Retourne

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

Request

DELETE
/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/multi-color/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/multi-color

Lister les tâches d'impression 3D multicolores

Ce point de terminaison vous permet de récupérer une liste de tâches d'impression 3D multicolores.

Paramètres

Attributs optionnels

  • Name
    page_num
    Type
    integer
    Description

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

  • 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 à utiliser pour le tri. 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.

Retourne

Retourne une liste paginée d'objets de tâche d'impression 3D.

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-multi-color",
    "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
  "consumed_credits": 10
  }
]
GET/openapi/v1/print/multi-color/:id/stream

Diffuser en continu une tâche d'impression 3D multicolore

Ce point de terminaison diffuse en continu les mises à jour en temps réel d'une tâche d'impression 3D multicolore en utilisant les Server-Sent Events (SSE).

Paramètres

  • Name
    id
    Type
    path
    Description

    Identifiant unique de la tâche d'impression 3D multicolore à diffuser en continu.

Retours

Renvoie un flux d'objets de tâche d'impression 3D sous forme de Server-Sent Events.

Pour les tâches PENDING ou IN_PROGRESS, le flux de réponse n'inclura que les champs progress et status nécessaires.

Request

GET
/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream
curl -N https://api.meshy.ai/openapi/v1/print/multi-color/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-multi-color",
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.3mf?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

L'objet de tâche d'impression 3D

  • 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'impression 3D. La valeur est print-multi-color.

  • Name
    model_urls
    Type
    object
    Description

    URL téléchargeable vers le fichier de modèle 3D généré par Meshy. La propriété d'un format sera omise si le format n'est pas généré, au lieu de renvoyer une chaîne vide.

    • Name
      3mf
      Type
      string
      Description

      URL téléchargeable vers le fichier 3MF multicolore.

  • 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
    status
    Type
    string
    Description

    Statut de la tâche. Les valeurs possibles sont l'une des suivantes : PENDING, IN_PROGRESS, SUCCEEDED, FAILED.

  • 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
    task_error
    Type
    object
    Description

    Détails de l'erreur pour les tâches échouées. Consultez Erreurs pour la référence complète de l'objet task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Le nombre de crédits consommés par cette tâche. Présent lorsque le statut de la tâche est PENDING, IN_PROGRESS ou SUCCEEDED. Renvoie 0 pour les tâches FAILED (les crédits sont remboursés en cas d'échec).

The 3D Print Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}