Druckbarkeit reparieren API

Reparieren Sie ein 3D-Modell für die FDM-Druckbarkeit — beheben Sie nicht-mannigfaltige Kanten, entartete Flächen, Löcher und andere topology-Probleme, damit das Netz druckbereit ist.

POST/openapi/v1/print/repair

Erstellen einer Druckbarkeit-reparieren-Aufgabe

Dieser Endpunkt erstellt eine neue Druckbarkeit-reparieren-Aufgabe. Die Aufgabe führt eine Topologiereparatur an einem 3D-Modell durch und liefert eine wasserdichte, druckfertige Version zurück.

Das Ausgabeformat entspricht dem Eingabeformat. Wenn Sie eine .stl-Datei über model_url übermitteln, enthält model_urls.stl in der Antwort das reparierte Netz, während die übrigen Formatfelder leer bleiben. input_task_id liest immer das GLB der Ausgangsaufgabe, sodass die Ausgabe .glb ist.

Parameter

Nur eines von input_task_id oder model_url ist erforderlich. Werden beide angegeben, hat input_task_id Priorität.

Vorhandene Texturen werden während der Reparatur aufgrund von Geometrieänderungen entfernt. Um Texturen wieder hinzuzufügen, verwenden Sie die Retexture-API auf dem reparierten Modell.

  • Name
    input_task_id
    Type
    string
    Erforderlich
    Description

    Die ID einer erfolgreich abgeschlossenen Aufgabe, die Ihnen gehört. Unterstützte Aufgabentypen: Bild zu 3D, Multi-Bild zu 3D, Text zu 3D, Remesh und Retexture. Die Aufgabe muss den Status SUCCEEDED haben und muss ein GLB-Asset erzeugt haben.

  • Name
    model_url
    Type
    string
    Erforderlich
    Description

    URL eines zu reparierenden 3D-Modells. Unterstützte Formate: .glb, .gltf, .obj, .fbx, .stl. Maximale Dateigröße: 100 MB. Es muss http, https oder eine data:-URL verwendet werden (Data-URLs überspringen die Endungsprüfung).

  • Name
    alpha_thumbnail
    Type
    boolean
    Standard false
    Description

    Wenn dieser Wert auf true gesetzt ist, rendert die Aufgabe zusätzlich eine Version der Vorschau mit transparentem Hintergrund (RGBA) und gibt diese als alpha_thumbnail_url in der GET-Antwort zurück. Das vorhandene Feld thumbnail_url bleibt unverändert.

Rückgabewerte

Die Eigenschaft result der Antwort enthält die id der neu erstellten Druckbarkeit-reparieren-Aufgabe.

Fehlermodi

  • Name
    400 - Bad Request
    Description

    Die Anfrage war nicht akzeptabel. Häufige Ursachen:

    • Fehlender Parameter: Weder input_task_id noch model_url wurde angegeben.
    • Ungültige UUID: input_task_id ist keine gültige UUID.
    • Ungültige Modell-URL: model_url ist fehlerhaft formatiert, verwendet ein nicht unterstütztes Schema oder hat eine nicht unterstützte Dateiendung.
    • Modelldatei zu groß: Der Inhalt von model_url überschritt 100 MB.
    • Aufgabe nicht erfolgreich: Die referenzierte Aufgabe ist noch ausstehend, in Bearbeitung oder fehlgeschlagen.
    • Fehlendes GLB: Die referenzierte Aufgabe verfügt über kein zu reparierendes GLB-Asset.
  • Name
    401 - Unauthorized
    Description

    Die Authentifizierung ist fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.

  • Name
    402 - Payment Required
    Description

    Häufige Ursachen:

    • Kostenloser Plan: Das Erstellen von Aufgaben erfordert einen kostenpflichtigen Plan. Upgraden Sie auf der Abonnement-Seite.
    • Unzureichende Credits: Das Credit-Limit des Arbeitsbereichs wurde erreicht.
  • Name
    404 - Not Found
    Description

    Die referenzierte Aufgabe existiert nicht oder gehört einem anderen Benutzer.

  • Name
    429 - Too Many Requests
    Description

    Sie haben Ihr Kontingent für ausstehende Aufgaben oder die Ratenbegrenzung überschritten.

