Analizuj drukowalność API

Przeanalizuj model 3D pod kątem drukowalności FDM — szczelności, objętości, otworów, krawędzi non-manifold i zdegenerowanych ścian.

POST/openapi/v1/print/analyze

Utwórz zadanie Analizuj drukowalność

Ten punkt końcowy tworzy nowe zadanie analizy drukowalności. Zadanie ocenia model 3D i raportuje jego metryki drukowalności.

Jeśli zadanie wejściowe ma już zbuforowaną drukowalność, zwrócone zadanie jest natychmiast gotowe, a pierwsze wywołanie GET na nim zwróci wynik analizy bez przechodzenia przez worker.

Parametry

Wymagane jest tylko jedno z input_task_id lub model_url. Jeśli podano obie wartości, input_task_id ma priorytet.

Name
input_task_id
Type
string
Wymagane
Description
ID zakończonego sukcesem zadania, którego jesteś właścicielem. Wspierane typy zadań: Obraz na 3D, Wiele obrazów na 3D, Tekst na 3D, Remesh oraz Reteksturowanie. Zadanie musi wykorzystywać Meshy 6 lub nowszy (w tym Meshy 7) i musi mieć status SUCCEEDED.

Name
model_url
Type
string
Wymagane
Description
URL modelu 3D do analizy. Wspierane formaty: .glb, .gltf, .obj, .fbx, .stl. Maksymalny rozmiar pliku: 100 MB. Musi wykorzystywać http, https lub URL typu data: (URL-e typu data omijają sprawdzanie rozszerzenia).

Zwracana wartość

Właściwość result w odpowiedzi zawiera id nowo utworzonego zadania analizy drukowalności.

Rodzaje błędów

Name
400 - Bad Request
Description
Żądanie było nieprawidłowe. Częste przyczyny:
- Brak parametru: nie podano ani input_task_id, ani model_url.
- Nieprawidłowy UUID: input_task_id nie jest prawidłowym UUID.
- Nieprawidłowy URL modelu: model_url jest niepoprawnie sformatowany, wykorzystuje niewspierany schemat lub ma niewspierane rozszerzenie pliku.
- Plik modelu za duży: treść model_url przekroczyła 100 MB.
- Zadanie nie zakończone sukcesem: przywołane zadanie jest wciąż oczekujące, w trakcie realizacji lub zakończyło się niepowodzeniem.
Name
401 - Unauthorized
Description
Uwierzytelnianie nie powiodło się. Sprawdź swój klucz API.
Name
403 - Forbidden
Description
Zadanie istnieje, ale jest własnością innego użytkownika.
Name
404 - Not Found
Description
Częste przyczyny:
- Zadanie nie istnieje lub zostało usunięte.
- Zadanie wykorzystuje model starszy niż Meshy 6, lub jego mode nie generuje elementu 3D.
- Bazowy plik modelu nie jest już dostępny w magazynie danych.
Name
429 - Too Many Requests
Description
Przekroczono limit oczekujących zadań lub limit szybkości.

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

Pobierz zadanie Analizuj drukowalność

Ten punkt końcowy pobiera zadanie analizy drukowalności na podstawie jego ID.

Parametry

Name
id
Type
path
Description
ID zadania analizy drukowalności do pobrania.

Zwraca

Obiekt zadania Analizuj drukowalność. Pole printability ma wartość null, dopóki zadanie nie osiągnie statusu SUCCEEDED.

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

Usuń zadanie Analizuj drukowalność

Ten punkt końcowy trwale usuwa zadanie analizy drukowalności oraz jego zapisany w pamięci podręcznej wynik. Ta operacja jest nieodwracalna.

Parametry ścieżki

Name
id
Type
path
Description
ID zadania analizy drukowalności do usunięcia.

Status zadania

Zadanie, które nadal ma status PENDING, zostaje usunięte, a kredyty zużyte w momencie jego utworzenia są zwracane.

Zadania, które jest już IN_PROGRESS, nie można usunąć: żądanie jest odrzucane z kodem 409 Conflict, a zadanie kontynuuje działanie. Kredyty za zadanie, które worker już rozpoczął przetwarzać, nie podlegają zwrotowi, więc usunięcie go w trakcie wykonywania kosztowałoby Cię zarówno kredyty, jak i wynik. Poczekaj, aż osiągnie ono status SUCCEEDED, FAILED lub CANCELED, a następnie je usuń.

Zadanie w stanie końcowym (SUCCEEDED, FAILED lub CANCELED) jest usuwane bez zwrotu kredytów.

Zwraca

Zwraca 200 OK w przypadku powodzenia lub 409 Conflict, gdy zadanie ma status IN_PROGRESS.

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

Lista zadań Analizuj drukowalność

Ten punkt końcowy umożliwia pobranie listy zadań analizy drukowalności.

Parametry

Opcjonalne atrybuty

Name
page_num
Type
integer
Description
Numer strony do stronicowania. Zaczyna się i domyślnie wynosi 1.
Name
page_size
Type
integer
Description
Limit rozmiaru strony. Domyślnie 10 elementów. Maksymalna dozwolona wartość to 100 elementów.
Name
sort_by
Type
string
Description
Pole, według którego ma nastąpić sortowanie. Dostępne wartości:
- +created_at: Sortuj według czasu utworzenia w porządku wzrastającym.
- -created_at: Sortuj według czasu utworzenia w porządku opadającym.

