API Аналізу придатності до друку

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

POST/openapi/v1/print/analyze

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

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

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

Параметри

Потрібен лише один із input_task_id або model_url. Якщо надано обидва, input_task_id має пріоритет.

Name
input_task_id
Type
string
Обов'язковий
Description
ID успішно виконаного завдання, яке належить вам. Підтримувані типи завдань: Зображення у 3D, Мульти-зображення у 3D, Текст у 3D, Ремеш і Ретекстурування. Завдання має використовувати Meshy 6 (або будь-яку модель Preview) і мати статус SUCCEEDED.

Name
model_url
Type
string
Обов'язковий
Description
URL 3D-моделі для аналізу. Підтримувані формати: .glb, .gltf, .obj, .fbx, .stl. Максимальний розмір файлу: 100 MB. Має використовувати URL http, https або data: (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 MB.
- Завдання не успішне: завдання, на яке є посилання, ще очікує, виконується або завершилося невдачею.
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
ID завдання аналізу придатності до друку, яке потрібно видалити.

Повернення

Повертає 200 OK у разі успіху.

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

// Returns 200 Ok on success.

GET/openapi/v1/print/analyze

Список завдань Аналіз придатності до друку

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

Параметри

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

Name
page_num
Type
integer
Description
Номер сторінки для пагінації. Починається з 1 і за замовчуванням дорівнює 1.
Name
page_size
Type
integer
Description
Обмеження розміру сторінки. За замовчуванням — 10 елементів. Максимально дозволено 50 елементів.
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

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

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

Параметри

Name
id
Type
path
Description
Унікальний ідентифікатор завдання аналізу придатності до друку для потокової передачі.

Повертає

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

Для завдань PENDING або IN_PROGRESS потік відповіді міститиме лише необхідні поля progress і status. Блок 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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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
progress завдання. Якщо завдання ще не розпочато, ця властивість буде 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
}