API Auto Split

Розділіть 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) не підтримуються. Модель із текстурою приймається, але її текстура не переноситься до результату.

  • 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 взагалі не може зчитати, повертається до auto, завдання все одно виконується і оплачується, а у відповіді буде поле prompt_ignored: true.

  • 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

    Ідентифікатор завдання 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: Сортування за часом створення в порядку спадання.

Повертає

Повертає список об'єктів The Auto Split Task Objects з пагінацією.

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

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