Request

POST
/openapi/v1/print/repair
# Repair an existing task
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Or repair a model URL directly
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.stl"
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/print/repair/:id

Eine Aufgabe zur Druckbarkeitsreparatur abrufen

Dieser Endpunkt ruft eine Aufgabe zur Druckbarkeitsreparatur anhand ihrer ID ab.

Parameter

  • Name
    id
    Type
    path
    Description

    Die ID der Aufgabe zur Druckbarkeitsreparatur, die abgerufen werden soll.

Rückgabewerte

Das Repair Printability Task Object. Der Block model_urls ist leer, bis die Aufgabe den Status SUCCEEDED erreicht. Nur das model_urls-Feld, das dem Eingabeformat entspricht, wird befüllt.

Request

GET
/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl https://api.meshy.ai/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}
DELETE/openapi/v1/print/repair/:id

Eine Aufgabe zur Druckbarkeitsreparatur löschen

Dieser Endpunkt löscht eine Aufgabe zur Druckbarkeit reparieren und ihre reparierte Ausgabe dauerhaft. Diese Aktion ist unwiderruflich.

Pfadparameter

  • Name
    id
    Type
    path
    Description

    Die ID der zu löschenden Aufgabe zur Druckbarkeit reparieren.

Aufgabenstatus

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

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

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

Rückgabewerte

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

Request

DELETE
/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/repair/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/repair

Liste der Aufgaben zur Druckbarkeitsreparatur

Dieser Endpunkt ermöglicht es Ihnen, eine Liste von Aufgaben zur Druckbarkeitsreparatur abzurufen.

Parameter

Optionale Attribute

  • Name
    page_num
    Type
    integer
    Description

    Seitenzahl für die Paginierung. Beginnt bei und ist standardmäßig 1.

  • Name
    page_size
    Type
    integer
    Description

    Seitengrößenbeschränkung. 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 Repair Printability Task Objects zurück.

Request

GET
/openapi/v1/print/repair
curl https://api.meshy.ai/openapi/v1/print/repair?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-repair",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000030000,
    "expires_at": 1715725401000,
    "task_error": null,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "gltf": "",
      "fbx": "",
      "obj": "",
      "stl": "",
      "usdz": "",
      "3mf": "",
      "mtl": ""
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "texture_urls": [],
    "consumed_credits": 10
  }
]
GET/openapi/v1/print/repair/:id/stream

Eine Aufgabe zur Druckbarkeitsreparatur streamen

Dieser Endpunkt streamt Echtzeit-Updates für eine Aufgabe zur Reparatur der Druckbarkeit mithilfe von Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Eindeutige Kennung der Aufgabe zur Reparatur der Druckbarkeit, die gestreamt werden soll.

Rückgabewerte

Gibt einen Stream von Objekten der Aufgabe „Druckbarkeit reparieren“ als Server-Sent Events zurück.

Jeder Frame enthält das vollständige Aufgabenobjekt für die jeweilige Phase – dieselbe Form, die der Get-Endpunkt zurückgibt. Solange die Aufgabe also PENDING oder IN_PROGRESS ist, sind die Ausgabefelder einfach noch nicht befüllt (null, [] oder {}) und finished_at ist null. Der model_urls-Block wird erst gesendet, sobald die Aufgabe den Status SUCCEEDED erreicht.

Request

GET
/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream
curl -N https://api.meshy.ai/openapi/v1/print/repair/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.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}

