Auto Split API

Разделите 3D-модель на отдельные печатаемые части — автоматически, по частям, которые вы назовёте, или по цветовым областям — с опциональными соединителями; тонкие участки, оставшиеся после разреза, всегда усиливаются, чтобы каждая часть печаталась сплошной.

Результат разделения не сохраняет текстуру исходной модели. Auto Split принимает на вход модели с текстурами, поэтому вам не нужно повторно генерировать модель с параметром should_texture: false. Он перестраивает разрезанные части и присваивает каждой из них однородный цвет вершин; ни одна входная карта текстуры не переносится ни в один из экспортируемых форматов.

POST/openapi/v1/print/split

Создание задачи Auto Split

Этот эндпоинт создаёт новую задачу Auto Split. Задача разрезает модель из предыдущей задачи на отдельно печатаемые части и возвращает сегментированную модель, где каждая часть представлена как отдельный объект в файле.

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

Параметры

Name
input_task_id
Type
string
Обязательный
Description
ID успешно завершённой задачи, модель которой нужно разделить. Поддерживаемые типы задач: Изображение в 3D, Мульти-изображение в 3D, Текст в 3D (предварительная версия), Ремешинг, Конвертировать и Изменить размер. Задача должна иметь статус SUCCEEDED, а её модель должна быть создана с использованием Meshy 6 или Meshy 7 (ai_model meshy-6, meshy-7, meshy-7.1 или latest). Низкополигональные модели и модели Smart Topology (meshy-t2, meshy-t2.5) не поддерживаются. Текстурированная модель принимается, но её текстура не переносится в результат.

Name
mode
Type
string
по умолчанию auto
Description
Как модель разделяется на части.
Доступные значения:
- auto: Meshy сама выбирает разрезы. prompt игнорируется.
- by_parts: разрезать по структурным частям, которые вы указали в prompt, например голова, руки и торс.
- by_color: разрезать по цветовым областям, которые вы указали в prompt. Требует входных данных, созданных из загруженного изображения (Изображение в 3D или Мульти-изображение в 3D); остальные входные данные отклоняются с ошибкой 400. Границы цветовых областей берутся из исходного изображения, а не из текстуры входной модели. Для Мульти-изображение в 3D Auto Split использует первое исходное изображение.

Применяется только когда mode = by_parts or by_color

Name
prompt
Type
string
Обязательный
Description
Описывает части, на которые нужно разделить модель, на любом языке. Meshy считывает из него от 1 до 10 названий частей, поэтому называйте именно сами части, а не описывайте модель целиком, например split into the figure and the base, или head, torso, left arm, right arm, legs. Указать только одну часть допустимо: всё, что вы не назвали, станет одной оставшейся частью, поэтому the head разделит модель на голову и остальное, как в веб-приложении. Максимум 600 символов. Описание, которое просит вообще не делить модель или называет более 10 частей, отклоняется с ошибкой 400, и плата не взимается. Если Meshy не может распознать названия частей в описании, она вместо этого разделяет модель по частям, которые определяет на эталонном изображении модели, в выбранном вами режиме: задача всё равно выполняется и оплачивается, и в ней указывается prompt_ignored: true. Если у модели нет эталонного изображения, или Meshy находит в нём менее двух частей, такой запрос отклоняется с ошибкой 400, и плата не взимается.

Name
target_formats
Type
array
по умолчанию ["glb"]
Description
Форматы, в которых нужно экспортировать разделённую модель. Форматы, поддерживающие объекты сцены (glb, obj, fbx, usdz, blend, 3mf), сохраняют каждую часть как отдельный объект; у stl нет понятия отдельных объектов, поэтому он объединяет все части в одно твёрдое тело, расположенное согласно layout (запросите 3mf, если нужны отдельно выбираемые части в слайсере). glb создаётся всегда и возвращается в model_urls; остальные нужные форматы указывайте дополнительно.
Доступные значения: glb, obj, fbx, stl, usdz, blend, 3mf.
Name
layout
Type
string
по умолчанию assembled
Description
Как части располагаются в каждом выходном формате и на миниатюре.
Доступные значения:
- assembled: части остаются там же, где они находились в исходной модели.
- on_plate: части раскладываются плоско и распределяются на столе печати, готовые к слайсингу — такое же расположение, как в режиме On Plate веб-приложения.
В обоих вариантах расположения свёрнутый тонкий срез или точкоподобный фрагмент, оставшийся после разреза, удаляется перед экспортом, так что каждая полученная часть пригодна для печати. Форматы, поддерживающие объекты сцены, хранят по одному объекту на часть; stl объединяет их в единое твёрдое тело.
Name
connectors
Type
boolean
по умолчанию false
Description
Добавляет соединители типа шип-паз в каждом месте разреза, чтобы напечатанные части соединялись друг с другом.

