API d'impression multicolore

Convertir un modèle 3D en un fichier 3MF multicolore pour l'impression 3D. Choisissez une palette allant jusqu'à 16 couleurs et un préréglage de trancheur pour la marque de votre imprimante.

POST/openapi/v1/print/multi-color

Créer une tâche d'impression multicolore

Crée une tâche d'impression multicolore, qui convertit un modèle 3D en un fichier 3MF multicolore pour l'impression 3D. La tâche s'exécute en arrière-plan. Pour connaître la durée habituelle d'une tâche, consultez Temps de traitement.

Request

POST

/openapi/v1/print/multi-color

# Convert a 3D model to a multi-color 3MF with a Creality slicer preset
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,
    "printer_brand": "creality"
  }'

Response

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

Paramètres

Name
input_task_id
Type
string
Requis
Description
Requis sauf si vous envoyez model_url. L'ID de la tâche dont vous voulez imprimer le modèle, par exemple une tâche Image en 3D, Multi-image en 3D, Texte en 3D, Remaillage, ou Retexturisation. La tâche doit être une tâche que vous avez créée avec l'API, et avoir le statut SUCCEEDED.
L'impression multicolore lit le fichier GLB de la tâche, qui peut avoir au maximum 8 000 000 de faces. Un modèle avec plus de faces renvoie 400. Dans ce cas, exécutez d'abord une tâche de Remaillage, puis envoyez l'ID de cette tâche de remaillage à la place.

Name
model_url
Type
string
Requis
Description
Requis sauf si vous envoyez input_task_id. Le modèle à imprimer, sous forme d'URL publique ou de Data URI. Si vous envoyez les deux, Meshy utilise input_task_id.
Une URL http ou https doit pointer vers un fichier .glb ou .fbx de 400 Mo maximum. Un Data URI doit contenir un fichier GLB encodé en base64 de 100 Mo maximum. Utilisez data:model/gltf-binary;base64,. Envoyez un fichier .fbx sous forme d'URL http ou https.
Un fichier de plus de 100 Mo doit également respecter les règles suivantes :
- Il peut avoir au maximum 8 000 000 de faces. Meshy compte les faces comme des triangles, donc un quadrilatère compte pour 2, et un maillage dessiné plusieurs fois compte une fois par copie.
- Un fichier FBX doit être au format binaire FBX 7.1 ou plus récent.
- Un fichier GLB ne doit pas utiliser la compression Draco.

Name
max_colors
Type
integer
défaut 4
Description
Le nombre maximal de couleurs dans la palette de sortie, de 1 à 16. Pour utiliser la valeur par défaut, omettez ce paramètre plutôt que d'envoyer 0.
Name
style
Type
string
défaut realistic
Description
Le style de couleur du fichier 3MF.
Valeurs disponibles :
- realistic : échantillonne les couleurs directement depuis la texture du modèle pour un détail fin et photo-réaliste, et produit un fichier plus volumineux.
- cartoon : aplatit les couleurs en zones uniformes et nettes pour un rendu stylisé, et produit un fichier plus petit.
Le modèle doit avoir de la couleur. realistic nécessite une texture de couleur de base unique, avec des UV sur chaque partie du maillage, et cartoon accepte également les couleurs de sommets. Meshy rejette un modèle sans texture (blanc). Voir model_missing_texture.
Name
max_depth
Type
integer
défaut 4
Description
La profondeur de subdivision que Meshy utilise pour échantillonner les couleurs de la texture sur le maillage, de 3 à 6. 0 équivaut à omettre ce paramètre. Des valeurs plus élevées capturent un détail de couleur plus fin, et produisent un fichier plus volumineux. Seul le style realistic l'utilise, et cartoon l'ignore.
Name
printer_brand
Type
string
défaut bambu
Description
La marque d'imprimante dont Meshy écrit le préréglage du trancheur dans le fichier 3MF. Le fichier s'ouvre ensuite dans le trancheur de cette marque avec une imprimante, un filament et un profil de processus correspondants. Le préréglage utilise l'imprimante par défaut de la marque, avec une buse de 0,4 mm.
Valeurs disponibles :
- bambu
- anycubic
- creality
- elegoo
- flashforge
- prusa
- qidi
- snapmaker
- ankermake
Toute autre valeur renvoie 400.

