Auto Split API

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

Auto Split наразі підтримує лише нетекстуровані моделі. Для Зображення у 3D та Мульти-зображення у 3D створюйте вхідні дані з should_texture, встановленим у false. Текстуровані вхідні дані відхиляються з кодом 400. Підтримка текстурованих моделей у процесі розробки.

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 або latest). Низькополігональні моделі та моделі Smart Topology (meshy-t2) не підтримуються.

  • Name
    mode
    Type
    string
    за замовчуванням auto
    Description

    Як модель розділяється на частини.

    Доступні значення:

    • auto: Meshy самостійно обирає лінії розрізу. prompt ігнорується.
    • by_parts: Розрізати по структурних частинах, які ви вказуєте у prompt, наприклад голова, руки та торс.
    • by_color: Розрізати по колірних областях, які ви вказуєте у prompt. Потребує вхідних даних, згенерованих із завантаженого зображення (Зображення у 3D або Мульти-зображення у 3D); інші вхідні дані відхиляються з кодом 400.
Застосовується лише коли mode = by_parts or by_color
  • Name
    prompt
    Type
    string
    Обов'язковий
    Description

    Описує частини, на які потрібно розділити модель, будь-якою мовою. Meshy зчитує від 1 до 10 назв частин з нього, тож називайте саме частини, а не описуйте модель — наприклад розділити на фігурку та основу, або голова, торс, ліва рука, права рука, ноги. До 600 символів. Є два режими відмови: якщо опис виглядає як розділення, але називає менше двох частин (наприклад розділити на окремі частини), запит відхиляється з кодом 400 і оплата не стягується; якщо Meshy взагалі не може розпізнати опис, він переходить у режим auto, завдання все одно виконується та оплачується, а у відповіді буде поле prompt_ignored: true.

  • Name
    target_formats
    Type
    array
    за замовчуванням ["glb"]
    Description

    Формати, у яких експортується розділена модель. Кожна частина є окремим об'єктом у кожному форматі. glb завжди генерується і повертається у model_urls; вказуйте додатково будь-які інші потрібні формати.

    Доступні значення: glb, obj, fbx, usdz, blend, 3mf.

    3mf створюється для слайсерів: один об'єкт на частину, кожен на власному слоті філаменту, тож Bambu Studio відкриває файл із частинами, забарвленими окремо та доступними для окремого вибору (архів містить конфігурацію проєкту Bambu Studio; інші слайсери читають лише геометрію). Як і інші формати друку Meshy, він вимірюється в міліметрах, і оскільки ця кінцева точка не приймає цільовий розмір, вся модель масштабується так, щоб її найдовша сторона становила 150 мм — те саме обмеження, яке використовується для інших форматів експорту друку, обране так, щоб підходити для будь-якої поширеної друкувальної платформи. При layout: "on_plate" це обмеження застосовується до всієї розкладеної на платформі моделі, тож файл готовий до нарізки на слайси; при assembled частини залишаються на своїх місцях, як у вихідній моделі, а розташовувати їх потрібно вже у слайсері.

    stl не підтримується, оскільки цей формат не може містити окремі частини.

  • Name
    layout
    Type
    string
    за замовчуванням assembled
    Description

    Як частини розташовані у кожному вихідному форматі та на мініатюрі.

    Доступні значення:

    • assembled: Частини залишаються там, де вони були у вихідній моделі.
    • on_plate: Частини розкладені пласко та розсунуті на друкувальній платформі, готові до нарізки на слайси — таке саме розташування, як у режимі On Plate веб-застосунку.

    В обох варіантах розташування експортовані файли містять по одному об'єкту на кожну частину і нічого більше: сплощений уламок або точкоподібний фрагмент, що залишився після розрізу, видаляється перед експортом, тож кожен об'єкт у файлі придатний для друку.

  • 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 потребує принаймні двох названих частин (наприклад голова, торс, основа); загальна інструкція, така як розділити на окремі частини, відхиляється. Оплата не стягується.
    • Непідтримуване вхідне завдання: input_task_id повинен посилатися на успішне завдання підтримуваного типу, згенероване за допомогою Meshy 6 або Meshy 7.
    • Текстуровані вхідні дані: Вхідна модель має текстури. На даний момент підтримуються лише моделі без текстур.
    • Немає референсного зображення: by_color потребує вхідних даних, згенерованих із завантаженого зображення.
    • Непідтримуваний формат: target_formats містить stl.
    • З'єднувач поза допустимим діапазоном: 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 запитів на хвилину на облiковий запис.

  • 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, яке потрібно видалити.

Повертає

Повертає 200 OK у разі успіху.

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

// Returns 200 Ok on success.
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

Stream an Auto Split Task

Ця кінцева точка транслює оновлення в реальному часі для завдання 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 і parts з'являються після досягнення статусу 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 містить лише перелічені нижче властивості. Поля з prompt для генерації, які містять інші об'єкти завдань (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-адреси для завантаження розділеної моделі, одна на кожен запитаний формат. Кожна частина — окремий об'єкт у файлі. Властивість для формату буде відсутня, якщо цей формат не було запитано.

    • Name
      glb
      Type
      string
      Description

      URL-адреса для завантаження розділеної моделі у форматі GLB.

    • Name
      obj
      Type
      string
      Description

      URL-адреса для завантаження розділеної моделі у форматі OBJ.

    • Name
      fbx
      Type
      string
      Description

      URL-адреса для завантаження розділеної моделі у форматі FBX.

    • Name
      usdz
      Type
      string
      Description

      URL-адреса для завантаження розділеної моделі у форматі USDZ.

    • Name
      blend
      Type
      string
      Description

      URL-адреса для завантаження розділеної моделі у форматі Blender.

    • Name
      3mf
      Type
      string
      Description

      URL-адреса для завантаження розділеної моделі у форматі 3MF: по одному об'єкту на кожну частину, кожна на власному слоті нитки, у міліметрах, масштабовано так, щоб найдовша сторона становила 150 мм, із конфігурацією проєкту Bambu Studio.

  • 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

    Кількість придатних для друку частин у розділеній моделі — по одній на кожен об'єкт в експортованих файлах. Стиснуті фрагменти, які сегментація не змогла перетворити на придатну для друку частину, видаляються з файлів перед експортом і не враховуються.

  • 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.

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