Применяется только когда connectors = true

Name
connector_type
Type
string
по умолчанию cube
Description
Форма соединителя на каждой поверхности разреза.
Доступные значения: cube, cylinder.
Name
connector_size
Type
number
по умолчанию 0.5
Description
Размер соединителя относительно поверхности разреза.
Допустимый диапазон: от 0.1 до 0.8.
Name
connector_height
Type
number
по умолчанию 0.1
Description
Насколько соединитель выступает за поверхность разреза, относительно поверхности разреза.
Допустимый диапазон: от 0.1 до 0.8.

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

Свойство result ответа содержит id вновь созданной задачи Auto Split.

Режимы отказа

Name
400 - Bad Request
Description
Запрос был некорректным. Распространённые причины:
- Отсутствует prompt: prompt обязателен, когда mode равен by_parts или by_color.
- Prompt не описывает разделение или описывает слишком много частей: by_parts / by_color принимает от 1 до 10 именованных частей. Описание, которое просит оставить модель цельной или называет более 10 частей, отклоняется. Плата не взимается.
- Неподдерживаемая входная задача: input_task_id должен ссылаться на успешно завершённую задачу поддерживаемого типа, созданную с использованием Meshy 6 или Meshy 7.
- Нет эталонного изображения: by_color требует входных данных, созданных из загруженного изображения.
- Соединитель вне допустимого диапазона: connector_size или connector_height выходит за пределы диапазона от 0.1 до 0.8.
Name
401 - Unauthorized
Description
Ошибка аутентификации. Пожалуйста, проверьте свой API-ключ.
Name
402 - Payment Required
Description
Недостаточно кредитов для выполнения этой задачи.
Name
404 - Not Found
Description
input_task_id не существует или не принадлежит вашему аккаунту.
Name
429 - Too Many Requests
Description
Вы превысили ограничение частоты запросов. Запросы by_parts и by_color также используют общий лимит на разбор prompt в 12 запросов в минуту на аккаунт.
Name
503 - Service Unavailable
Description
Разделение на основе prompt (by_parts и by_color) временно недоступно. Повторите попытку позже или используйте mode: "auto", который не подвержен этой проблеме. Плата не взимается.

Request

POST

/openapi/v1/print/split

# Simple request: let Meshy choose the cuts
curl https://api.meshy.ai/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Advanced request: name the parts, add connectors, export glb and obj
curl https://api.meshy.ai/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "mode": "by_parts",
    "prompt": "split into the figure and the base",
    "target_formats": ["glb", "obj"],
    "layout": "on_plate",
    "connectors": true,
    "connector_type": "cylinder",
    "connector_size": 0.4
  }'

Response

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

GET/openapi/v1/print/split/:id

Получение задачи Auto Split

Этот эндпоинт получает задачу Auto Split по её ID.

Параметры

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

Возвращает

Объект задачи Auto Split.

Request

GET

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

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

DELETE/openapi/v1/print/split/:id

Удаление задачи Auto Split

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

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

Name
id
Type
path
Description
ID задачи Auto Split, которую нужно удалить.

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

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

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

Задача в завершающем статусе (SUCCEEDED, FAILED или CANCELED) удаляется без возврата кредитов.

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

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

Request

DELETE

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

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/split/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/split

Список задач Auto Split

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

Параметры

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

Name
page_num
Type
integer
Description
Номер страницы для пагинации. Начинается и по умолчанию равен 1.
Name
page_size
Type
integer
Description
Ограничение размера страницы. По умолчанию 10 элементов. Максимально допустимое значение — 100 элементов; большие значения ограничиваются до 100.
Name
sort_by
Type
string
Description
Поле для сортировки. Доступные значения:
- +created_at: сортировка по времени создания в порядке возрастания.
- -created_at: сортировка по времени создания в порядке убывания.

Возвращает

Возвращает список объектов задачи Auto Split с пагинацией.

Request

GET

/openapi/v1/print/split

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-split",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "part_count": 4,
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000082000,
    "task_error": null,
    "consumed_credits": 10
  }
]

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

Потоковая передача задачи Auto Split

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

