Mehrfarbdruck-API

Konvertieren Sie ein 3D-Modell in eine 3MF-Datei mit mehreren Farben für den 3D-Druck. Wählen Sie eine Palette mit bis zu 16 Farben und eine Slicer-Voreinstellung für Ihre Druckermarke.

POST/openapi/v1/print/multi-color

Eine Mehrfarbdruck-Aufgabe erstellen

Erstellt eine Mehrfarbdruck-Aufgabe, die ein 3D-Modell in eine mehrfarbige 3MF-Datei für den 3D-Druck konvertiert. Die Aufgabe läuft im Hintergrund. Wie lange eine Aufgabe üblicherweise dauert, erfahren Sie unter Verarbeitungszeiten.

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

Parameter

Name
input_task_id
Type
string
Erforderlich
Description
Erforderlich, sofern Sie nicht model_url senden. Die ID der Aufgabe, deren Modell Sie drucken möchten, zum Beispiel eine Bild zu 3D-, Multi-Bild zu 3D-, Text zu 3D-, Neuvernetzung- oder Neutexturierung-Aufgabe. Die Aufgabe muss eine sein, die Sie mit der API erstellt haben, und den Status SUCCEEDED haben.
Mehrfarbdruck liest die GLB-Datei der Aufgabe, die höchstens 8.000.000 Flächen haben darf. Ein Modell mit mehr Flächen liefert 400. Führen Sie in diesem Fall zuerst eine Neuvernetzung-Aufgabe dafür aus und senden Sie stattdessen die ID der Neuvernetzungs-Aufgabe.

Name
model_url
Type
string
Erforderlich
Description
Erforderlich, sofern Sie nicht input_task_id senden. Das zu druckende Modell, als öffentliche URL oder als Data URI. Wenn Sie beides senden, verwendet Meshy input_task_id.
Eine http- oder https-URL muss auf eine .glb- oder .fbx-Datei von höchstens 400 MB verweisen. Eine Data URI muss eine base64-kodierte GLB-Datei von höchstens 100 MB enthalten. Verwenden Sie data:model/gltf-binary;base64,. Senden Sie eine .fbx-Datei als http- oder https-URL.
Eine Datei über 100 MB muss zusätzlich diese Regeln erfüllen:
- Sie darf höchstens 8.000.000 Flächen haben. Meshy zählt Flächen als Dreiecke, sodass ein Viereck als 2 zählt und ein mehrfach gezeichnetes Netz pro Kopie einmal gezählt wird.
- Eine FBX-Datei muss binäres FBX 7.1 oder neuer sein.
- Eine GLB-Datei darf keine Draco-Kompression verwenden.

Name
max_colors
Type
integer
Standard 4
Description
Die maximale Anzahl an Farben in der Ausgabepalette, von 1 bis 16. Um den Standardwert zu verwenden, lassen Sie den Parameter weg, statt 0 zu senden.
Name
style
Type
string
Standard realistic
Description
Der Farbstil der 3MF-Datei.
Verfügbare Werte:
- realistic: entnimmt Farben direkt aus der Textur des Modells für feine, fotorealistische Details und erzeugt eine größere Datei.
- cartoon: reduziert Farben auf saubere, einheitliche Bereiche für ein stilisiertes Aussehen und erzeugt eine kleinere Datei.
Das Modell muss Farbe aufweisen. realistic benötigt eine einzelne Basisfarbtextur mit UVs auf jedem Netzteil, und cartoon akzeptiert zusätzlich Vertexfarben. Meshy lehnt ein unstrukturiertes (weißes) Modell ab. Siehe model_missing_texture.
Name
max_depth
Type
integer
Standard 4
Description
Die Unterteilungstiefe, die Meshy verwendet, um Texturfarben auf das Netz abzutasten, von 3 bis 6. 0 entspricht dem Weglassen des Parameters. Höhere Werte erfassen feinere Farbdetails und erzeugen eine größere Datei. Nur der Stil realistic nutzt diesen Parameter; cartoon ignoriert ihn.
Name
printer_brand
Type
string
Standard bambu
Description
Die Druckermarke, deren Slicer-Voreinstellung Meshy in die 3MF-Datei schreibt. Die Datei öffnet sich dann im Slicer dieser Marke mit passendem Drucker-, Filament- und Prozessprofil. Die Voreinstellung verwendet den Standarddrucker der Marke mit einer 0,4-mm-Düse.
Verfügbare Werte:
- bambu
- anycubic
- creality
- elegoo
- flashforge
- prusa
- qidi
- snapmaker
- ankermake
Jeder andere Wert liefert 400.

