API Анализ пригодности к печати

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

POST/openapi/v1/print/analyze

Создание задачи Анализ пригодности к печати

Этот эндпоинт создает новую задачу анализа пригодности к печати. Задача оценивает 3D-модель и сообщает метрики ее пригодности к печати.

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

Параметры

Требуется только один из 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 МБ. Должен использовать http, https или 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-asset.
- Базовый файл модели больше недоступен в хранилище.
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
Тип задачи analyze-printability. Значение — 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
}