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

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

POST/openapi/v1/print/analyze

Create an Analyze Printability Task

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

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

Параметры

Требуется указать только один из параметров: 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

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

Этот эндпоинт позволяет получить список задач анализа пригодности к печати.

Параметры

Необязательные атрибуты

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
}

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
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
  Количество проблем уровня ошибки. Ошибки возникают, если модель не является водонепроницаемой (watertight), имеет неположительный объём, или содержит немногообразные рёбра.
- 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
}