Rückgabewerte

Das Feld result der Antwort enthält die ID der neuen Mehrfarbdruck-Aufgabe.

Fehlermodi

Name
400 - Bad Request
Description
Die Anfrage kann nicht ausgeführt werden. Die Fehlermeldung nennt das gefundene Problem. Zum Beispiel:
- Fehlender Parameter: Weder model_url noch input_task_id wurde gesendet.
- Ungültiges Modellformat: Die model_url-Datei ist keine .glb- oder .fbx-Datei.
- Nicht erreichbare URL: Meshy kann die model_url-Datei nicht herunterladen.
- Modelldatei zu groß: Die model_url-Datei ist über 400 MB groß bei einer http- oder https-URL, oder über 100 MB als Data URI.
- Zu viele Flächen: Die model_url-Datei ist über 100 MB groß und hat mehr als 8.000.000 Flächen. Reduzieren Sie die Flächenanzahl und senden Sie die Datei erneut.
- ASCII-FBX über 100 MB: Die model_url-Datei ist eine ASCII-FBX-Datei über 100 MB. Senden Sie sie als binäre FBX- oder GLB-Datei.
- Nicht lesbare Modelldatei: Die model_url-Datei ist über 100 MB groß, und Meshy kann ihren Header nicht lesen. Zum Beispiel handelt es sich um eine Draco-komprimierte GLB-Datei oder eine binäre FBX-Datei älter als 7.1.
- Modell-Header zu komplex: Die model_url-Datei ist über 100 MB groß, und ihr Header enthält zu viele Netze, Knoten oder Einträge zum Prüfen. Reduzieren Sie die Anzahl der Objekte in der Datei und senden Sie sie erneut.
- Ungültige Eingabeaufgabe: input_task_id ist keine erfolgreiche Aufgabe.
- Zu viele Flächen in der Eingabeaufgabe: Das Modell von input_task_id hat mehr als 8.000.000 Flächen. Führen Sie dafür eine Neuvernetzung-Aufgabe aus und senden Sie stattdessen die ID der Neuvernetzungs-Aufgabe.
- Ungültiges max_colors: max_colors ist negativ oder über 16.
- Ungültiger style: style ist weder realistic noch cartoon.
- Ungültiges max_depth: max_depth liegt außerhalb von 3 bis 6 und ist nicht 0.
- Ungültiges printer_brand: printer_brand ist keiner der verfügbaren Werte.
- Keine Farbquelle: Dem Modell fehlt die Farbe, die style benötigt. realistic benötigt eine einzelne Basisfarbtextur mit UVs auf jedem Netzteil. cartoon akzeptiert eine Basisfarbtextur oder Vertexfarben. Texturieren Sie das Modell zuerst, oder verwenden Sie cartoon für ein Modell mit Vertexfarben. Meshy prüft einen .fbx-Upload erst, nachdem die Aufgabe ihn normalisiert hat, sodass die Aufgabe stattdessen mit model_missing_texture fehlschlägt.
Korrigieren Sie die Anfrage und senden Sie sie erneut. Siehe Fehler.
Name
401 - Unauthorized
Description
Der API-Schlüssel fehlt oder ist ungültig. Überprüfen Sie den Authorization-Header.
Name
402 - Payment Required
Description
Zum Beispiel:
- Unzureichende Credits: Das Konto hat nicht genügend Credits für diese Aufgabe, oder das Konto hat ein Credit-Limit erreicht. Prüfen Sie Ihr Credit-Guthaben und versuchen Sie es erneut.
- Kostenloser Plan: Das Erstellen einer Aufgabe erfordert einen kostenpflichtigen Plan. Aktualisieren Sie Ihren Plan in den Abonnement-Einstellungen und versuchen Sie es erneut.
Name
403 - Forbidden
Description
input_task_id ist ein Flachrelief-Modell, das dieser Endpunkt nicht drucken kann. Die Meldung lautet This model type does not support this operation. Senden Sie ein anderes Modell.
Name
404 - Not Found
Description
input_task_id entspricht keiner Ihrer Aufgaben. Überprüfen Sie die Aufgaben-ID und senden Sie die Anfrage erneut.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten. Warten Sie und versuchen Sie es erneut. Siehe Ratenbegrenzungen.

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

Multi-Color-Print-Task abrufen

Gibt einen Mehrfarbdruck-Task anhand seiner ID zurück.

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
}

Parameter

Name
id
Type
path
Description
Die Task-ID aus der Antwort der Erstellung.

Rückgabe

Das Mehrfarbdruck-Task-Objekt.

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

Einen Mehrfarbdruck-Task löschen

