lowpoly буде вимкнено 30 жовт. 2026 р.. Перейдіть на іншу модель до цих дат, щоб уникнути помилок у запитах.

Analyze Printability API

Проаналізуйте 3D-модель на придатність до друку — водонепроникність, об'єм, отвори, немноговидні ребра та вироджені грані. За бажанням також можна перевірити товщину стінки за розміром, у якому ви плануєте друкувати.


POST/openapi/v1/print/analyze

Create an Analyze Printability Task

Ця кінцева точка створює нове завдання аналізу придатності до друку. Завдання оцінює 3D-модель та повідомляє показники придатності до друку.

Завдання виконується у фоновому режимі. Про типовий час виконання див. Час обробки.

Якщо вхідне завдання вже має кешовану придатність до друку, повернуте завдання одразу готове, і перший GET-запит до нього поверне результат аналізу без проходження через воркер.

Щоб також перевірити товщину стінки для розміру, у якому ви плануєте друкувати, надішліть printer_type, розмір друку або обидва параметри. Результат повертається у printability.thin_walls. Перевірка товщини стінки займає більше часу, тому завдання зазвичай не готове одразу, навіть якщо модель вже була проаналізована раніше.

Параметри

  • Name
    model_url
    Type
    string
    Обов'язковий
    Description

    URL 3D-моделі для аналізу. Підтримувані формати: .glb, .gltf, .obj, .fbx, .stl. Використовуйте URL за протоколом http або https, або base64 data: URL для GLB (data:model/gltf-binary;base64,...) чи glTF (data:model/gltf+json;base64,...). Файли .obj, .fbx та .stl мають надсилатися як URL за протоколом http або https.

    Максимальний розмір файлу: 400 МБ для URL за протоколом http або https, 100 МБ для data: URI.

    Файл GLB, glTF, FBX або OBJ розміром понад 100 МБ може мати не більше 10 000 000 граней. Грані рахуються як трикутники: чотирикутник рахується як 2, а сітка, намальована кілька разів, рахується один раз за кожну копію. Понад 100 МБ, файл FBX повинен бути бінарним FBX 7.1 або новішим, а файл GLB або glTF не повинен використовувати стиснення Draco.

    URL завантаження Meshy (assets.meshy.ai/…?Expires=…&Signature=…) підписані й перестають працювати після expires_at завдання; повторне отримання завдання не оновлює їх. Для моделі, згенерованої за допомогою Meshy, натомість передавайте input_task_id. Він працює, поки вихідне завдання зберігається (див. Зберігання ресурсів). Щоб повторно використати модель після цього, завантажте її до настання expires_at і надішліть власну копію.

  • Name
    printer_type
    Type
    string
    Description

    Принтер, який ви плануєте використовувати. Він встановлює мінімальну товщину стінки для перевірки товщини стінки. За замовчуванням встановлюється fdm, якщо ви надсилаєте розмір друку без цього параметра.

    Доступні значення:

    • fdm: філамент, мінімальна товщина стінки 1,0 мм.
    • sla: смола, мінімальна товщина стінки 0,8 мм.
    • full_color: повнокольоровий друк, мінімальна товщина стінки 2,0 мм.
  • Name
    intended_print_height_mm
    Type
    number
    Description

    Висота друку в міліметрах. Діапазон: [1, 1000]. Округлюється до найближчого міліметра. Лише для вхідних даних GLB.

  • Name
    intended_print_longest_side_mm
    Type
    number
    Description

    Довжина найдовшої сторони друку, в міліметрах. Діапазон: [1, 1000]. Округлюється до найближчого міліметра. Працює з будь-яким форматом вхідних даних.

Повертає

Властивість result відповіді містить id щойно створеного завдання аналізу придатності до друку.

