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. Используйтеhttp- илиhttps-URL, либо base64data:-URL для GLB (data:model/gltf-binary;base64,...) или glTF (data:model/gltf+json;base64,...). Файлы.obj,.fbxи.stlдолжны передаваться в видеhttp- илиhttps-URL.Максимальный размер файла: 400 МБ для
http- илиhttps-URL, 100 МБ дляdata:-URI.Файл GLB, glTF, FBX или OBJ размером более 100 МБ может содержать не более 10 000 000 граней. Грани считаются как треугольники: четырёхугольник считается за 2, а сетка, нарисованная более одного раза, считается по разу за каждую копию. При размере более 100 МБ файл FBX должен быть бинарным FBX версии 7.1 или новее, а файл GLB или glTF не должен использовать сжатие Draco.
Ссылки для скачивания 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 МБ (http- илиhttps-URL) или 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вернул ошибку, чаще всего из-за истёкшего срока действия подписанной ссылки для скачивания 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.
- 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-sortable 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
Количество проблем уровня ошибки. Ошибки возникают, если модель не является водонепроницаемой (watertight), имеет неположительный объём, либо содержит немногообразные рёбра. Если проверялась толщина стенки, стенки, которые слишком тонкие (
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
}