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

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

POST/openapi/v1/print/repair

Create a Repair Printability Task

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

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

Параметры

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

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

  • 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 для восстановления.
  • 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": "",
    "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 задачи восстановления пригодности к печати, которую нужно удалить.

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

Задача, которая всё ещё находится в статусе PENDING, удаляется, а кредиты, потраченные при её создании, возвращаются.

Задача, которая уже находится в статусе IN_PROGRESS, не может быть удалена: запрос отклоняется с ошибкой 409 Conflict, и задача продолжает выполняться. Кредиты за задачу, которую воркер уже начал выполнять, не подлежат возврату, поэтому удаление её в процессе выполнения приведёт к потере как кредитов, так и результата. Дождитесь, пока она перейдёт в статус SUCCEEDED, FAILED или CANCELED, а затем удалите её.

Задача в финальном статусе (SUCCEEDED, FAILED или CANCELED) удаляется без возврата средств.

Возвращает

Возвращает 200 OK при успешном выполнении или 409 Conflict, если задача находится в статусе IN_PROGRESS.

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

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

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

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

Параметры

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

  • 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/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=***",
      "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.

Каждый кадр содержит полный объект задачи для данного этапа — такую же структуру, что возвращает эндпоинт Get — поэтому, пока задача имеет статус PENDING или IN_PROGRESS, выходные поля просто ещё не заполнены (null, [] или {}), а finished_at равно null. Блок 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.
// 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-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-sortable 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

    Ссылки для скачивания восстановленной 3D-модели. Заполнено только то поле, которое соответствует входному формату; остальные поля форматов — пустые строки.

    • Name
      glb
      Type
      string
      Description

      Ссылка для скачивания восстановленного GLB. Заполняется, если входной файл был GLB или использовался input_task_id.

    • Name
      gltf
      Type
      string
      Description

      Ссылка для скачивания восстановленного GLTF. Заполняется, если входной файл был загружен в формате GLTF.

    • Name
      fbx
      Type
      string
      Description

      Ссылка для скачивания восстановленного FBX. Заполняется, если входной файл был загружен в формате FBX.

    • Name
      obj
      Type
      string
      Description

      Ссылка для скачивания восстановленного OBJ. Заполняется, если входной файл был загружен в формате OBJ.

    • Name
      stl
      Type
      string
      Description

      Ссылка для скачивания восстановленного 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

    Ссылка для скачивания версии 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=***",
    "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
}