Retour

Le champ result de la réponse contient l'ID de la nouvelle tâche d'impression multicolore.

Modes d'échec

Name
400 - Bad Request
Description
La requête ne peut pas s'exécuter. Le message d'erreur indique le problème détecté. Par exemple :
- Paramètre manquant : Ni model_url ni input_task_id n'ont été envoyés.
- Format de modèle invalide : Le fichier model_url n'est pas un fichier .glb ou .fbx.
- URL inaccessible : Meshy ne peut pas télécharger le fichier model_url.
- Fichier modèle trop volumineux : Le fichier model_url dépasse 400 Mo depuis une URL http ou https, ou dépasse 100 Mo en tant que Data URI.
- Trop de faces : Le fichier model_url dépasse 100 Mo et compte plus de 8 000 000 de faces. Réduisez le nombre de faces, puis renvoyez le fichier.
- FBX ASCII de plus de 100 Mo : Le fichier model_url est un fichier FBX ASCII de plus de 100 Mo. Envoyez-le en FBX binaire ou en GLB.
- Fichier modèle illisible : Le fichier model_url dépasse 100 Mo, et Meshy ne peut pas lire son en-tête. Par exemple, il s'agit d'un GLB compressé avec Draco, ou d'un FBX binaire antérieur à la version 7.1.
- En-tête de modèle trop complexe : Le fichier model_url dépasse 100 Mo, et son en-tête contient trop de maillages, de nœuds ou d'enregistrements à vérifier. Réduisez le nombre d'objets dans le fichier, puis renvoyez-le.
- Tâche d'entrée invalide : input_task_id n'est pas une tâche réussie.
- Trop de faces dans la tâche d'entrée : Le modèle de input_task_id a plus de 8 000 000 de faces. Exécutez une tâche de Remaillage dessus, puis envoyez l'ID de cette tâche de remaillage à la place.
- max_colors invalide : max_colors est négatif ou dépasse 16.
- style invalide : style n'est ni realistic ni cartoon.
- max_depth invalide : max_depth est en dehors de la plage 3 à 6, et n'est pas 0.
- printer_brand invalide : printer_brand n'est pas l'une de ses valeurs disponibles.
- Aucune source de couleur : Le modèle manque de la couleur dont style a besoin. realistic nécessite une texture de couleur de base unique, avec des UV, sur chaque partie du maillage. cartoon accepte une texture de couleur de base ou des couleurs de sommets. Texturez d'abord le modèle, ou utilisez cartoon pour un modèle avec des couleurs de sommets. Meshy vérifie un envoi .fbx uniquement après que la tâche l'a normalisé, donc la tâche échoue avec model_missing_texture à la place.
Corrigez la requête, puis renvoyez-la. Voir Erreurs.
Name
401 - Unauthorized
Description
La clé API est manquante ou invalide. Vérifiez l'en-tête Authorization.
Name
402 - Payment Required
Description
Par exemple :
- Crédits insuffisants : Le compte n'a pas assez de crédits pour cette tâche, ou le compte a atteint une limite de crédits. Vérifiez votre solde de crédits, puis réessayez.
- Plan gratuit : La création d'une tâche nécessite un plan payant. Mettez à niveau votre plan dans vos paramètres d'abonnement, puis réessayez.
Name
403 - Forbidden
Description
input_task_id est un modèle en bas-relief, que ce point de terminaison ne peut pas imprimer. Le message est This model type does not support this operation. Envoyez un modèle différent.
Name
404 - Not Found
Description
input_task_id ne correspond à aucune de vos tâches. Vérifiez l'ID de la tâche, puis renvoyez la requête.
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit. Attendez, puis réessayez. Voir Limites de débit.

GET/openapi/v1/print/multi-color/:id

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

Renvoie une tâche d'impression multicolore à partir de son ID.

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
}

Paramètres

Name
id
Type
path
Description
L'ID de la tâche provenant de la réponse de création.

Renvoie

L'objet de tâche d'impression multicolore.

DELETE/openapi/v1/print/multi-color/:id

Supprimer une tâche d'impression multicolore

Supprime définitivement une tâche d'impression multicolore, y compris ses modèles et données. Vous ne pouvez pas annuler une suppression.

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 keeps 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."
}

