lowpoly будет отключён 30 окт. 2026 г.. Перейдите на другую модель до этих дат, чтобы избежать ошибок в запросах.

Analyze Printability API

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


POST/openapi/v1/print/analyze

Create an Analyze Printability Task

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

Задача выполняется в фоновом режиме. О том, сколько времени это обычно занимает, см. Время обработки.

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

Чтобы также проверить толщину стенки при размере, в котором вы планируете печатать, отправьте printer_type, размер печати или оба параметра. Результат возвращается в printability.thin_walls. Проверка толщины стенки занимает больше времени, поэтому задача обычно не готова сразу, даже если модель уже была проанализирована ранее.

Параметры

  • Name
    model_url
    Type
    string
    Обязательный
    Description

    URL 3D-модели для анализа. Поддерживаемые форматы: .glb, .gltf, .obj, .fbx, .stl. Используйте http- или https-URL, либо base64 data:-URL для GLB (data:model/gltf-binary;base64,...) или glTF (data:model/gltf+json;base64,...). Файлы .obj, .fbx и .stl должны передаваться в виде http- или https-URL.

    Максимальный размер файла: 400 МБ для http- или https-URL, 100 МБ для data:-URI.

    Файл GLB, glTF, FBX или OBJ размером более 100 МБ может содержать не более 10 000 000 граней. Грани считаются как треугольники: четырёхугольник считается за 2, а сетка, нарисованная более одного раза, считается по разу за каждую копию. При размере более 100 МБ файл FBX должен быть бинарным FBX версии 7.1 или новее, а файл GLB или glTF не должен использовать сжатие Draco.

    Ссылки для скачивания Meshy (assets.meshy.ai/…?Expires=…&Signature=…) подписаны и перестают работать по достижении expires_at задачи; повторный запрос задачи не обновляет их. Для модели, сгенерированной с помощью Meshy, передавайте вместо этого input_task_id. Это работает, пока исходная задача сохраняется (см. Хранение ресурсов). Чтобы повторно использовать модель позже, скачайте её до наступления expires_at и отправьте свою собственную копию.

  • Name
    printer_type
    Type
    string
    Description

    Принтер, который вы планируете использовать. Он задаёт минимальную толщину стенки для проверки толщины стенки. По умолчанию используется fdm, когда вы отправляете размер печати без указания этого параметра.

    Доступные значения:

    • fdm: филамент, минимальная толщина стенки 1,0 мм.
    • sla: смола, минимальная толщина стенки 0,8 мм.
    • full_color: полноцветная печать, минимальная толщина стенки 2,0 мм.
  • Name
    intended_print_height_mm
    Type
    number
    Description

    Высота печати в миллиметрах. Диапазон: [1, 1000]. Округляется до ближайшего миллиметра. Только для ввода GLB.

  • Name
    intended_print_longest_side_mm
    Type
    number
    Description

    Длина наибольшей стороны печати в миллиметрах. Диапазон: [1, 1000]. Округляется до ближайшего миллиметра. Работает с любым форматом ввода.

Возвращаемое значение

Свойство result ответа содержит id только что созданной задачи анализа пригодности к печати.

Режимы сбоя

  • Name
    400 - Bad Request
    Description

    Запрос был неприемлем. Распространённые причины:

    • Отсутствует параметр: не был указан ни input_task_id, ни model_url.
    • Недопустимый UUID: input_task_id не является допустимым UUID.
    • Недопустимый URL модели: model_url имеет неверный формат, использует неподдерживаемую схему или имеет неподдерживаемое расширение файла.
    • Файл модели слишком большой: тело model_url превысило 400 МБ (http- или https-URL) или 100 МБ (data:-URI).
    • Слишком много граней: model_url — это файл GLB, glTF, FBX или OBJ размером более 100 МБ с более чем 10 000 000 граней. Уменьшите количество граней и отправьте файл снова.
    • ASCII FBX более 100 МБ: model_url — это ASCII FBX размером более 100 МБ. Отправьте его как бинарный FBX или GLB.
    • Нечитаемый файл модели: model_url превышает 100 МБ, и его заголовок невозможно прочитать, например сжатый с помощью Draco GLB или glTF, либо бинарный FBX старше версии 7.1.
    • Заголовок модели слишком сложный: model_url превышает 100 МБ, и его заголовок содержит слишком много сеток, узлов или записей для проверки. Уменьшите количество объектов в файле и отправьте его снова.
    • Не удалось скачать файл модели: model_url вернул ошибку, чаще всего из-за истёкшего срока действия подписанной ссылки для скачивания Meshy. Повторный запрос задачи возвращает тот же URL с тем же сроком действия, поэтому отправьте собственную копию файла или используйте input_task_id, пока исходная задача ещё сохраняется.
    • Задача не завершена успешно: указанная задача всё ещё ожидает выполнения, выполняется или завершилась неудачно.
    • Недопустимый размер печати: intended_print_height_mm или intended_print_longest_side_mm выходит за пределы [1, 1000], либо были отправлены оба параметра.
    • Неизвестный тип принтера: printer_type не равен fdm, sla или full_color.
    • Высота для модели не в формате GLB: intended_print_height_mm был отправлен с model_url, который не является .glb. Используйте вместо этого intended_print_longest_side_mm.
    • Невозможно задать размер этой модели по высоте: при запрошенной высоте (или высоте по умолчанию 150 мм) наибольшая сторона модели выйдет за пределы [1, 1000] мм, модель плоская, либо её размер не может быть определён. Используйте вместо этого intended_print_longest_side_mm. Для model_url в формате .glb и некоторых задач input_task_id это выясняется только после начала выполнения задачи, и задача завершается со статусом FAILED.
    • Непригодный размер STL: printer_type был отправлен без указания размера, а собственная наибольшая сторона .stl не может быть прочитана либо выходит за пределы [1, 1000] мм. Отправьте intended_print_longest_side_mm.
  • Name
    401 - Unauthorized
    Description

    Ошибка аутентификации. Пожалуйста, проверьте свой API-ключ.

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

