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

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

POST/openapi/v1/print/analyze

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

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

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

Параметри

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

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

    URL 3D моделі для аналізу. Підтримувані формати: .glb, .gltf, .obj, .fbx, .stl. Максимальний розмір файлу: 100 MB. Має використовувати 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 MB.
    • Завдання не успішне: посилане завдання ще очікує, виконується або не вдалося.
  • Name
    401 - Unauthorized
    Description

    Автентифікація не вдалася. Будь ласка, перевірте ваш API-ключ.

  • Name
    403 - Forbidden
    Description

    Завдання існує, але належить іншому користувачу.

  • Name
    404 - Not Found
    Description

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

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

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

Запит

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"
  }'

Відповідь

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/print/analyze/:id

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

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

Параметри

  • Name
    id
    Type
    path
    Description

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

Повертає

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

Запит

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}"

Відповідь

{
  "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

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

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

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

  • Name
    id
    Type
    path
    Description

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

Повертає

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

Запит

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}"

Відповідь

// Returns 200 Ok on success.
GET/openapi/v1/print/analyze

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

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

Параметри

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

  • Name
    page_num
    Type
    integer
    Description

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

  • Name
    page_size
    Type
    integer
    Description

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

  • Name
    sort_by
    Type
    string
    Description

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

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

Повертає

Повертає список з пагінацією Об'єктів завдань Аналізу придатності до друку.

Запит

GET
/openapi/v1/print/analyze
curl https://api.meshy.ai/openapi/v1/print/analyze?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Відповідь

[
  {
    "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.

Запит

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

    Прогрес завдання. Якщо завдання ще не розпочато, це властивість буде 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. Цей endpoint безкоштовний.

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
}