Druckbarkeit analysieren API

Analysieren Sie ein 3D-Modell auf FDM-Druckbarkeit — Wasserdichtigkeit, Volumen, Löcher, nicht-mannigfaltige Kanten und entartete Flächen.

POST/openapi/v1/print/analyze

Create an Analyze Printability Task

Dieser Endpunkt erstellt eine neue Aufgabe zur Analyse der Druckbarkeit. Die Aufgabe bewertet ein 3D-Modell und liefert dessen Druckbarkeitsmetriken.

Wenn die Eingabeaufgabe bereits eine zwischengespeicherte Druckbarkeit besitzt, ist die zurückgegebene Aufgabe sofort bereit, und der erste GET-Aufruf darauf liefert das Analyseergebnis, ohne den Worker zu durchlaufen.

Parameter

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

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, Neuvernetzung und Neutexturierung. Die Aufgabe muss Meshy 6 oder neuer verwenden (einschließlich Meshy 7) und den Status SUCCEEDED haben.

Name
model_url
Type
string
Erforderlich
Description
URL eines zu analysierenden 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 umgehen die Erweiterungsprüfung).

Rückgabewerte

Die Eigenschaft result der Antwort enthält die id der neu erstellten Aufgabe zur Druckbarkeitsanalyse.

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 Dateierweiterung.
- Modell-Datei zu groß: Der Inhalt von model_url überschritt 100 MB.
- Aufgabe nicht erfolgreich: Die referenzierte Aufgabe ist noch ausstehend, in Bearbeitung oder fehlgeschlagen.
Name
401 - Unauthorized
Description
Die Authentifizierung ist fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.
Name
403 - Forbidden
Description
Die Aufgabe existiert, gehört jedoch einem anderen Benutzer.
Name
404 - Not Found
Description
Häufige Ursachen:
- Die Aufgabe existiert nicht oder wurde gelöscht.
- Die Aufgabe verwendet ein Modell älter als Meshy 6, oder ihr Modus erzeugt kein 3D-Asset.
- Die zugrunde liegende Modell-Datei ist im Speicher nicht mehr verfügbar.
Name
429 - Too Many Requests
Description
Sie haben Ihr Kontingent für ausstehende Aufgaben oder die Ratenbegrenzung überschritten.

Request

POST

/openapi/v1/print/analyze

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

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

Response

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

GET/openapi/v1/print/analyze/:id

Druckbarkeit analysieren Task abrufen

Dieser Endpunkt ruft einen Analyze-Printability-Task anhand seiner ID ab.

Parameter

Name
id
Type
path
Description
Die ID des abzurufenden Analyze-Printability-Tasks.

Rückgabewerte

Das Analyze Printability Task Object. Das Feld printability ist null, bis der Task den Status SUCCEEDED erreicht.

Request

GET

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

DELETE/openapi/v1/print/analyze/:id

Eine Analyze-Printability-Aufgabe löschen

Dieser Endpunkt löscht eine Aufgabe zur Druckbarkeitsanalyse und ihr zwischengespeichertes Ergebnis dauerhaft. Diese Aktion ist unwiderruflich.

Pfadparameter

Name
id
Type
path
Description
Die ID der zu löschenden Aufgabe zur Druckbarkeitsanalyse.

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, sodass ein Löschen während der Ausführung sowohl die Credits als auch das Ergebnis kosten würde. Warten Sie, bis der Status SUCCEEDED, FAILED oder CANCELED erreicht ist, und löschen Sie die Aufgabe 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/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/analyze/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/analyze

Liste der Aufgaben zur Druckbarkeitsanalyse

Dieser Endpunkt ermöglicht es Ihnen, eine Liste von Aufgaben zur Druckbarkeitsanalyse 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: Sortiert nach Erstellungszeitpunkt in aufsteigender Reihenfolge.
- -created_at: Sortiert nach Erstellungszeitpunkt in absteigender Reihenfolge.

Rückgabewerte

Gibt eine paginierte Liste von Analyze-Printability-Task-Objekten zurück.

Request

GET

/openapi/v1/print/analyze

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-analyze",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "expires_at": 1715725401000,
    "task_error": null,
    "printability": {
      "_version": "v1",
      "status": "warning",
      "issue_count": 1,
      "error_count": 0,
      "warning_count": 1,
      "metrics": {
        "is_watertight": true,
        "volume": 1.316167354292668,
        "non_manifold_edges": 0,
        "degenerate_faces": 43242,
        "holes": 0
      },
      "evaluated_at": 1700000001000
    },
    "consumed_credits": 0
  }
]

