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 имеет приоритет.

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

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

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

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 asset для восстановления.
Name
401 - Unauthorized
Description
Аутентификация не удалась. Пожалуйста, проверьте ваш API-ключ.
Name
402 - Payment Required
Description
Общие причины:
- Бесплатный план: создание задачи требует платного плана. Обновите на странице подписки.
- Недостаточно кредитов: достигнут лимит кредитов рабочей области.
Name
404 - Not Found
Description
Указанная задача не существует или принадлежит другому пользователю.
Name
429 - Too Many Requests
Description
Вы превысили квоту на ожидающие задачи или ограничение частоты.

Запрос

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

Ответ

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

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

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

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

Параметры

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

Возвращает

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

Запрос

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

Ответ

{
  "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": "",
    "gltf": "",
    "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 в случае успеха.

Запрос

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

Ответ

// Returns 200 Ok on success.

GET/openapi/v1/print/repair

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

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

Параметры

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

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

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

Ответ

[
  {
    "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=***",
      "gltf": "",
      "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.

Запрос

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=***",
    "gltf": "",
    "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
Прогресс выполнения задачи. Если задача еще не начата, это свойство будет 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
  gltf
  Type
  string
  Description
  Скачиваемый URL-адрес восстановленного GLTF. Заполняется, когда входной файл был загружен в формате GLTF.
- Name
  fbx
  Type
  string
  Description
  Скачиваемый URL-адрес восстановленного FBX. Заполняется, когда входной файл был загружен в формате 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
Всегда пустой массив. Восстановление сохраняет только входную геометрию и не пересоздает 3D texture.
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=***",
    "gltf": "",
    "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
}