Multi-Color Print API

Konvertieren Sie 3D-Modelle in das mehrfarbige 3MF-Format für den 3D-Druck, mit einer konfigurierbaren Farbpalette von bis zu 16 Farben.

POST/openapi/v1/print/multi-color

Multi-Color-3D-Druckaufgabe erstellen

Dieser endpoint erstellt eine neue Multi-Color-3D-Druckaufgabe. Die Aufgabe konvertiert ein 3D-Modell in eine mehrfarbige 3MF-Datei, die für den 3D-Druck geeignet ist.

Parameter

Nur eines von input_task_id oder model_url ist erforderlich. Wenn beide angegeben werden, hat input_task_id Vorrang.

Name
input_task_id
Type
string
Erforderlich
Description
Die ID einer erfolgreich abgeschlossenen Aufgabe, die als Eingabe verwendet werden soll. Unterstützte Aufgabentypen: Bild zu 3D, Multi-Bild zu 3D, Text zu 3D, Remesh und Retexture. Die Aufgabe muss den Status SUCCEEDED haben.

Name
model_url
Type
string
Erforderlich
Description
Öffentlich zugängliche URL oder Data URI eines 3D-Modells. Wir unterstützen derzeit die Formate .glb und .fbx.

Name
max_colors
Type
integer
Standard 4
Description
Maximale Anzahl von Farben in der Ausgabepalette.
Gültiger Bereich: 1 bis 16.
Name
max_depth
Type
integer
Standard 4
Description
Quadtree-Tiefe für Farbpräzision. Höhere Werte erzeugen feinere Farbgrenzen, erhöhen aber die Dateigröße.
Gültiger Bereich: 3 bis 6.

Rückgabewerte

Die Eigenschaft result der Antwort enthält die id der neu erstellten 3D-Druckaufgabe.

Fehlermodi

Name
400 - Bad Request
Description
Die Anfrage war nicht akzeptabel. Häufige Ursachen:
- Fehlender Parameter: Entweder model_url oder input_task_id muss angegeben werden.
- Ungültiges Modellformat: Die model_url verweist auf eine Datei mit einer nicht unterstützten Erweiterung (nur .glb und .fbx werden unterstützt).
- Nicht erreichbare URL: Die model_url konnte nicht heruntergeladen werden.
- Ungültige Eingabeaufgabe: Die input_task_id muss auf eine erfolgreiche Aufgabe verweisen.
- Ungültiges max_colors: Der Wert muss zwischen 1 und 16 liegen.
- Ungültiges max_depth: Der Wert muss zwischen 3 und 6 liegen.
Name
401 - Unauthorized
Description
Authentifizierung fehlgeschlagen. Bitte prüfen Sie Ihren API key.
Name
402 - Payment Required
Description
Nicht genügend Credits, um diese Aufgabe auszuführen.
Name
429 - Too Many Requests
Description
Sie haben Ihr Ratenlimit überschritten.

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,
    "max_depth": 5
  }'

Response

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

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

Eine mehrfarbige 3D-Druckaufgabe abrufen

Dieser endpoint ruft eine mehrfarbige 3D-Druckaufgabe anhand ihrer ID ab.

Parameter

Name
id
Type
path
Description
Die ID der abzurufenden 3D-Druckaufgabe.

Rückgabe

Das 3D-Druckaufgabenobjekt.

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

Mehrfarbige 3D-Druckaufgabe löschen

Dieser endpoint löscht dauerhaft eine mehrfarbige 3D-Druckaufgabe, einschließlich aller zugehörigen Modelle und Daten. Diese Aktion ist irreversibel.

Pfadparameter

Name
id
Type
path
Description
Die ID der zu löschenden mehrfarbigen 3D-Druckaufgabe.

Rückgabe

Gibt bei Erfolg 200 OK zurück.

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

// Returns 200 Ok on success.

GET/openapi/v1/print/multi-color

Multi-Color-3D-Druckaufgaben auflisten

Dieser endpoint ermöglicht es Ihnen, eine Liste von Multi-Color-3D-Druckaufgaben abzurufen.

Parameter

Optionale Attribute

Name
page_num
Type
integer
Description
Seitennummer für die Paginierung. Beginnt bei 1 und ist standardmäßig 1.
Name
page_size
Type
integer
Description
Limit für die Seitengröße. Standardmäßig 10 Elemente. Maximal erlaubt sind 50 Elemente.
Name
sort_by
Type
string
Description
Feld, nach dem sortiert werden soll. Verfügbare Werte:
- +created_at: Nach Erstellungszeit in aufsteigender Reihenfolge sortieren.
- -created_at: Nach Erstellungszeit in absteigender Reihenfolge sortieren.

Rückgabe

Gibt eine paginierte Liste der 3D-Druckaufgabenobjekte 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
  }
]

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

Streamen einer mehrfarbigen 3D-Druckaufgabe

Dieser endpoint streamt Echtzeit-Updates für eine mehrfarbige 3D-Druckaufgabe mithilfe von Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der zu streamenden mehrfarbigen 3D-Druckaufgabe.

Rückgaben

Gibt einen Stream von den 3D-Druckaufgabenobjekten als Server-Sent Events zurück.

Für Aufgaben mit PENDING oder IN_PROGRESS enthält der Antwort-Stream nur die erforderlichen Felder progress und status.

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
}

Das 3D-Druck-Aufgabenobjekt

Name
id
Type
string
Description
Eindeutige Kennung für die Aufgabe. Obwohl wir als Implementierungsdetail eine k-sortierbare UUID für Aufgaben-IDs verwenden, sollten Sie keine Annahmen über das Format der ID treffen.
Name
type
Type
string
Description
Typ der 3D-Druck-Aufgabe. Der Wert ist print-multi-color.
Name
model_urls
Type
object
Description
Herunterladbare URL zur von Meshy generierten 3D-Modelldatei. Die Eigenschaft für ein Format wird weggelassen, wenn das Format nicht generiert wird, anstatt eine leere Zeichenfolge zurückzugeben.
- Name
  3mf
  Type
  string
  Description
  Herunterladbare URL zur mehrfarbigen 3MF-Datei.
Name
progress
Type
integer
Description
Fortschritt der Aufgabe. Wenn die Aufgabe noch nicht gestartet wurde, ist diese Eigenschaft 0. Sobald die Aufgabe erfolgreich abgeschlossen wurde, wird sie zu 100.
Name
status
Type
string
Description
Status der Aufgabe. Mögliche Werte sind einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der vorangehenden Aufgaben.
Der Wert dieses Feldes ist nur dann aussagekräftig, wenn der Aufgabenstatus PENDING ist.
Name
created_at
Type
timestamp
Description
Zeitstempel, wann die Aufgabe erstellt wurde, in Millisekunden.
Name
started_at
Type
timestamp
Description
Zeitstempel, wann die Aufgabe gestartet wurde, in Millisekunden. Wenn die Aufgabe noch nicht gestartet wurde, ist diese Eigenschaft 0.
Name
finished_at
Type
timestamp
Description
Zeitstempel, wann die Aufgabe abgeschlossen wurde, in Millisekunden. Wenn die Aufgabe noch nicht abgeschlossen wurde, ist diese Eigenschaft 0.
Name
task_error
Type
object
Description
Fehlerdetails für fehlgeschlagene Aufgaben. Siehe Fehler für die vollständige task_error-Objektreferenz.
Name
consumed_credits
Type
integer
Description
Die Anzahl der von dieser Aufgabe verbrauchten Credits. Vorhanden, wenn der Aufgabenstatus PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED-Aufgaben zurück (Credits werden bei einem Fehlschlag erstattet).

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
}