API Відновлення придатності до друку

Відновіть 3D модель для придатності до друку за допомогою FDM — виправте немноговидні ребра, вироджені грані, отвори та інші проблеми topology, щоб сітка була готова до друку.

POST/openapi/v1/print/repair

Створення завдання з відновлення придатності до друку

Цей endpoint створює нове завдання з відновлення придатності до друку. Завдання виконує відновлення 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
Ідентифікатор успішного завдання, яке ви володієте. Підтримувані типи завдань: Зображення у 3D, Мульти-зображення у 3D, Текст у 3D, Ремеш, та Ретекстурування. Завдання повинно мати статус SUCCEEDED і повинно було створити GLB asset.

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

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 MB.
- Завдання не виконано: посилане завдання ще в очікуванні, в процесі або не виконано.
- Відсутній 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

Видалення завдання з Відновлення придатності до друку

Цей endpoint назавжди видаляє завдання з відновлення придатності до друку та його відновлений результат. Ця дія є незворотною.

Параметри шляху

Name
id
Type
path
Description
Ідентифікатор завдання з відновлення придатності до друку, яке потрібно видалити.

Повертає

Повертає 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

Перелік завдань з відновлення придатності до друку

Цей endpoint дозволяє отримати перелік завдань з відновлення придатності до друку.

Параметри

Необов'язкові атрибути

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

Потік Відповідей

// 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 текстури.
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
}