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 назв частин, тому називайте саме частини, а не описуйте модель — наприклад, split into the figure and the base, або head, torso, left arm, right arm, legs. До 600 символів. Є два режими відмови: опис, який виглядає як розділення, але називає менше двох частин (наприклад, split into individual parts), відхиляється з кодом 400, і плата не стягується; опис, який Meshy взагалі не може зрозуміти, повертається до режиму auto, завдання все одно виконується та оплачується, а у відповіді присутнє поле prompt_ignored: true.

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

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

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

  • 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 вимагає щонайменше двох названих частин (наприклад, head, torso, base); загальна інструкція на кшталт split into individual parts відхиляється. Плата не стягується.
    • Непідтримуване вхідне завдання: 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 запитів за хвилину на обліковий запис.

  • 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.cn/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.cn/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.cn/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.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/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.cn/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.cn/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.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.cn/***/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.cn/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.cn/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/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-адреси для завантаження розділеної моделі, по одній для кожного запитаного формату. Кожна частина є окремим об'єктом у файлі. Властивість для формату буде відсутня, якщо формат не запитувався.

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

  • 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.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/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
}