API багатоколірного друку

Конвертувати 3D-моделі у багатоколірний формат 3MF для 3D-друку з настроюваною колірною палітрою до 16 кольорів.

POST/openapi/v1/print/multi-color

Створення завдання мультиколірного 3D-друку

Ця кінцева точка створює нове завдання мультиколірного 3D-друку. Завдання конвертує 3D-модель у мультиколірний файл 3MF, придатний для 3D-друку.

Параметри

Обов'язковим є лише один із параметрів: input_task_id або model_url. Якщо вказано обидва, пріоритет має input_task_id.

Name
input_task_id
Type
string
Обов'язковий
Description
Ідентифікатор успішного завдання, яке буде використано як вхідні дані. Підтримувані типи завдань: Зображення у 3D, Мульти-зображення у 3D, Текст у 3D, Ремеш та Ретекстурування. Завдання повинне мати статус SUCCEEDED.

Name
model_url
Type
string
Обов'язковий
Description
Публічно доступна URL-адреса або Data URI 3D-моделі. Наразі підтримуються формати .glb та .fbx.

Name
max_colors
Type
integer
за замовчуванням 4
Description
Максимальна кількість кольорів у вихідній палітрі.
Допустимий діапазон: від 1 до 16.
Name
style
Type
string
за замовчуванням realistic
Description
Візуальний стиль кольорів у створеному файлі 3MF.
Доступні значення:
- realistic: Вибирає кольори безпосередньо з текстури моделі для тонкої, фотореалістичної деталізації. Створює більший файл.
- cartoon: Зводить кольори до чистих, однорідних областей для стилізованого вигляду. Створює менший файл.
Вхідні дані повинні містити колір: realistic вимагає єдиної базової кольорової текстури з UV-координатами на кожній частині сітки; cartoon також приймає кольори по вершинах. Моделі без текстур (білі) відхиляються — див. model_missing_texture.
Name
max_depth
Type
integer
за замовчуванням 4
Description
Глибина підподілу, що використовується для накладання кольорів текстури на сітку. Вищі значення дозволяють захопити тонші деталі кольору за рахунок більшого розміру файлу. Застосовується лише до стилю realistic; ігнорується для cartoon.
Допустимий діапазон: від 3 до 6.
Name
printer_brand
Type
string
за замовчуванням bambu
Description
Бренд принтера, чий преднастроєний профіль слайсера записується у файл 3MF, щоб файл відкривався у слайсері цього бренду з відповідним принтером, філаментом та профілем процесу. Кожен бренд використовує свій принтер за замовчуванням із форсункою 0,4 мм.
Доступні значення: bambu, anycubic, creality, elegoo, flashforge, prusa, qidi, snapmaker, ankermake.

Результати

Властивість result у відповіді містить id новостворенoго завдання 3D-друку.

Режими збоїв

Name
400 - Bad Request
Description
Запит неприпустимий. Поширені причини:
- Відсутній параметр: Потрібно вказати або model_url, або input_task_id.
- Недійсний формат моделі: model_url вказує на файл із непідтримуваним розширенням (підтримуються лише .glb та .fbx).
- Недоступна URL-адреса: Не вдалося завантажити файл за адресою model_url.
- Недійсне вхідне завдання: input_task_id повинен посилатися на успішне завдання.
- Недійсне значення max_colors: Значення повинне бути в межах від 1 до 16.
- Недійсне значення style: Значення повинне бути realistic або cartoon.
- Недійсне значення max_depth: Значення повинне бути в межах від 3 до 6.
- Недійсне значення printer_brand: Значення повинне бути одним із брендів, перелічених вище.
- Немає джерела кольору: Вхідна модель не має базової кольорової текстури (realistic вимагає єдиної текстури з UV-координатами на кожній частині сітки) і не має кольорів по вершинах (cartoon приймає будь-що з цього). Спочатку нанесіть текстуру на модель або використовуйте cartoon для моделей із кольорами по вершинах. Завантажені файли .fbx перевіряються після нормалізації завданням і завершуються помилкою model_missing_texture.
Name
401 - Unauthorized
Description
Помилка автентифікації. Перевірте свій API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
429 - Too Many Requests
Description
Ви перевищили обмеження частоти запитів.