Löscht einen Mehrfarbdruck-Task dauerhaft, einschließlich seiner Modelle und Daten. Ein Löschvorgang kann nicht rückgängig gemacht werden.

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

Pfadparameter

Name
id
Type
path
Description
Die ID des zu löschenden Tasks.

Task-Status

Das Löschen eines Tasks mit dem Status PENDING erstattet die beim Erstellen verwendeten Credits zurück.

Ein Task mit dem Status IN_PROGRESS kann nicht gelöscht werden. Die Anfrage gibt 409 Conflict zurück, und der Task läuft weiter. Meshy erstattet keine Credits für einen bereits gestarteten Task, daher würde ein Löschen sowohl die Credits als auch das Ergebnis kosten. Warten Sie, bis der Task SUCCEEDED, FAILED oder CANCELED erreicht, und löschen Sie ihn dann.

Das Löschen eines Tasks mit einem finalen Status (SUCCEEDED, FAILED oder CANCELED) erstattet dessen Credits nicht zurück.

Rückgabewerte

200 OK, wenn der Task gelöscht wurde, oder 409 Conflict, wenn sich der Task im Status IN_PROGRESS befindet.

GET/openapi/v1/print/multi-color

Multi-Color-Print-Aufgaben auflisten

Gibt eine Liste deiner Multi-Color-Print-Aufgaben zurück.

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

Parameter

Name
page_num
Type
integer
Standard 1
Description
Die zurückzugebende Seitennummer. Die Seitennummerierung beginnt bei 1.
Name
page_size
Type
integer
Standard 10
Description
Die Anzahl der Aufgaben pro Seite, bis zu 100.
Name
sort_by
Type
string
Description
Die Sortierreihenfolge.
Verfügbare Werte:
- +created_at: älteste zuerst
- -created_at: neueste zuerst

Rückgabe

Eine paginierte Liste von Multi-Color-Print-Aufgabenobjekten.

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

Einen Mehrfarbdruck-Task streamen

Streamt die Updates eines Mehrfarbdruck-Tasks als Server-Sent Events (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
}

Parameter

Name
id
Type
path
Description
Die Task-ID aus der Create-Antwort.

Rückgabe

Ein Stream von Mehrfarbdruck-Task-Objekten als Server-Sent Events.

Jedes Event enthält das vollständige Task-Objekt, in derselben Form, die der Get-Endpunkt zurückgibt. Solange der Task PENDING oder IN_PROGRESS ist, haben seine Ergebnisfelder noch keine Werte.

Das Mehrfarbdruck-Task-Objekt

Ein Mehrfarbdruck-Task-Objekt beschreibt eine Umwandlung eines 3D-Modells in eine Mehrfarbdruck-3MF-Datei. Es enthält den Status, den progress und die 3MF-Datei, wenn der Task erfolgreich ist.

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
Die Task-ID. Behandeln Sie sie als eine undurchsichtige Zeichenkette und verlassen Sie sich nicht auf ihr Format.
Name
type
Type
string
Description
Der Task-Typ, immer print-multi-color.
Name
model_urls
Type
object
Description
Download-URLs für das gedruckte Modell, eine pro Dateiformat. Ein Format, das der Task nicht generiert hat, besitzt keinen Schlüssel, statt einer leeren Zeichenkette.
- Name
  3mf
  Type
  string
  Description
  Die Mehrfarbdruck-3MF-Datei.
Name
progress
Type
integer
Description
Wie viel vom Task bereits erledigt ist, in Prozent. Der Wert ist 0, bis der Task startet, und 100, wenn er erfolgreich ist.
Name
status
Type
string
Description
Der Task-Status, einer von PENDING, IN_PROGRESS, SUCCEEDED oder FAILED.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der Tasks, die in der Warteschlange vor diesem stehen. Der Wert ist nur aussagekräftig, solange der Task PENDING ist.
Name
created_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task erstellt wurde, in Unix-Millisekunden.
Name
started_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task gestartet wurde, in Unix-Millisekunden. Der Wert ist 0, bis der Task startet.
Name
finished_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task beendet wurde, in Unix-Millisekunden. Der Wert ist 0, bis der Task beendet ist.
Name
task_error
Type
object
Description
Die Fehlerdetails, wenn der Task fehlschlägt. Siehe Fehler.
Name
consumed_credits
Type
integer
Description
Die Anzahl der vom Task verbrauchten Credits. Vorhanden, wenn der Status PENDING, IN_PROGRESS oder SUCCEEDED ist. Bei einem FAILED-Task ist der Wert 0, da Meshy die Credits erstattet, wenn ein Task fehlschlägt.