Analyze Printability API

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

POST/openapi/v1/print/analyze

Create an Analyze Printability Task

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

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

Параметри

Потрібен лише один з параметрів 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. Максимальний розмір файлу: 100 МБ. Має використовувати http, https або data: URL (data URL обходять перевірки розширення).

Результат

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

Режими збою

Name
400 - Bad Request
Description
Запит неприйнятний. Поширені причини:
- Відсутній параметр: не надано ані input_task_id, ані model_url.
- Недійсний UUID: input_task_id не є дійсним UUID.
- Недійсний URL моделі: model_url некоректно сформований, використовує непідтримувану схему або має непідтримуване розширення файлу.
- Файл моделі завеликий: тіло model_url перевищило 100 МБ.
- Завдання не завершено успішно: зазначене завдання все ще очікує, виконується або завершилося невдачею.
Name
401 - Unauthorized
Description
Помилка автентифікації. Будь ласка, перевірте свій API-ключ.
Name
403 - Forbidden
Description
Завдання існує, але належить іншому користувачу.
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"
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/print/analyze/:id

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

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

Параметри

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

Повертає

Об'єкт завдання аналізу придатності до друку. Поле printability дорівнює null, доки завдання не досягне статусу SUCCEEDED.

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
}

DELETE/openapi/v1/print/analyze/:id

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

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

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

Name
id
Type
path
Description
Ідентифікатор завдання аналізу придатності до друку, яке потрібно видалити.

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

Завдання, яке ще перебуває у стані 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.
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
}

Об'єкт задачі Аналіз придатності до друку

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: модель не вдалося проаналізувати.
- Name
  issue_count
  Type
  integer
  Description
  Загальна кількість проблем, що дорівнює error_count + warning_count.
- Name
  error_count
  Type
  integer
  Description
  Кількість проблем рівня помилки. Помилки виникають, коли модель не є водонепроникною, має невід'ємний обсяг (некоректний об'єм), або має немноговидні ребра.
- 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
  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
}