Режими збою

  • Name
    400 - Bad Request
    Description

    Запит неприйнятний. Поширені причини:

    • Відсутній параметр: не надано ні input_task_id, ні model_url.
    • Недійсний UUID: input_task_id не є дійсним UUID.
    • Недійсний URL моделі: model_url має неправильний формат, використовує непідтримувану схему або має непідтримуване розширення файлу.
    • Файл моделі завеликий: тіло model_url перевищило 400 МБ (URL за протоколом http або https) чи 100 МБ (data: URI).
    • Забагато граней: model_url — це файл GLB, glTF, FBX або OBJ розміром понад 100 МБ з більш ніж 10 000 000 граней. Зменшіть кількість граней, а потім надішліть файл знову.
    • ASCII FBX понад 100 МБ: model_url — це ASCII FBX понад 100 МБ. Надішліть його як бінарний FBX або GLB.
    • Нечитабельний файл моделі: model_url має розмір понад 100 МБ, і його заголовок неможливо прочитати, наприклад стиснутий Draco GLB чи glTF, або бінарний FBX старіший за 7.1.
    • Заголовок моделі занадто складний: model_url має розмір понад 100 МБ, і його заголовок містить забагато сіток, вузлів або записів для перевірки. Зменшіть кількість об'єктів у файлі, а потім надішліть його знову.
    • Не вдалося завантажити файл моделі: model_url повернув помилку, найчастіше через те, що термін дії підписаного URL завантаження Meshy минув. Повторне отримання завдання повертає той самий URL з тим самим терміном дії, тому надішліть власну копію файлу або використовуйте input_task_id, поки вихідне завдання ще зберігається.
    • Завдання не завершилося успішно: зазначене завдання все ще очікує, виконується або завершилося помилкою.
    • Недійсний розмір друку: intended_print_height_mm або intended_print_longest_side_mm виходить за межі [1, 1000], або були надіслані обидва параметри.
    • Невідомий тип принтера: printer_type не є fdm, sla або full_color.
    • Висота для не-GLB моделі: intended_print_height_mm надіслано з model_url, яке не є .glb. Натомість використовуйте intended_print_longest_side_mm.
    • Неможливо встановити розмір моделі за висотою: за запитаної висоти (або типової 150 мм) найдовша сторона моделі виходила б за межі [1, 1000] мм, модель є плоскою, або її розмір неможливо визначити. Натомість використовуйте intended_print_longest_side_mm. Для model_url у форматі .glb і деяких завдань input_task_id це виявляється лише після запуску завдання, і завдання завершується зі статусом FAILED замість цього.
    • Розмір STL непридатний для використання: printer_type надіслано без розміру, а власна найдовша сторона .stl не може бути прочитана або виходить за межі [1, 1000] мм. Надішліть intended_print_longest_side_mm.
  • Name
    401 - Unauthorized
    Description

    Помилка автентифікації. Будь ласка, перевірте свій API-ключ.

  • Name
    404 - Not Found
    Description

    Поширені причини:

    • Завдання не існує, було видалене або належить іншому користувачу.
    • Завдання використовує модель старішу за Meshy 6, або його mode не створює 3D-ресурс.
    • Базовий файл моделі більше недоступний у сховищі.
  • Name
    429 - Too Many Requests
    Description

    Ви перевищили квоту очікуваних завдань або обмеження частоти.

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

Отримати завдання аналізу придатності до друку

Ця кінцева точка отримує завдання аналізу придатності до друку за його ID.

Параметри

  • Name
    id
    Type
    path
    Description

    ID завдання аналізу придатності до друку, яке потрібно отримати.

Повертає

Об'єкт завдання аналізу придатності до друку. Поле printability має значення null, доки завдання не досягне статусу SUCCEEDED. Якщо перевірялася товщина стінки, printability також включає intended_print та 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

Видалити завдання аналізу придатності до друку

Ця кінцева точка остаточно видаляє завдання аналізу придатності до друку та його кешований результат. Ця дія незворотна.

Параметри шляху

  • Name
    id
    Type
    path
    Description

    ID завдання аналізу придатності до друку, яке потрібно видалити.

Статус завдання

Завдання, яке все ще має статус PENDING, видаляється, а кредити, витрачені під час створення, повертаються.

