Analizuj drukowalność API
Analizuj model 3D pod kątem drukowalności — szczelności, objętości, otworów, krawędzi non-manifold i zdegenerowanych ścian. Opcjonalnie możesz również sprawdzić grubość ścianki przy rozmiarze, w jakim planujesz drukować.
Create an Analyze Printability Task
Ten punkt końcowy tworzy nowe zadanie analizy drukowalności. Zadanie ocenia model 3D i raportuje jego wskaźniki drukowalności.
Jeśli zadanie wejściowe ma już zapisaną w pamięci podręcznej drukowalność, zwrócone zadanie jest natychmiast gotowe, a pierwsze żądanie GET na nim zwróci wynik analizy bez przechodzenia przez worker.
Aby dodatkowo sprawdzić grubość ścianki dla rozmiaru, w jakim planujesz drukować, wyślij printer_type, rozmiar wydruku lub oba te parametry. Wynik jest zwracany w polu printability.thin_walls. Sprawdzanie grubości ścianki trwa dłużej, więc zadanie zwykle nie jest gotowe od razu, nawet jeśli model był wcześniej analizowany.
Parametry
Wymagany jest tylko jeden z parametrów input_task_id lub model_url. Jeśli podano oba, pierwszeństwo ma input_task_id.
- Name
- input_task_id
- Type
- string
- Wymagane
- Description
ID zakończonego powodzeniem zadania, którego jesteś właścicielem. Obsługiwane typy zadań: Obraz na 3D, Wiele obrazów na 3D, Tekst na 3D, Remesh oraz Reteksturowanie. Zadanie musi korzystać z Meshy 6 lub nowszego (w tym Meshy 7) i musi mieć status
SUCCEEDED. Akceptowane są również zadania Napraw drukowalność.
- Name
- model_url
- Type
- string
- Wymagane
- Description
Adres URL modelu 3D do analizy. Obsługiwane formaty:
.glb,.gltf,.obj,.fbx,.stl. Maksymalny rozmiar pliku: 100 MB. Musi używać protokołuhttp,httpslub adresu URLdata:(adresy URL typu data pomijają sprawdzanie rozszerzenia).
Wyślij co najwyżej jedno z dwóch pól rozmiaru wydruku. Jeśli wyślesz printer_type bez podania rozmiaru, domyślny rozmiar wynosi:
.glbi dowolneinput_task_id: wysokość 150 mm..stl: najdłuższy bok pliku, odczytany jako milimetry. Dla pliku STL w innych jednostkach wyślijintended_print_longest_side_mm..obj,.fbx,.gltf: 150 mm na najdłuższym boku.
- Name
- printer_type
- Type
- string
- Description
Drukarka, której planujesz użyć. Określa minimalną grubość ścianki dla sprawdzania grubości ścianki. Domyślnie
fdm, gdy wyślesz rozmiar wydruku bez podania tego parametru.Dostępne wartości:
fdm: filament, minimalna grubość ścianki 1,0 mm.sla: żywica, minimalna grubość ścianki 0,8 mm.full_color: pełny kolor, minimalna grubość ścianki 2,0 mm.
- Name
- intended_print_height_mm
- Type
- number
- Description
Wysokość wydruku w milimetrach. Zakres:
[1, 1000]. Zaokrąglane do najbliższego milimetra. Tylko dla wejścia GLB.
- Name
- intended_print_longest_side_mm
- Type
- number
- Description
Długość najdłuższego boku wydruku w milimetrach. Zakres:
[1, 1000]. Zaokrąglane do najbliższego milimetra. Działa z każdym formatem wejściowym.
Zwracane wartości
Właściwość result odpowiedzi zawiera id nowo utworzonego zadania analizy drukowalności.
Tryby niepowodzenia
- Name
400 - Bad Request- Description
Żądanie było niedopuszczalne. Typowe przyczyny:
- Brakujący parametr: nie podano ani
input_task_id, animodel_url. - Nieprawidłowy UUID:
input_task_idnie jest prawidłowym UUID. - Nieprawidłowy adres URL modelu:
model_urljest nieprawidłowo sformatowany, używa nieobsługiwanego schematu lub ma nieobsługiwane rozszerzenie pliku. - Plik modelu zbyt duży: treść
model_urlprzekroczyła 100 MB. - Zadanie nie zakończone powodzeniem: wskazane zadanie jest wciąż oczekujące, w trakcie realizacji lub zakończyło się niepowodzeniem.
- Nieprawidłowy rozmiar wydruku:
intended_print_height_mmlubintended_print_longest_side_mmwykracza poza zakres[1, 1000]lub wysłano oba parametry. - Nieznany typ drukarki:
printer_typenie jest ustawione nafdm,slaanifull_color. - Wysokość dla modelu innego niż GLB:
intended_print_height_mmwysłano zmodel_url, który nie jest.glb. Zamiast tego użyjintended_print_longest_side_mm. - Nie można określić rozmiaru tego modelu na podstawie wysokości: przy żądanej wysokości (lub domyślnych 150 mm) najdłuższy bok modelu wykraczałby poza zakres
[1, 1000]mm, model jest płaski lub jego rozmiaru nie można określić. Zamiast tego użyjintended_print_longest_side_mm. W przypadkumodel_urltypu.glboraz niektórych zadańinput_task_idjest to wykrywane dopiero po rozpoczęciu zadania, a zadanie kończy się wtedy statusemFAILED. - Rozmiar STL nieprzydatny: wysłano
printer_typebez podania rozmiaru, a najdłuższy bok pliku.stlnie może zostać odczytany lub wykracza poza zakres[1, 1000]mm. Wyślijintended_print_longest_side_mm.
- Brakujący parametr: nie podano ani
- Name
401 - Unauthorized- Description
Uwierzytelnianie nie powiodło się. Sprawdź swój klucz API.
- Name
403 - Forbidden- Description
Zadanie istnieje, ale należy do innego użytkownika.
- Name
404 - Not Found- Description
Typowe przyczyny:
- Zadanie nie istnieje lub zostało usunięte.
- Zadanie korzysta z modelu starszego niż Meshy 6 lub jego mode nie generuje zasobu 3D.
- Bazowy plik modelu nie jest już dostępny w pamięci masowej.
- Name
429 - Too Many Requests- Description
Przekroczono limit oczekujących zadań lub limit szybkości.
Request
# 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"
}'
# Also check wall thickness for a 100 mm tall SLA print
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",
"printer_type": "sla",
"intended_print_height_mm": 100
}'
Response
{
"result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
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. Gdy sprawdzana była grubość ścianki, printability zawiera również intended_print oraz thin_walls.
Request
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
}
Response (wall thickness checked)
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-analyze",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000012000,
"expires_at": 1715725412000,
"task_error": null,
"printability": {
"_version": "v1",
"status": "error",
"issue_count": 2,
"error_count": 1,
"warning_count": 1,
"metrics": {
"is_watertight": true,
"volume": 1.316167354292668,
"non_manifold_edges": 0,
"degenerate_faces": 43242,
"holes": 0
},
"intended_print": {
"printer_type": "sla",
"height_mm": 100,
"longest_side_mm": 118,
"wall_thickness_mm": 0.8,
"dimensions_mm": [118, 72.41, 99.87]
},
"thin_walls": {
"thin_area_ratio": 0.083,
"has_thin_walls": true,
"status": "error"
},
"evaluated_at": 1700000012000
},
"consumed_credits": 0
}
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
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."
}
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
10elementów. Maksymalna dozwolona wartość to100elementó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
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
}
]
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
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. Choć jako szczegół implementacyjny używamy identyfikatora UUID z sortowaniem typu k dla identyfikatorów zadań, nie należy przyjmować żadnych założeń co do formatu tego 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 jedna z:
PENDING,IN_PROGRESS,SUCCEEDED,FAILED,CANCELED.
- Name
- progress
- Type
- integer
- Description
Postęp zadania. Jeśli zadanie jeszcze się nie rozpoczęło, ta właściwość będzie wynosić
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 wynosić
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 wynosić
0.
- Name
- expires_at
- Type
- timestamp
- Description
Znacznik czasu, kiedy wynik zadania wygaśnie 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. Więcej informacji znajdziesz w sekcji Błędy.- 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, dopóki zadanie nie osiągnie statusuSUCCEEDED.- Name
_version- Type
- string
- Description
Wersja schematu wyniku drukowalności. Obecnie
v1.
- Name
status- Type
- string
- Description
Ogólny status. Jeden z:
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: modelu nie udało się przeanalizować.
Gdy sprawdzana była grubość ścianki, jest to gorsza z wartości powyższych sprawdzeń oraz
thin_walls.status. Od najgorszej do najlepszej:error,warning,unknown,healthy.
- 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 nie-dodatnią objętość lub posiada krawędzie non-manifold. Gdy sprawdzana była grubość ścianki, ścianki zbyt cienkie (
thin_walls.statusma wartośćerror) liczą się jako dodatkowy błąd.
- 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 mechanizm oceny.
- Name
is_watertight- Type
- boolean
- Description
true, gdy siatka nie ma krawędzi brzegowych (tj. 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
intended_print- Type
- object
- Description
Drukarka i rozmiar użyte w sprawdzeniu grubości ścianki. Obecne tylko wtedy, gdy grubość ścianki była sprawdzana.
- Name
printer_type- Type
- string
- Description
fdm,slalubfull_color.
- Name
height_mm- Type
- number
- Description
Wysokość wydruku w milimetrach, jeśli rozmiar wydruku został ustalony na podstawie wysokości. W przeciwnym razie
null.
- Name
longest_side_mm- Type
- number
- Description
Najdłuższy bok wydruku w milimetrach. Gdy rozmiar ustalany jest na podstawie wysokości, wartość ta jest obliczana na podstawie proporcji modelu.
- Name
wall_thickness_mm- Type
- number
- Description
Minimalna grubość ścianki dla
printer_type, w milimetrach. Ścianki cieńsze niż ta wartość są zgłaszane jako zbyt cienkie.
- Name
dimensions_mm- Type
- array
- Description
Wymiary wydruku
[szerokość, głębokość, wysokość]w milimetrach. Wysokość może różnić się odheight_mmo ułamek milimetra.nulldla danych wejściowych innych niż GLB lub jeśli nie można ustalić rozmiaru modelu.
- Name
thin_walls- Type
- object
- Description
Wynik sprawdzenia grubości ścianki. Obecny tylko wtedy, gdy grubość ścianki była sprawdzana.
- Name
thin_area_ratio- Type
- number
- Description
Udział powierzchni, od
0do1, która jest cieńsza niżintended_print.wall_thickness_mm.null, jeśli modelu nie udało się zmierzyć.
- Name
has_thin_walls- Type
- boolean
- Description
true, jeśli jakakolwiek część powierzchni jest zbyt cienka. Samo ostre naroże może ustawić tę wartość, dlatego aby zdecydować, czy ścianki wymagają pogrubienia, należy kierować się polemstatus.null, jeśli modelu nie udało się zmierzyć.
- Name
status- Type
- string
- Description
Werdykt dotyczący grubości ścianki. Jeden z:
healthy: 5% lub mniej powierzchni jest zbyt cienkie.error: więcej niż 5% powierzchni jest zbyt cienkie. Aby pogrubić ścianki, przekażidtego zadania do Napraw drukowalność jakoinput_task_id(w przypadkumodel_urlw formacie.stl,.fbxlub.gltfzamiast tego wyślij plik jakomodel_url).unknown: modelu nie udało się zmierzyć. Jeśli samo sprawdzenie grubości ścianki się nie powiedzie, zadanie kończy się statusemFAILED.
- 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
}
The Analyze Printability Task Object (wall thickness checked)
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "print-analyze",
"status": "SUCCEEDED",
"progress": 100,
"preceding_tasks": 0,
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000012000,
"expires_at": 1715725412000,
"task_error": null,
"printability": {
"_version": "v1",
"status": "error",
"issue_count": 2,
"error_count": 1,
"warning_count": 1,
"metrics": {
"is_watertight": true,
"volume": 1.316167354292668,
"non_manifold_edges": 0,
"degenerate_faces": 43242,
"holes": 0
},
"intended_print": {
"printer_type": "sla",
"height_mm": 100,
"longest_side_mm": 118,
"wall_thickness_mm": 0.8,
"dimensions_mm": [118, 72.41, 99.87]
},
"thin_walls": {
"thin_area_ratio": 0.083,
"has_thin_walls": true,
"status": "error"
},
"evaluated_at": 1700000012000
},
"consumed_credits": 0
}