Paramètres de chemin

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

Statut de la tâche

Supprimer une tâche PENDING rembourse les crédits utilisés lors de sa création.

Une tâche IN_PROGRESS ne peut pas être supprimée. La requête renvoie 409 Conflict, et la tâche continue de s'exécuter. Meshy ne rembourse pas une tâche qui a démarré, donc la supprimer vous coûterait à la fois les crédits et le résultat. Attendez qu'elle atteigne le statut SUCCEEDED, FAILED ou CANCELED, puis supprimez-la.

Supprimer une tâche dans un statut final (SUCCEEDED, FAILED ou CANCELED) ne rembourse pas ses crédits.

Retours

200 OK lorsque la tâche est supprimée, ou 409 Conflict lorsque la tâche est IN_PROGRESS.

GET/openapi/v1/print/multi-color

Lister les tâches d'impression multicolore

Renvoie une liste de vos tâches d'impression multicolore.

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

Paramètres

Name
page_num
Type
integer
défaut 1
Description
Le numéro de page à renvoyer. La numérotation des pages commence à 1.
Name
page_size
Type
integer
défaut 10
Description
Le nombre de tâches par page, jusqu'à 100.
Name
sort_by
Type
string
Description
L'ordre de tri.
Valeurs disponibles :
- +created_at : du plus ancien au plus récent
- -created_at : du plus récent au plus ancien

Retours

Une liste paginée d'objets de tâche d'impression multicolore.

GET/openapi/v1/print/multi-color/:id/stream

Diffuser en continu une tâche d'impression multicolore

Diffuse les mises à jour d'une tâche d'impression multicolore sous forme d'événements envoyés par le serveur (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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
}

Paramètres

Name
id
Type
path
Description
L'ID de la tâche provenant de la réponse de création.

Retours

Un flux d'objets de tâche d'impression multicolore sous forme d'événements envoyés par le serveur.

Chaque événement contient l'objet de tâche complet, dans la même forme que celle renvoyée par le point de terminaison Get. Tant que la tâche est PENDING ou IN_PROGRESS, ses champs de résultat n'ont pas encore de valeurs.

L'objet tâche d'impression multicolore

Un objet tâche d'impression multicolore décrit une conversion d'un modèle 3D en fichier 3MF multicolore. Il contient le statut, la progression et le fichier 3MF lorsque la tâche réussit.

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
}

Name
id
Type
string
Description
L'ID de la tâche. Traitez-le comme une chaîne opaque et ne vous fiez pas à son format.
Name
type
Type
string
Description
Le type de tâche, toujours print-multi-color.
Name
model_urls
Type
object
Description
Les URL de téléchargement pour le modèle imprimé, une par format de fichier. Un format que la tâche n'a pas généré n'a pas de clé, plutôt qu'une chaîne vide.
- Name
  3mf
  Type
  string
  Description
  Le fichier 3MF multicolore.
Name
progress
Type
integer
Description
La part de la tâche réalisée, en pourcentage. Elle vaut 0 tant que la tâche n'a pas démarré et 100 lorsqu'elle réussit.
Name
status
Type
string
Description
Le statut de la tâche, l'une des valeurs PENDING, IN_PROGRESS, SUCCEEDED ou FAILED.
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches devançant celle-ci dans la file d'attente. Cette valeur n'a de sens que tant que la tâche est PENDING.
Name
created_at
Type
timestamp
Description
Horodatage de création de la tâche, en millisecondes Unix.
Name
started_at
Type
timestamp
Description
Horodatage de démarrage de la tâche, en millisecondes Unix. Il vaut 0 tant que la tâche n'a pas démarré.
Name
finished_at
Type
timestamp
Description
Horodatage de fin de la tâche, en millisecondes Unix. Il vaut 0 tant que la tâche n'est pas terminée.
Name
task_error
Type
object
Description
Les détails de l'erreur lorsque la tâche échoue. Voir Erreurs.
Name
consumed_credits
Type
integer
Description
Le nombre de crédits consommés par la tâche. Présent lorsque le statut est PENDING, IN_PROGRESS ou SUCCEEDED. Il vaut 0 pour une tâche FAILED, car Meshy rembourse les crédits lorsqu'une tâche échoue.