Zwracane wartości

Zwraca stronicowaną listę obiektów zadania Analizuj drukowalność.

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

Strumieniuj zadanie Analizuj drukowalność

Ten punkt końcowy strumieniuje aktualizacje w czasie rzeczywistym dla zadania analizy drukowalności przy użyciu Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zadania analizy drukowalności do strumieniowania.

Zwraca

Zwraca strumień obiektów zadania Analizuj drukowalność jako Server-Sent Events.

Każda ramka zawiera pełny obiekt zadania dla danego etapu — o takiej samej strukturze, jaką zwraca punkt końcowy Get — więc gdy zadanie ma status PENDING lub IN_PROGRESS, pola wyjściowe po prostu nie są jeszcze wypełnione (null, [] lub {}), a finished_at ma wartość null. Blok printability jest wysyłany tylko wtedy, gdy zadanie osiągnie status SUCCEEDED.

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
}

Obiekt zadania Analizuj drukowalność

Name
id
Type
string
Description
Unikalny identyfikator zadania. Chociaż jako szczegół implementacyjny używamy dla identyfikatorów zadań identyfikatora UUID z możliwością sortowania k-sortable, nie należy przyjmować żadnych założeń co do formatu id.
Name
type
Type
string
Description
Typ zadania analizy drukowalności. Wartość to print-analyze.
Name
status
Type
string
Description
Status zadania. Możliwe wartości to PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress zadania. Jeśli zadanie jeszcze się nie rozpoczęło, ta właściwość będzie miała wartość 0. Gdy zadanie zakończy się powodzeniem, przyjmie wartość 100.
Name
preceding_tasks
Type
integer
Description
Liczba poprzedzających zadań.
Wartość tego pola ma znaczenie tylko wtedy, gdy status zadania to PENDING.
Name
created_at
Type
timestamp
Description
Znacznik czasu utworzenia zadania, w milisekundach.
Name
started_at
Type
timestamp
Description
Znacznik czasu rozpoczęcia zadania, w milisekundach. Jeśli zadanie jeszcze się nie rozpoczęło, ta właściwość będzie miała wartość 0.
Name
finished_at
Type
timestamp
Description
Znacznik czasu zakończenia zadania, w milisekundach. Jeśli zadanie jeszcze się nie zakończyło, ta właściwość będzie miała wartość 0.
Name
expires_at
Type
timestamp
Description
Znacznik czasu wygaśnięcia wyniku zadania w systemie, w milisekundach. 0, jeśli zadanie jeszcze się nie zakończyło.
Name
task_error
Type
object
Description
Informacje o błędzie, jeśli zadanie zakończyło się niepowodzeniem. Ta właściwość ma wartość null, jeśli zadanie nie zakończyło się niepowodzeniem. Zobacz Błędy, aby uzyskać więcej informacji.
- Name
  message
  Type
  string
  Description
  Komunikat błędu opisujący, co poszło nie tak.
Name
printability
Type
object
Description
Wynik oceny drukowalności. null do momentu, gdy zadanie osiągnie status SUCCEEDED.
- Name
  _version
  Type
  string
  Description
  Wersja schematu wyniku drukowalności. Obecnie v1.
- Name
  status
  Type
  string
  Description
  Ogólny status. Jedna z wartości:
  
  healthy: brak błędów i ostrzeżeń.
  
  warning: co najmniej jedno ostrzeżenie, brak błędów.
  
  error: co najmniej jeden błąd.
  
  unknown: nie można było przeanalizować modelu.
- Name
  issue_count
  Type
  integer
  Description
  Łączna liczba problemów, równa error_count + warning_count.
- Name
  error_count
  Type
  integer
  Description
  Liczba problemów na poziomie błędu. Błędy są zgłaszane, gdy model nie jest szczelny (watertight), ma niedodatnią objętość lub zawiera krawędzie non-manifold.
- Name
  warning_count
  Type
  integer
  Description
  Liczba problemów na poziomie ostrzeżenia. Ostrzeżenia są zgłaszane, gdy model zawiera zdegenerowane ściany lub otwory.
- Name
  metrics
  Type
  object
  Description
  Surowe metryki geometrii zwrócone przez ewaluator.
  Name
  is_watertight
  Type
  boolean
  Description
  true, gdy siatka nie ma krawędzi brzegowych (tzn. jest zamknięta).
  Name
  volume
  Type
  number
  Description
  Objętość modelu w metrach sześciennych.
  Name
  non_manifold_edges
  Type
  integer
  Description
  Liczba krawędzi non-manifold.
  Name
  degenerate_faces
  Type
  integer
  Description
  Liczba zdegenerowanych ścian (ścian o zerowej powierzchni lub nieprawidłowych).
  Name
  holes
  Type
  integer
  Description
  Liczba otworów (pętli brzegowych) w siatce.
- Name
  evaluated_at
  Type
  timestamp
  Description
  Znacznik czasu obliczenia analizy, w milisekundach od epoki.
Name
consumed_credits
Type
integer
Description
Zawsze 0. Ten punkt końcowy jest bezpłatny.

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
}