GET/openapi/v1/print/analyze/:id/stream

Stream einer Analyze-Printability-Aufgabe

Dieser Endpunkt streamt Echtzeit-Updates für eine Aufgabe zur Druckbarkeitsanalyse mittels Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der Aufgabe zur Druckbarkeitsanalyse, die gestreamt werden soll.

Rückgabe

Gibt einen Stream von Analyze-Printability-Task-Objekten als Server-Sent Events zurück.

Jeder Frame enthält das vollständige Task-Objekt für die jeweilige Phase — dieselbe Struktur, die auch der Get-Endpunkt zurückgibt — daher sind die Ausgabefelder, solange die Aufgabe PENDING oder IN_PROGRESS ist, einfach noch nicht befüllt (null, [] oder {}) und finished_at ist null. Der printability-Block wird erst gesendet, wenn die Aufgabe den Status SUCCEEDED erreicht.

Request

GET

/openapi/v1/print/analyze/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/analyze/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-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

The Analyze Printability Task Object

Name
id
Type
string
Description
Eindeutige Kennung für die Aufgabe. Zwar verwenden wir als Implementierungsdetail eine k-sortierbare UUID für Aufgaben-IDs, Sie sollten jedoch keine Annahmen über das Format der ID treffen.
Name
type
Type
string
Description
Typ der Analyze-Printability-Aufgabe. Der Wert ist print-analyze.
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, 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 dieser Wert 0.
Name
finished_at
Type
timestamp
Description
Zeitstempel, wann die Aufgabe abgeschlossen wurde, in Millisekunden. Wenn die Aufgabe noch nicht abgeschlossen wurde, ist dieser Wert 0.
Name
expires_at
Type
timestamp
Description
Zeitstempel, wann das Ergebnis der Aufgabe im 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 Einzelheiten finden Sie unter Fehler.
- Name
  message
  Type
  string
  Description
  Fehlermeldung, die beschreibt, was schiefgelaufen ist.
Name
printability
Type
object
Description
Ergebnis der Druckbarkeitsbewertung. null, bis die Aufgabe den Status SUCCEEDED erreicht.
- Name
  _version
  Type
  string
  Description
  Schemaversion des Druckbarkeitsergebnisses. Derzeit v1.
- Name
  status
  Type
  string
  Description
  Gesamtstatus. Einer von:
  
  healthy: keine Fehler und keine Warnungen.
  
  warning: mindestens eine Warnung, keine Fehler.
  
  error: mindestens ein Fehler.
  
  unknown: das Modell konnte nicht analysiert werden.
- Name
  issue_count
  Type
  integer
  Description
  Gesamtanzahl der Probleme, entspricht error_count + warning_count.
- Name
  error_count
  Type
  integer
  Description
  Anzahl der Probleme auf Fehlerebene. Fehler werden ausgelöst, wenn das Modell nicht wasserdicht ist, ein nicht-positives Volumen aufweist oder nicht-mannigfaltige Kanten enthält.
- Name
  warning_count
  Type
  integer
  Description
  Anzahl der Probleme auf Warnebene. Warnungen werden ausgelöst, wenn das Modell entartete Flächen oder Löcher enthält.
- Name
  metrics
  Type
  object
  Description
  Rohdaten der Geometrie-Metriken, die vom Evaluator zurückgegeben werden.
  Name
  is_watertight
  Type
  boolean
  Description
  true, wenn das Netz keine Randkanten besitzt (d. h. geschlossen ist).
  Name
  volume
  Type
  number
  Description
  Volumen des Modells in Kubikmetern.
  Name
  non_manifold_edges
  Type
  integer
  Description
  Anzahl der nicht-mannigfaltigen Kanten.
  Name
  degenerate_faces
  Type
  integer
  Description
  Anzahl der entarteten Flächen (Flächen mit Nullfläche oder ungültige Flächen).
  Name
  holes
  Type
  integer
  Description
  Anzahl der Löcher (Randschleifen) im Netz.
- Name
  evaluated_at
  Type
  timestamp
  Description
  Zeitstempel, wann die Analyse berechnet wurde, in Millisekunden seit der Epoche.
Name
consumed_credits
Type
integer
Description
Immer 0. Dieser Endpunkt ist kostenlos.

The Analyze Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}