Параметры

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

Возвращает

Возвращает поток объектов задачи Auto Split в формате Server-Sent Events.

Каждое событие message содержит полный объект задачи, как он возвращается методом Получение задачи Auto Split, включая consumed_credits, временные метки и prompt_ignored; пока задача находится в статусе PENDING или IN_PROGRESS, между кадрами меняются поля progress, status, started_at и preceding_tasks, а поля model_urls, thumbnail_url и part_count появляются после перехода в статус SUCCEEDED. Событие error содержит только status_code и message, поэтому перед чтением status следует различать события по их имени.

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/print/split/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 (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

Объект задачи Auto Split

Задача Auto Split содержит только свойства, перечисленные ниже. Поля подсказок для генерации, которые включают другие объекты задач (name, object_prompt, texture_prompt и так далее), единственное поле model_url и texture_urls никогда не заполняются для разделения и не возвращаются. Свойства, которые заполняются по мере выполнения задачи (thumbnail_url, model_urls, временные метки), всегда присутствуют и остаются пустыми, пока не получат значение, поэтому набор ключей не меняется между PENDING и SUCCEEDED.

Name
id
Type
string
Description
Уникальный идентификатор задачи. Хотя в качестве деталей реализации мы используем k-сортируемый UUID для идентификаторов задач, вам не следует делать никаких предположений о формате id.
Name
type
Type
string
Description
Тип задачи. Значение — print-split.
Name
model_urls
Type
object
Description
Ссылки для скачивания разделённой модели, по одной на каждый запрошенный формат. Форматы, поддерживающие объекты сцены, сохраняют каждую часть как отдельный объект; stl объединяет их в одно твёрдое тело. Свойство для формата будет опущено, если формат не был запрошен.
- Name
  glb
  Type
  string
  Description
  Ссылка для скачивания разделённой модели в формате GLB.
- Name
  obj
  Type
  string
  Description
  Ссылка для скачивания разделённой модели в формате OBJ.
- Name
  fbx
  Type
  string
  Description
  Ссылка для скачивания разделённой модели в формате FBX.
- Name
  stl
  Type
  string
  Description
  Ссылка для скачивания разделённой модели в формате STL. Все части объединены в одно твёрдое тело; запросите 3mf, чтобы получить отдельно выбираемые части.
- Name
  usdz
  Type
  string
  Description
  Ссылка для скачивания разделённой модели в формате USDZ.
- Name
  blend
  Type
  string
  Description
  Ссылка для скачивания разделённой модели в формате Blender.
- Name
  3mf
  Type
  string
  Description
  Ссылка для скачивания разделённой модели в формате 3MF.
Name
thumbnail_url
Type
string
Description
Ссылка для скачивания отрендеренного превью разделённой модели, где каждая часть выделена своим цветом, в запрошенном layout.
Name
prompt_ignored
Type
boolean
Description
true, если в запросе by_parts или by_color prompt не называл ни одной части, поэтому Meshy разделил модель автоматически — названия частей в результате принадлежат Meshy, а не вам. Присутствует начиная с PENDING. Опускается для задач auto и во всех случаях, когда prompt был соблюдён.
Name
part_count
Type
integer
Description
Количество пригодных для печати частей, полученных в результате разделения. Форматы, поддерживающие объекты сцены, содержат по одному объекту на часть; stl объединяет их в одно твёрдое тело, но количество по-прежнему отражает число частей. Схлопнувшиеся фрагменты, которые сегментация не смогла превратить в пригодную для печати часть, удаляются из файлов перед экспортом и не учитываются в подсчёте.
Name
progress
Type
integer
Description
Прогресс выполнения задачи. Если задача ещё не начата, это свойство будет равно 0. Как только задача завершится успешно, оно станет равно 100.
Name
status
Type
string
Description
Статус задачи. Возможные значения: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
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
task_error
Type
object
Description
Сведения об ошибке для неудавшихся задач. Полное описание объекта task_error см. в разделе Ошибки. Если проверка безопасности поставщика модели отклоняет входную модель, задача завершается с task_error.type равным invalid_input и code равным provider_content_refused. См. Ошибки.
Name
consumed_credits
Type
integer
Description
Количество кредитов, потраченных на эту задачу. Присутствует всегда: 10 после принятия задачи и 0 для задач со статусом FAILED, поскольку списание возвращается при сбое. Удаление задачи, пока она ещё находится в статусе PENDING, также приводит к возврату.

The Auto Split Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}