Multi-Color-Print-API

Konvertieren Sie 3D-Modelle in das Mehrfarben-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-Druckauftrag erstellen

Dieser Endpunkt erstellt einen neuen Multi-Color-3D-Druckauftrag. Der Auftrag konvertiert ein 3D-Modell in eine mehrfarbige 3MF-Datei, die für den 3D-Druck geeignet ist.

Parameter

Nur einer der beiden Parameter input_task_id oder model_url ist erforderlich. Wenn beide angegeben werden, hat input_task_id Priorität.

  • 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 an 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: Übernimmt Farben direkt aus der Textur des Modells für feine, fotorealistische Details. Erzeugt eine größere Datei.
    • cartoon: Reduziert Farben auf saubere, einheitliche Bereiche für einen stilisierten Look. Erzeugt eine kleinere Datei.

    Die Eingabe muss Farbinformationen enthalten: realistic erfordert eine einzelne Basisfarbtextur mit UV-Koordinaten auf jedem Netzteil; cartoon akzeptiert auch Vertex-Farben. Modelle ohne Textur (weiß) werden abgelehnt — siehe model_missing_texture.

Rückgabewerte

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

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: model_url verweist auf eine Datei mit nicht unterstützter Dateiendung (nur .glb und .fbx werden unterstützt).
    • Nicht erreichbare URL: model_url konnte nicht heruntergeladen werden.
    • Ungültiger Eingabeauftrag: input_task_id muss sich auf einen erfolgreichen Auftrag beziehen.
    • Ungültiger max_colors-Wert: Der Wert muss zwischen 1 und 16 liegen.
    • Ungültiger style-Wert: Der Wert muss realistic oder cartoon sein.
    • Keine Farbquelle: Das Eingabemodell hat keine Basisfarbtextur (realistic benötigt genau eine, mit UVs, auf jedem Netzteil) und keine Vertex-Farben (cartoon akzeptiert beides). Texturieren Sie das Modell zuerst oder verwenden Sie cartoon für Modelle mit Vertex-Farben. .fbx-Uploads werden geprüft, nachdem der Auftrag sie normalisiert hat, und schlagen stattdessen mit model_missing_texture fehl.
  • Name
    401 - Unauthorized
    Description

    Die Authentifizierung ist 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.

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

Einen Multi-Color-3D-Druckauftrag abrufen

Dieser Endpunkt ruft einen Multi-Color-3D-Druckauftrag anhand seiner ID ab.

Parameter

  • Name
    id
    Type
    path
    Description

    Die ID des abzurufenden 3D-Druckauftrags.

Rückgabewerte

Das 3D-Druckauftrag-Objekt.

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

Einen Multi-Color-3D-Druckauftrag löschen

Dieser Endpunkt löscht einen Multi-Color-3D-Druckauftrag dauerhaft, einschließlich aller zugehörigen Modelle und Daten. Diese Aktion ist unwiderruflich.

Pfad-Parameter

  • Name
    id
    Type
    path
    Description

    Die ID des zu löschenden Multi-Color-3D-Druckauftrags.

Aufgabenstatus

Ein Auftrag, der sich noch im Status PENDING befindet, wird gelöscht, und die bei der Erstellung verbrauchten Credits werden zurückerstattet.

Ein Auftrag, der sich bereits im Status IN_PROGRESS befindet, kann nicht gelöscht werden: Die Anfrage wird mit 409 Conflict abgelehnt, und der Auftrag läuft weiter. Credits für einen Auftrag, den der Worker bereits gestartet hat, sind nicht erstattungsfähig, daher würde das Löschen während der Ausführung sowohl die Credits als auch das Ergebnis kosten. Warten Sie, bis er den Status SUCCEEDED, FAILED oder CANCELED erreicht, und löschen Sie ihn dann.

Ein Auftrag in einem Endzustand (SUCCEEDED, FAILED oder CANCELED) wird ohne Rückerstattung gelöscht.

Rückgabe

Gibt bei Erfolg 200 OK zurück, oder 409 Conflict, wenn sich der Auftrag im Status IN_PROGRESS befindet.

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

Multi-Color-3D-Druckaufgaben auflisten

Dieser Endpunkt 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 und ist standardmäßig 1.

  • Name
    page_size
    Type
    integer
    Description

    Begrenzung der Seitengröße. Standardmäßig 10 Einträge. Maximal zulässig sind 100 Einträge.

  • Name
    sort_by
    Type
    string
    Description

    Feld, nach dem sortiert werden soll. Verfügbare Werte:

    • +created_at: Sortierung nach Erstellungszeit in aufsteigender Reihenfolge.
    • -created_at: Sortierung nach Erstellungszeit in absteigender Reihenfolge.

Rückgabewerte

Gibt eine paginierte Liste von Die 3D-Druckaufgaben-Objekte 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 Mehrfarben-3D-Druckaufgabe

Dieser Endpunkt streamt Echtzeit-Updates für eine Mehrfarben-3D-Druckaufgabe mittels Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Eindeutige Kennung der Mehrfarben-3D-Druckaufgabe, die gestreamt werden soll.

Rückgabewerte

Gibt einen Stream von 3D-Druckaufgaben-Objekten als Server-Sent Events zurück.

Bei Aufgaben mit dem Status PENDING oder IN_PROGRESS enthält der Antwort-Stream nur die notwendigen 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-Task-Objekt

  • Name
    id
    Type
    string
    Description

    Eindeutige Kennung für den Task. Obwohl wir als Implementierungsdetail eine k-sortierbare UUID für Task-IDs verwenden, sollten Sie keine Annahmen über das Format der ID treffen.

  • Name
    type
    Type
    string
    Description

    Typ des 3D-Druck-Tasks. 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 wurde, anstatt eine leere Zeichenkette zurückzugeben.

    • Name
      3mf
      Type
      string
      Description

      Herunterladbare URL zur mehrfarbigen 3MF-Datei.

  • Name
    progress
    Type
    integer
    Description

    Fortschritt des Tasks. Wenn der Task noch nicht gestartet wurde, ist diese Eigenschaft 0. Sobald der Task erfolgreich abgeschlossen wurde, wird sie 100.

  • Name
    status
    Type
    string
    Description

    Status des Tasks. Mögliche Werte sind PENDING, IN_PROGRESS, SUCCEEDED, FAILED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Die Anzahl der vorangehenden Tasks.

    Der Wert dieses Felds ist nur dann aussagekräftig, wenn der Task-Status PENDING ist.

  • Name
    created_at
    Type
    timestamp
    Description

    Zeitstempel, wann der Task erstellt wurde, in Millisekunden.

  • Name
    started_at
    Type
    timestamp
    Description

    Zeitstempel, wann der Task gestartet wurde, in Millisekunden. Wenn der Task noch nicht gestartet wurde, ist diese Eigenschaft 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Zeitstempel, wann der Task abgeschlossen wurde, in Millisekunden. Wenn der Task noch nicht abgeschlossen wurde, ist diese Eigenschaft 0.

  • Name
    task_error
    Type
    object
    Description

    Fehlerdetails für fehlgeschlagene Tasks. Siehe Fehler für die vollständige Referenz des task_error-Objekts.

  • Name
    consumed_credits
    Type
    integer
    Description

    Die Anzahl der von diesem Task verbrauchten Credits. Vorhanden, wenn der Task-Status PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED-Tasks zurück (Credits werden bei einem Fehlschlag zurückerstattet).

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
}