Request

POST

/openapi/v1/print/multi-color

# Convert a 3D model to a multi-color 3MF with a Creality slicer preset
curl https://api.meshy.ai/openapi/v1/print/multi-color \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "max_colors": 8,
    "printer_brand": "creality"
  }'

Response

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

GET/openapi/v1/print/multi-color/:id

Отримати завдання багатоколірного 3D-друку

Ця кінцева точка отримує завдання багатоколірного 3D-друку за його ID.

Параметри

Name
id
Type
path
Description
ID завдання 3D-друку, яке потрібно отримати.

Повертає

Об'єкт завдання 3D-друку.

Request

GET

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

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

DELETE/openapi/v1/print/multi-color/:id

Видалення завдання мультиколірного 3D-друку

Ця кінцева точка остаточно видаляє завдання мультиколірного 3D-друку, включно з усіма пов'язаними моделями та даними. Ця дія незворотна.

Параметри шляху

Name
id
Type
path
Description
ID завдання мультиколірного 3D-друку, яке потрібно видалити.

Статус завдання

Завдання, яке ще перебуває у статусі PENDING, видаляється, а кредити, витрачені під час створення, повертаються.

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

Завдання в кінцевому статусі (SUCCEEDED, FAILED або CANCELED) видаляється без повернення коштів.

Повертає

Повертає 200 OK у разі успіху або 409 Conflict, коли завдання перебуває у статусі IN_PROGRESS.

Request

DELETE

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

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

Список завдань багатокольорового 3D-друку

Ця кінцева точка дозволяє отримати список завдань багатокольорового 3D-друку.

Параметри

Необов'язкові атрибути

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

Повертає

Повертає розбитий на сторінки список об'єктів завдання 3D-друку.

Request

GET

/openapi/v1/print/multi-color

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-multi-color",
    "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
  "consumed_credits": 10
  }
]

GET/openapi/v1/print/multi-color/:id/stream

Потокова передача завдання 3D-друку з кількома кольорами

Ця кінцева точка передає в реальному часі оновлення для завдання 3D-друку з кількома кольорами за допомогою Server-Sent Events (SSE).

Параметри

Name
id
Type
path
Description
Унікальний ідентифікатор завдання 3D-друку з кількома кольорами, дані якого потрібно транслювати.

Повертає

Повертає потік Об'єктів завдання 3D-друку у формі Server-Sent Events.

Для завдань зі статусом PENDING або IN_PROGRESS потік відповіді міститиме лише необхідні поля progress та status.

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/print/multi-color/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-multi-color",
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.3mf?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

Об’єкт завдання 3D-друку

Name
id
Type
string
Description
Унікальний ідентифікатор завдання. Хоча як деталь реалізації ми використовуємо k-сортований UUID для ідентифікаторів завдань, вам не слід робити жодних припущень щодо формату id.
Name
type
Type
string
Description
Тип завдання 3D-друку. Значення — print-multi-color.
Name
model_urls
Type
object
Description
URL для завантаження файлу 3D-моделі, згенерованого Meshy. Властивість для формату буде відсутня, якщо формат не було згенеровано, замість повернення порожнього рядка.
- Name
  3mf
  Type
  string
  Description
  URL для завантаження мультиколірного файлу 3MF.
Name
progress
Type
integer
Description
Прогрес завдання. Якщо завдання ще не розпочато, ця властивість дорівнюватиме 0. Коли завдання завершиться успішно, вона стане 100.
Name
status
Type
string
Description
Статус завдання. Можливі значення: PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
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
Кількість кредитів, витрачених на це завдання. Присутня, коли статус завдання — PENDING, IN_PROGRESS або SUCCEEDED. Повертає 0 для завдань зі статусом FAILED (кредити повертаються у разі невдачі).

The 3D Print Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}