Завдання, яке вже має статус IN_PROGRESS, не можна видалити: запит відхиляється з помилкою 409 Conflict, а завдання продовжує виконуватися. Кредити за завдання, яке воркер уже почав виконувати, не підлягають поверненню, тому видалення його під час виконання призведе до втрати і кредитів, і результату. Дочекайтеся, поки воно досягне статусу SUCCEEDED, FAILED або CANCELED, а потім видаліть його.

Завдання у кінцевому стані (SUCCEEDED, FAILED або CANCELED) видаляється без повернення кредитів.

Повертає

Повертає 200 OK у разі успіху або 409 Conflict, коли завдання має статус 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

List Analyze Printability Tasks

Ця кінцева точка дозволяє отримати список завдань Аналіз придатності до друку.

Параметри

Необов'язкові атрибути

  • Name
    page_num
    Type
    integer
    Description

    Номер сторінки для пагінації. Починається з 1 і за замовчуванням дорівнює 1.

  • Name
    page_size
    Type
    integer
    Description

    Обмеження розміру сторінки. За замовчуванням 10 елементів. Максимально допустимо 100 елементів.

  • Name
    sort_by
    Type
    string
    Description

    Поле для сортування. Доступні значення:

    • +created_at: Сортування за часом створення у зростаючому порядку.
    • -created_at: Сортування за часом створення у спадному порядку.

Повертає

Повертає пагінований список об'єктів завдання Аналіз придатності до друку.

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 an Analyze Printability Task

Ця кінцева точка транслює оновлення в реальному часі для завдання аналізу придатності до друку за допомогою Server-Sent Events (SSE).

Параметри

  • Name
    id
    Type
    path
    Description

    Унікальний ідентифікатор завдання аналізу придатності до друку для трансляції.

Повертає

Повертає потік об'єктів завдання аналізу придатності до друку у вигляді Server-Sent Events.

Кожен кадр містить повний об'єкт завдання для відповідного етапу — таку ж структуру, яку повертає кінцева точка Get — тому поки завдання має статус PENDING або IN_PROGRESS, вихідні поля просто ще не заповнені (null, [] або {}), а finished_at дорівнює null. Блок printability надсилається лише після того, як завдання досягає статусу 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
}

