meshy-5 zostanie wycofany 10 paź 2026. lowpoly zostanie wycofany 30 paź 2026. Zmień model przed tymi datami, aby uniknąć błędów żądań.

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ć.


POST/openapi/v1/print/analyze

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

  • 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łu http, https lub adresu URL data: (adresy URL typu data pomijają sprawdzanie rozszerzenia).

  • 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, ani model_url.
    • Nieprawidłowy UUID: input_task_id nie jest prawidłowym UUID.
    • Nieprawidłowy adres URL modelu: model_url jest nieprawidłowo sformatowany, używa nieobsługiwanego schematu lub ma nieobsługiwane rozszerzenie pliku.
    • Plik modelu zbyt duży: treść model_url przekroczył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_mm lub intended_print_longest_side_mm wykracza poza zakres [1, 1000] lub wysłano oba parametry.
    • Nieznany typ drukarki: printer_type nie jest ustawione na fdm, sla ani full_color.
    • Wysokość dla modelu innego niż GLB: intended_print_height_mm wysłano z model_url, który nie jest .glb. Zamiast tego użyj intended_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żyj intended_print_longest_side_mm. W przypadku model_url typu .glb oraz niektórych zadań input_task_id jest to wykrywane dopiero po rozpoczęciu zadania, a zadanie kończy się wtedy statusem FAILED.
    • Rozmiar STL nieprzydatny: wysłano printer_type bez podania rozmiaru, a najdłuższy bok pliku .stl nie może zostać odczytany lub wykracza poza zakres [1, 1000] mm. Wyślij intended_print_longest_side_mm.
  • 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

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"
  }'

# 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"
}

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. Gdy sprawdzana była grubość ścianki, printability zawiera również intended_print oraz thin_walls.

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
}

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
}

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. 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ń.

  • 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 statusu SUCCEEDED.

    • 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.status ma 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, sla lub full_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ę od height_mm o ułamek milimetra. null dla 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 0 do 1, 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ę polem status. 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ż id tego zadania do Napraw drukowalność jako input_task_id (w przypadku model_url w formacie .stl, .fbx lub .gltf zamiast tego wyślij plik jako model_url).
        • unknown: modelu nie udało się zmierzyć. Jeśli samo sprawdzenie grubości ścianki się nie powiedzie, zadanie kończy się statusem FAILED.
    • 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
}