Mehrfarbdruck-API

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

POST/openapi/v1/print/multi-color

Erstellen einer Multi-Color 3D-Druckaufgabe

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

Parameter

Nur einer von input_task_id oder model_url ist erforderlich. Wenn beide angegeben sind, hat input_task_id Priorität.

Name
input_task_id
Type
string
Erforderlich
Description
Die ID einer erfolgreichen Aufgabe, die als Eingabe verwendet werden soll. Unterstützte Aufgabentypen: Bild zu 3D, Multi-Bild zu 3D, Text zu 3D, Neuvernetzung und Neutexturierung. 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
style
Type
string
Standard realistic
Description
Visueller Farbstil der generierten 3MF-Datei.
Verfügbare Werte:
- realistic: Nimmt Farben direkt aus der Textur des Modells für feine, fotorealistische Details. Erzeugt eine größere Datei.
- cartoon: Glättet Farben in saubere, einheitliche Bereiche für einen stilisierten Look. Erzeugt eine kleinere Datei.

Rückgaben

Die result-Eigenschaft 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 sich auf eine erfolgreiche Aufgabe beziehen.
- Ungültige max_colors: Der Wert muss zwischen 1 und 16 liegen.
- Ungültiger Stil: Der Wert muss realistic oder cartoon sein.
Name
401 - Unauthorized
Description
Authentifizierung fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.
Name
402 - Payment Required
Description
Nicht genügend Credits, um diese Aufgabe auszuführen.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten.

Anfrage

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

Antwort

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

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

Abrufen einer Mehrfarben-3D-Druckaufgabe

Dieser Endpunkt ruft eine Mehrfarben-3D-Druckaufgabe anhand ihrer ID ab.

Parameter

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

Rückgaben

Das 3D-Druckaufgaben-Objekt.

Anfrage

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

Antwort

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

Löschen einer Mehrfarben-3D-Druckaufgabe

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

Pfadparameter

Name
id
Type
path
Description
Die ID der Mehrfarben-3D-Druckaufgabe, die gelöscht werden soll.

Rückgaben

Gibt 200 OK bei Erfolg zurück.

Anfrage

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

Antwort

// Returns 200 Ok on success.

GET/openapi/v1/print/multi-color

Liste der Mehrfarb-3D-Druckaufgaben

Dieser Endpunkt ermöglicht es Ihnen, eine Liste von Mehrfarb-3D-Druckaufgaben abzurufen.

Parameter

Optionale Attribute

Name
page_num
Type
integer
Description
Seitenzahl für die Paginierung. Beginnt und standardmäßig auf 1.
Name
page_size
Type
integer
Description
Seitenlimit. Standardmäßig 10 Elemente. Maximal erlaubt sind 50 Elemente.
Name
sort_by
Type
string
Description
Feld zum Sortieren. Verfügbare Werte:
- +created_at: Sortieren nach Erstellungszeit in aufsteigender Reihenfolge.
- -created_at: Sortieren nach Erstellungszeit in absteigender Reihenfolge.

Rückgaben

Gibt eine paginierte Liste der 3D-Druckaufgaben-Objekte zurück.

Anfrage

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

Antwort

[
  {
    "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 Endpunkt streamt Echtzeit-Updates für eine mehrfarbige 3D-Druckaufgabe unter Verwendung von Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Eindeutiger Bezeichner für die mehrfarbige 3D-Druckaufgabe, die gestreamt werden soll.

Rückgaben

Gibt einen Stream von The 3D Print Task Objects als Server-Sent Events zurück.

Für PENDING oder IN_PROGRESS Aufgaben enthält der Antwortstream nur die notwendigen progress und status Felder.

Anfrage

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

Antwortstream

// 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
Eindeutiger Bezeichner für die Aufgabe. Obwohl wir eine k-sortierbare UUID für Aufgaben-IDs als Implementierungsdetail verwenden, sollten Sie keine Annahmen über das Format der ID machen.
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 3D-Modell-Datei, die von Meshy generiert wurde. Die Eigenschaft für ein Format wird weggelassen, wenn das Format nicht generiert wird, anstatt einen leeren String 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 ist, wird dies 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 vorhergehenden Aufgaben.
Der Wert dieses Feldes ist nur sinnvoll, 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 ist, ist diese Eigenschaft 0.
Name
task_error
Type
object
Description
Fehlerdetails für fehlgeschlagene Aufgaben. Siehe Fehler für die vollständige task_error Objekt-Referenz.
Name
consumed_credits
Type
integer
Description
Die Anzahl der Credits, die von dieser Aufgabe verbraucht wurden. Vorhanden, wenn der Aufgabenstatus PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED Aufgaben zurück (Credits werden bei einem Fehler zurückerstattet).

Das 3D-Druck-Aufgabenobjekt

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