The Analyze Printability Task Object

  • Name
    id
    Type
    string
    Description

    Унікальний ідентифікатор завдання. Хоча ми використовуємо k-сортований UUID для ідентифікаторів завдань як деталь реалізації, вам не слід робити жодних припущень щодо формату id.

  • Name
    type
    Type
    string
    Description

    Тип завдання аналізу придатності до друку. Значення — print-analyze.

  • Name
    status
    Type
    string
    Description

    Статус завдання. Можливі значення: одне з PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Прогрес завдання. Якщо завдання ще не розпочато, це значення буде 0. Після успішного завершення завдання воно стане 100.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Кількість завдань, що передують цьому.

  • Name
    created_at
    Type
    timestamp
    Description

    Мітка часу створення завдання, у мілісекундах.

  • Name
    started_at
    Type
    timestamp
    Description

    Мітка часу початку виконання завдання, у мілісекундах. Якщо завдання ще не розпочато, це значення буде 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Мітка часу завершення завдання, у мілісекундах. Якщо завдання ще не завершено, це значення буде 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Мітка часу, коли результат завдання закінчить термін дії в системі, у мілісекундах. 0, якщо завдання ще не завершено.

  • Name
    task_error
    Type
    object
    Description

    Інформація про помилку, якщо завдання завершилось невдало. Це поле є null, якщо завдання не завершилось невдало. Детальніше див. Помилки.

    • Name
      message
      Type
      string
      Description

      Повідомлення про помилку, що описує, що пішло не так.

  • Name
    printability
    Type
    object
    Description

    Результат оцінки придатності до друку. null, доки завдання не досягне статусу SUCCEEDED.

    • Name
      _version
      Type
      string
      Description

      Версія схеми результату придатності до друку. Наразі v1.

    • Name
      status
      Type
      string
      Description

      Загальний статус. Одне з:

      • healthy: немає ні помилок, ні попереджень.
      • warning: є принаймні одне попередження, помилок немає.
      • error: є принаймні одна помилка.
      • unknown: модель не вдалося проаналізувати.

      Якщо товщина стінки перевірялась, це найгірше значення з перевірок вище та thin_walls.status. Від найгіршого до найкращого: error, warning, unknown, healthy.

    • Name
      issue_count
      Type
      integer
      Description

      Загальна кількість проблем, що дорівнює error_count + warning_count.

    • Name
      error_count
      Type
      integer
      Description

      Кількість проблем рівня помилки. Помилки виникають, коли модель не є водонепроникною, має невалідний (неположитний) об'єм, або має немноговидні ребра. Якщо товщина стінки перевірялась, занадто тонкі стінки (thin_walls.status має значення error) враховуються як ще одна помилка.

    • Name
      warning_count
      Type
      integer
      Description

      Кількість проблем рівня попередження. Попередження виникають, коли модель містить вироджені грані або отвори.

    • Name
      metrics
      Type
      object
      Description

      Необроблені метрики геометрії, повернуті механізмом оцінки.

      • Name
        is_watertight
        Type
        boolean
        Description

        true, коли сітка не має граничних ребер (тобто є замкнутою).

      • Name
        volume
        Type
        number
        Description

        Об'єм моделі в кубічних метрах.

      • Name
        non_manifold_edges
        Type
        integer
        Description

        Кількість немноговидних ребер.

      • Name
        degenerate_faces
        Type
        integer
        Description

        Кількість вироджених граней (граней з нульовою площею або недійсних граней).

      • Name
        holes
        Type
        integer
        Description

        Кількість отворів (граничних циклів) у сітці.

    • Name
      intended_print
      Type
      object
      Description

      Принтер і розмір, які використовувались для перевірки товщини стінки. Присутнє лише якщо товщина стінки перевірялась.

      • Name
        printer_type
        Type
        string
        Description

        fdm, sla або full_color.

      • Name
        height_mm
        Type
        number
        Description

        Висота друку в міліметрах, якщо розмір друку визначався за висотою. Інакше null.

      • Name
        longest_side_mm
        Type
        number
        Description

        Найдовша сторона друку в міліметрах. Якщо розмір визначався за висотою, обчислюється з пропорцій моделі.

      • Name
        wall_thickness_mm
        Type
        number
        Description

        Мінімальна товщина стінки для printer_type, у міліметрах. Стінки тонші за це значення повідомляються як занадто тонкі.

      • Name
        dimensions_mm
        Type
        array
        Description

        Розміри друку [ширина, глибина, висота] у міліметрах. Висота може відрізнятися від height_mm на частку міліметра. null для вхідних даних не у форматі GLB, або якщо розмір моделі не вдається визначити.

    • Name
      thin_walls
      Type
      object
      Description

      Результат перевірки товщини стінки. Присутнє лише якщо товщина стінки перевірялась.

      • Name
        thin_area_ratio
        Type
        number
        Description

        Частка поверхні, від 0 до 1, яка тонша за intended_print.wall_thickness_mm. null, якщо модель не вдалося виміряти.

      • Name
        has_thin_walls
        Type
        boolean
        Description

        true, якщо будь-яка частина поверхні занадто тонка. Самі лише гострі кути можуть встановити це значення, тому для вирішення, чи потрібно потовщувати стінки, використовуйте status. null, якщо модель не вдалося виміряти.

      • Name
        status
        Type
        string
        Description

        Висновок щодо товщини стінки. Одне з:

        • healthy: 5% або менше поверхні занадто тонкі.
        • error: більше 5% поверхні занадто тонкі. Щоб потовщити стінки, передайте id цього завдання до Відновлення придатності до друку як input_task_id (для model_url у форматі .stl, .fbx або .gltf натомість надішліть файл як model_url).
        • unknown: модель не вдалося виміряти. Якщо сама перевірка товщини стінки зазнає невдачі, завдання завершується зі статусом FAILED.
    • Name
      evaluated_at
      Type
      timestamp
      Description

      Мітка часу обчислення аналізу, у мілісекундах з початку епохи.

  • Name
    consumed_credits
    Type
    integer
    Description

    Завжди 0. Ця кінцева точка безкоштовна.

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
}