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

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

POST/openapi/v1/print/multi-color

Create a Multi-Color 3D Print Task

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

Завдання виконується у фоновому режимі. Про те, скільки це зазвичай триває, див. Час обробки.

Параметри

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

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

Name
model_url
Type
string
Обов'язковий
Description
Публічно доступний URL моделі .glb або .fbx, або base64 data: URL для GLB (data:model/gltf-binary;base64,...). Файл .fbx повинен надсилатися як http або https URL.
Максимальний розмір файлу: 400 МБ для http або https URL, 100 МБ для data: URI.
Файл розміром понад 100 МБ може мати не більше 8 000 000 граней. Грані рахуються як трикутники: чотирикутник рахується як 2, а сітка, намальована кілька разів, рахується один раз для кожної копії. Понад 100 МБ, файл FBX повинен бути бінарним FBX версії 7.1 або новішим, а файл GLB не повинен використовувати стиснення Draco.

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 щойно створеного завдання 3D-друку.

Режими відмови

Name
400 - Bad Request
Description
Запит був неприйнятним. Поширені причини:
- Відсутній параметр: Потрібно вказати або model_url, або input_task_id.
- Недійсний формат моделі: model_url вказує на файл із непідтримуваним розширенням (підтримуються лише .glb та .fbx).
- Недоступний URL: Не вдалося завантажити файл за адресою model_url.
- Файл моделі занадто великий: Файл model_url перевищує 400 МБ (http або https URL) або 100 МБ (data: URI).
- Забагато граней: Файл model_url має розмір понад 100 МБ і містить понад 8 000 000 граней. Зменшіть кількість граней і надішліть файл знову.
- ASCII FBX понад 100 МБ: Файл model_url є ASCII FBX розміром понад 100 МБ. Надішліть його як бінарний FBX або GLB.
- Нечитабельний файл моделі: Файл model_url має розмір понад 100 МБ, і його заголовок не вдається прочитати, наприклад, GLB зі стисненням Draco або бінарний FBX старіший за 7.1.
- Заголовок моделі занадто складний: Файл model_url має розмір понад 100 МБ, і його заголовок містить забагато сіток, вузлів або записів для перевірки. Зменшіть кількість об'єктів у файлі та надішліть його знову.
- Недійсне вхідне завдання: 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 і за замовчуванням дорівнює 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
}