API восстановления пригодности к печати

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

POST/openapi/v1/print/repair

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

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

Выходной формат совпадает с входным форматом. Если вы отправляете .stl через model_url, model_urls.stl в ответе будет содержать восстановленную сетку, а поля других форматов будут пустыми. Вариант с input_task_id всегда считывает GLB исходной задачи, поэтому выходной файл имеет формат .glb.

Параметры

Требуется только один из параметров: input_task_id или model_url. Если указаны оба, input_task_id имеет приоритет.

Существующие текстуры удаляются во время восстановления из-за изменений геометрии. Чтобы добавить текстуры обратно, используйте API Ретекстурирование для восстановленной модели.

Name
input_task_id
Type
string
Обязательный
Description
ID успешной задачи, которой вы владеете. Поддерживаемые типы задач: Изображение в 3D, Мульти-изображение в 3D, Текст в 3D, Ремешинг и Ретекстурирование. Задача должна иметь статус SUCCEEDED и должна была создать GLB-ассет.

Name
model_url
Type
string
Обязательный
Description
URL 3D-модели для восстановления. Поддерживаемые форматы: .glb, .stl, .obj. Максимальный размер файла: 100 МБ. Должен использоваться URL со схемой http, https или data: (URL-адреса data обходят проверки расширения).

Name
alpha_thumbnail
Type
boolean
по умолчанию false
Description
Если задано значение true, задача дополнительно рендерит версию предпросмотра с прозрачным фоном (RGBA) и возвращает ее как alpha_thumbnail_url в ответе GET. Существующее поле thumbnail_url не изменяется.

Возвращаемые данные

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

Режимы сбоев

Name
400 - Bad Request
Description
Запрос был неприемлем. Распространенные причины:
- Отсутствует параметр: не был предоставлен ни input_task_id, ни model_url.
- Недействительный UUID: input_task_id не является действительным UUID.
- Недействительный URL модели: model_url имеет неверный формат, использует неподдерживаемую схему или имеет неподдерживаемое расширение файла.
- Файл модели слишком большой: тело model_url превысило 100 МБ.
- Задача не выполнена успешно: указанная задача все еще ожидает выполнения, выполняется или завершилась с ошибкой.
- Отсутствует GLB: у указанной задачи нет GLB-ассета для восстановления.
Name
401 - Unauthorized
Description
Аутентификация не удалась. Проверьте свой API-ключ.
Name
402 - Payment Required
Description
Распространенные причины:
- Бесплатный план: для создания задачи требуется платный план. Выполните апгрейд на странице подписки.
- Недостаточно кредитов: достигнут лимит кредитов рабочей области.
Name
404 - Not Found
Description
Указанная задача не существует или принадлежит другому пользователю.
Name
429 - Too Many Requests
Description
Вы превысили квоту ожидающих задач или ограничение частоты.

Request

POST

/openapi/v1/print/repair

# Repair an existing task
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Or repair a model URL directly
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.stl"
  }'

Response

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

GET/openapi/v1/print/repair/:id

Получение задачи Восстановление пригодности к печати

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

Параметры

Name
id
Type
path
Description
ID задачи восстановления пригодности к печати, которую нужно получить.

Возвращает

Объект задачи Восстановление пригодности к печати. Блок model_urls пуст, пока задача не достигнет SUCCEEDED. Заполняется только поле model_urls, соответствующее входному формату.

Request

GET

/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "",
    "fbx": "",
    "obj": "",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}

DELETE/openapi/v1/print/repair/:id

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

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

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

Name
id
Type
path
Description
ID задачи восстановления пригодности к печати, которую нужно удалить.

Возвращает

Возвращает 200 OK при успешном выполнении.

Request

DELETE

/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/print/repair

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

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

Параметры

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

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/repair

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-repair",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000030000,
    "expires_at": 1715725401000,
    "task_error": null,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "",
      "obj": "",
      "stl": "",
      "usdz": "",
      "3mf": "",
      "mtl": ""
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "texture_urls": [],
    "consumed_credits": 10
  }
]

GET/openapi/v1/print/repair/:id/stream

Потоковая передача задачи «Восстановление пригодности к печати»

Этот эндпоинт передает обновления в реальном времени для задачи восстановления пригодности к печати с использованием Server-Sent Events (SSE).

Параметры

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

Возвращаемые данные

Возвращает поток объектов задач восстановления пригодности к печати в виде Server-Sent Events.

Для задач PENDING или IN_PROGRESS поток ответа будет включать только необходимые поля progress и status. Блок model_urls отправляется только после того, как задача достигнет SUCCEEDED.

Request

GET

/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/repair/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-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}

Объект задачи Восстановление пригодности к печати

Name
id
Type
string
Description
Уникальный идентификатор задачи. Хотя мы используем k-сортируемый UUID для идентификаторов задач как деталь реализации, вам не следует делать каких-либо предположений о формате id.
Name
type
Type
string
Description
Тип задачи восстановления пригодности к печати. Значение — print-repair.
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
model_urls
Type
object
Description
URL-адреса для скачивания восстановленной 3D-модели. Заполняется только поле, соответствующее входному формату; поля других форматов являются пустыми строками.
- Name
  glb
  Type
  string
  Description
  URL-адрес для скачивания восстановленного GLB. Заполняется, когда входными данными был GLB или когда использовался input_task_id.
- Name
  fbx
  Type
  string
  Description
  Зарезервировано для вывода FBX. Всегда пустая строка для задач восстановления пригодности к печати.
- Name
  obj
  Type
  string
  Description
  URL-адрес для скачивания восстановленного OBJ. Заполняется, когда входными данными была загрузка OBJ.
- Name
  stl
  Type
  string
  Description
  URL-адрес для скачивания восстановленного STL. Заполняется, когда входными данными была загрузка STL.
- Name
  usdz
  Type
  string
  Description
  Зарезервировано для вывода USDZ. Всегда пустая строка для задач восстановления пригодности к печати.
- Name
  3mf
  Type
  string
  Description
  Зарезервировано для вывода 3MF. Всегда пустая строка для задач восстановления пригодности к печати.
- Name
  mtl
  Type
  string
  Description
  Зарезервировано для вывода MTL. Всегда пустая строка для задач восстановления пригодности к печати.
Name
thumbnail_url
Type
string
Description
URL-адрес изображения предпросмотра, отрендеренного из восстановленной модели.
Name
alpha_thumbnail_url
Type
string
Description
URL-адрес для скачивания версии thumbnail_url с прозрачным фоном (RGBA). Присутствует только когда задача была создана с alpha_thumbnail: true и прозрачный предпросмотр был успешно отрендерен; в противном случае это поле опускается.
Name
texture_urls
Type
array
Description
Всегда пустой массив. Восстановление сохраняет только входную геометрию и не выполняет повторное запекание текстур.
Name
consumed_credits
Type
integer
Description
Количество кредитов, израсходованных этой задачей. 10 после того, как задача достигла SUCCEEDED. Возвращает 0 для задач FAILED (кредиты возвращаются при сбое).

The Repair Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}