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

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

POST/openapi/v1/print/multi-color

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

Цей endpoint створює нове завдання для багатоколірного 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: Згладжує кольори в чисті, однорідні області для стилізованого вигляду. Створює менший файл.

Повертає

Властивість 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.
Name
401 - Unauthorized
Description
Автентифікація не вдалася. Будь ласка, перевірте ваш API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
429 - Too Many Requests
Description
Ви перевищили своє обмеження частоти.

Запит

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

Відповідь

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

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

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

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

Параметри

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

Повертає

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

Запит

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

Відповідь

{
  "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-друк

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

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

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

Повертає

Повертає 200 OK у разі успіху.

Запит

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

Відповідь

// Returns 200 Ok on success.

GET/openapi/v1/print/multi-color

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

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

Параметри

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

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

Повертає

Повертає список з пагінацією Об'єктів завдань на 3D-друк.

Запит

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

Відповідь

[
  {
    "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.

Запит

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

Потік відповіді

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