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
ID успішно виконаного завдання, яке використовується як вхідні дані. Підтримувані типи завдань: Зображення у 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.

Повернені дані

Властивість result у відповіді містить id новоствореного завдання 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.
- Недійсний стиль: Значення повинно бути realistic або cartoon.
- Відсутнє джерело кольору: Вхідна модель не має базової кольорової текстури (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 multi-color 3MF for printing
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
  }'

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
}