Auto Split API

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

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

POST/openapi/v1/print/split

Create an Auto Split Task

Ця кінцева точка створює нове завдання 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

Retrieve an Auto Split Task

Ця кінцева точка отримує завдання 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

List Auto Split Tasks

Ця кінцева точка дозволяє отримати список завдань 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
URL-адреси для завантаження розбитої моделі, по одній для кожного запитаного формату. Формати, що підтримують об'єкти сцени, зберігають кожну частину як окремий об'єкт; stl зливає їх в одне суцільне тіло. Властивість для формату буде опущена, якщо цей формат не було запитано.
- Name
  glb
  Type
  string
  Description
  URL-адреса для завантаження розбитої моделі у форматі GLB.
- Name
  obj
  Type
  string
  Description
  URL-адреса для завантаження розбитої моделі у форматі OBJ.
- Name
  fbx
  Type
  string
  Description
  URL-адреса для завантаження розбитої моделі у форматі FBX.
- Name
  stl
  Type
  string
  Description
  URL-адреса для завантаження розбитої моделі у форматі STL. Усі частини зливаються в одне суцільне тіло; запитайте 3mf для окремо вибираних частин.
- Name
  usdz
  Type
  string
  Description
  URL-адреса для завантаження розбитої моделі у форматі USDZ.
- Name
  blend
  Type
  string
  Description
  URL-адреса для завантаження розбитої моделі у форматі Blender.
- Name
  3mf
  Type
  string
  Description
  URL-адреса для завантаження розбитої моделі у форматі 3MF.
Name
thumbnail_url
Type
string
Description
URL-адреса для завантаження рендерованого попереднього перегляду розбитої моделі, з кожною частиною окремого кольору, у запитаному layout.
Name
prompt_ignored
Type
boolean
Description
true, якщо prompt запиту by_parts або by_color не називав жодних частин, тому 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
}