Analyze Printability API
Проаналізуйте 3D-модель на придатність до друку — водонепроникність, об'єм, отвори, немноговидні ребра та вироджені грані. За бажанням також можна перевірити товщину стінки за розміром, у якому ви плануєте друкувати.
Create an Analyze Printability Task
Ця кінцева точка створює нове завдання аналізу придатності до друку. Завдання оцінює 3D-модель та повідомляє показники придатності до друку.
Завдання виконується у фоновому режимі. Про типовий час виконання див. Час обробки.
Якщо вхідне завдання вже має кешовану придатність до друку, повернуте завдання одразу готове, і перший GET-запит до нього поверне результат аналізу без проходження через воркер.
Щоб також перевірити товщину стінки для розміру, у якому ви плануєте друкувати, надішліть printer_type, розмір друку або обидва параметри. Результат повертається у printability.thin_walls. Перевірка товщини стінки займає більше часу, тому завдання зазвичай не готове одразу, навіть якщо модель вже була проаналізована раніше.
Параметри
Потрібен лише один з параметрів input_task_id або model_url. Якщо надано обидва, пріоритет має input_task_id.
- Name
- input_task_id
- Type
- string
- Обов'язковий
- Description
ID успішного завдання, яким ви володієте. Підтримувані типи завдань: Зображення у 3D, Мульти-зображення у 3D, Текст у 3D, Ремеш та Ретекстурування. Завдання повинне використовувати Meshy 6 або новішу версію (включно з Meshy 7) і мати статус
SUCCEEDED. Завдання Відновлення придатності до друку також приймаються.
- Name
- model_url
- Type
- string
- Обов'язковий
- Description
URL 3D-моделі для аналізу. Підтримувані формати:
.glb,.gltf,.obj,.fbx,.stl. Використовуйте URL за протоколомhttpабоhttps, або base64data: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і надішліть власну копію.
Надсилайте не більше одного з двох полів розміру друку. Якщо ви надсилаєте printer_type без розміру, використовується типовий розмір:
.glbта будь-якийinput_task_id: 150 мм висотою..stl: власна найдовша сторона файлу, зчитана в міліметрах. Для STL в інших одиницях вимірювання надсилайтеintended_print_longest_side_mm..obj,.fbx,.gltf: 150 мм по найдовшій стороні.
- 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
# 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"
}
Отримати завдання аналізу придатності до друку
Ця кінцева точка отримує завдання аналізу придатності до друку за його ID.
Параметри
- Name
- id
- Type
- path
- Description
ID завдання аналізу придатності до друку, яке потрібно отримати.
Повертає
Об'єкт завдання аналізу придатності до друку. Поле printability має значення null, доки завдання не досягне статусу SUCCEEDED. Якщо перевірялася товщина стінки, printability також включає intended_print та 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
}
Видалити завдання аналізу придатності до друку
Ця кінцева точка остаточно видаляє завдання аналізу придатності до друку та його кешований результат. Ця дія незворотна.
Параметри шляху
- Name
- id
- Type
- path
- Description
ID завдання аналізу придатності до друку, яке потрібно видалити.
Статус завдання
Завдання, яке все ще має статус PENDING, видаляється, а кредити, витрачені
під час створення, повертаються.
Завдання, яке вже має статус IN_PROGRESS, не можна видалити: запит
відхиляється з помилкою 409 Conflict, а завдання продовжує виконуватися. Кредити за завдання,
яке воркер уже почав виконувати, не підлягають поверненню, тому видалення його під час виконання
призведе до втрати і кредитів, і результату. Дочекайтеся, поки воно досягне статусу
SUCCEEDED, FAILED або CANCELED, а потім видаліть його.
Завдання у кінцевому стані (SUCCEEDED, FAILED або CANCELED) видаляється
без повернення кредитів.
Повертає
Повертає 200 OK у разі успіху або 409 Conflict, коли завдання має статус
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."
}
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
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
}
]
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
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
Кількість завдань, що передують цьому.
Значення цього поля має сенс лише якщо статус завдання —
PENDING.
- 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
}