# Also check wall thickness for a 100 mm tall SLA print
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",
    "printer_type": "sla",
    "intended_print_height_mm": 100
  }'

Response

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

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

Получить задачу «Анализ пригодности к печати»

Этот эндпоинт получает задачу анализа пригодности к печати по её ID.

Параметры

  • Name
    id
    Type
    path
    Description

    ID задачи анализа пригодности к печати, которую нужно получить.

Возвращает

Объект задачи «Анализ пригодности к печати». Поле printability равно null, пока задача не достигнет статуса SUCCEEDED. Если проверялась толщина стенки, printability также включает intended_print и thin_walls.

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
}

Response (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "consumed_credits": 0
}

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

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

Этот эндпоинт безвозвратно удаляет задачу анализа пригодности к печати и её кэшированный результат. Это действие необратимо.

Параметры пути

  • Name
    id
    Type
    path
    Description

    ID задачи анализа пригодности к печати, которую нужно удалить.

Статус задачи

Задача, которая всё ещё находится в статусе 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
}

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

    Прогресс выполнения задачи. Если задача ещё не начата, это свойство будет равно 0. Как только задача завершится успешно, оно станет равным 100.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Количество предшествующих задач.

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

      Если проверялась толщина стенки, это худшее значение из приведённых выше проверок и thin_walls.status. От худшего к лучшему: error, warning, unknown, healthy.

    • Name
      issue_count
      Type
      integer
      Description

      Общее количество проблем, равное error_count + warning_count.

    • Name
      error_count
      Type
      integer
      Description

      Количество проблем уровня ошибки. Ошибки возникают, если модель не является водонепроницаемой (watertight), имеет неположительный объём, либо содержит немногообразные рёбра. Если проверялась толщина стенки, стенки, которые слишком тонкие (thin_walls.status равен error), считаются ещё одной дополнительной ошибкой.

    • 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
      intended_print
      Type
      object
      Description

      Принтер и размер, использованные при проверке толщины стенки. Присутствует только если толщина стенки проверялась.

      • Name
        printer_type
        Type
        string
        Description

        fdm, sla или full_color.

      • Name
        height_mm
        Type
        number
        Description

        Высота печати в миллиметрах, если размер печати определялся по высоте. В противном случае null.

      • Name
        longest_side_mm
        Type
        number
        Description

        Длина самой длинной стороны модели печати в миллиметрах. При определении размера по высоте вычисляется исходя из пропорций модели.

      • Name
        wall_thickness_mm
        Type
        number
        Description

        Минимальная толщина стенки для printer_type, в миллиметрах. Стенки тоньше этого значения сообщаются как слишком тонкие.

      • Name
        dimensions_mm
        Type
        array
        Description

        Размеры модели печати [ширина, глубина, высота] в миллиметрах. Высота может отличаться от height_mm на долю миллиметра. null для входных данных не в формате GLB или если размер модели не удаётся определить.

    • Name
      thin_walls
      Type
      object
      Description

      Результат проверки толщины стенки. Присутствует только если толщина стенки проверялась.

      • Name
        thin_area_ratio
        Type
        number
        Description

        Доля поверхности, от 0 до 1, которая тоньше, чем intended_print.wall_thickness_mm. null, если модель не удалось измерить.

      • Name
        has_thin_walls
        Type
        boolean
        Description

        true, если какая-либо часть поверхности слишком тонкая. Одни лишь острые углы могут вызвать это значение, поэтому для решения о необходимости утолщения стенок используйте status. null, если модель не удалось измерить.

      • Name
        status
        Type
        string
        Description

        Вердикт по толщине стенки. Одно из:

        • healthy: 5% или менее поверхности слишком тонкие.
        • error: более 5% поверхности слишком тонкие. Чтобы утолщить стенки, передайте id этой задачи в Восстановление пригодности к печати в качестве input_task_id (для model_url с расширением .stl, .fbx или .gltf отправьте файл в качестве model_url вместо этого).
        • unknown: модель не удалось измерить. Если сама проверка толщины стенки завершается неудачно, задача получает статус FAILED.
    • 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
}

The Analyze Printability Task Object (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "consumed_credits": 0
}