The Repair Printability Task Object

  • Name
    id
    Type
    string
    Description

    Eindeutiger Bezeichner für die Aufgabe. Auch wenn wir als Implementierungsdetail eine k-sortierbare UUID für Aufgaben-IDs verwenden, solltest du keine Annahmen über das Format der ID treffen.

  • Name
    type
    Type
    string
    Description

    Typ der Aufgabe zur Druckbarkeitsreparatur. Der Wert ist print-repair.

  • Name
    status
    Type
    string
    Description

    Status der Aufgabe. Mögliche Werte sind PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Fortschritt der Aufgabe. Wenn die Aufgabe noch nicht gestartet wurde, ist dieser Wert 0. Sobald die Aufgabe erfolgreich abgeschlossen wurde, wird dieser Wert 100.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Die Anzahl der vorausgehenden Aufgaben.

    Der Wert dieses Feldes ist nur dann aussagekräftig, wenn der Aufgabenstatus PENDING ist.

  • Name
    created_at
    Type
    timestamp
    Description

    Zeitstempel der Erstellung der Aufgabe, in Millisekunden.

  • Name
    started_at
    Type
    timestamp
    Description

    Zeitstempel des Starts der Aufgabe, in Millisekunden. Wenn die Aufgabe noch nicht gestartet wurde, ist dieser Wert 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Zeitstempel des Abschlusses der Aufgabe, in Millisekunden. Wenn die Aufgabe noch nicht abgeschlossen wurde, ist dieser Wert 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Zeitstempel, zu dem das Aufgabenergebnis aus dem System abläuft, in Millisekunden. 0, wenn die Aufgabe noch nicht abgeschlossen wurde.

  • Name
    task_error
    Type
    object
    Description

    Fehlerinformationen, falls die Aufgabe fehlgeschlagen ist. Diese Eigenschaft ist null, wenn die Aufgabe nicht fehlgeschlagen ist. Weitere Details findest du unter Fehler.

    • Name
      message
      Type
      string
      Description

      Fehlermeldung, die beschreibt, was schiefgelaufen ist.

  • Name
    model_urls
    Type
    object
    Description

    Herunterladbare URLs zum reparierten 3D-Modell. Nur das Feld, das dem Eingabeformat entspricht, wird befüllt; die übrigen Formatfelder sind leere Zeichenketten.

    • Name
      glb
      Type
      string
      Description

      Herunterladbare URL zum reparierten GLB. Wird befüllt, wenn die Eingabe ein GLB war oder wenn input_task_id verwendet wurde.

    • Name
      gltf
      Type
      string
      Description

      Herunterladbare URL zum reparierten GLTF. Wird befüllt, wenn die Eingabe ein GLTF-Upload war.

    • Name
      fbx
      Type
      string
      Description

      Herunterladbare URL zum reparierten FBX. Wird befüllt, wenn die Eingabe ein FBX-Upload war.

    • Name
      obj
      Type
      string
      Description

      Herunterladbare URL zum reparierten OBJ. Wird befüllt, wenn die Eingabe ein OBJ-Upload war.

    • Name
      stl
      Type
      string
      Description

      Herunterladbare URL zum reparierten STL. Wird befüllt, wenn die Eingabe ein STL-Upload war.

    • Name
      usdz
      Type
      string
      Description

      Reserviert für USDZ-Ausgabe. Bei Aufgaben zur Druckbarkeitsreparatur immer eine leere Zeichenkette.

    • Name
      3mf
      Type
      string
      Description

      Reserviert für 3MF-Ausgabe. Bei Aufgaben zur Druckbarkeitsreparatur immer eine leere Zeichenkette.

    • Name
      mtl
      Type
      string
      Description

      Reserviert für MTL-Ausgabe. Bei Aufgaben zur Druckbarkeitsreparatur immer eine leere Zeichenkette.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL eines Vorschaubilds, das aus dem reparierten Modell gerendert wurde.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    Herunterladbare URL zu einer Version von thumbnail_url mit transparentem Hintergrund (RGBA). Ist nur vorhanden, wenn die Aufgabe mit alpha_thumbnail: true erstellt wurde und die transparente Vorschau erfolgreich gerendert wurde; andernfalls wird dieses Feld weggelassen.

  • Name
    texture_urls
    Type
    array
    Description

    Immer ein leeres Array. Die Reparatur erhält nur die Eingabe-Geometrie und bäckt keine Texturen neu.

  • Name
    consumed_credits
    Type
    integer
    Description

    Die Anzahl der von dieser Aufgabe verbrauchten Credits. 10, sobald die Aufgabe den Status SUCCEEDED erreicht hat. Gibt 0 für Aufgaben mit Status FAILED zurück (Credits werden bei einem Fehlschlag zurückerstattet).

The Repair Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}