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, Ремеш, and Ретекстурування. Завдання повинно мати статус SUCCEEDED.

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

Name
max_colors
Type
integer
за замовчуванням 4
Description
Максимальна кількість кольорів у вихідній палітрі.
Допустимий діапазон: від 1 до 16.
Name
max_depth
Type
integer
за замовчуванням 4
Description
Глибина квадродерева для точності кольору. Вищі значення створюють точніші межі кольорів, але збільшують розмір файлу.
Допустимий діапазон: від 3 до 6.

Повертає

Властивість 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.
- Недійсний max_depth: Значення має бути між 3 і 6.
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,
    "max_depth": 5
  }'

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-друку, яке потрібно видалити.

Повертає

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

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

// Returns 200 Ok on success.

GET/openapi/v1/print/multi-color

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

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

Параметри

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

Name
page_num
Type
integer
Description
Номер сторінки для пагінації. Починається з 1 і за замовчуванням дорівнює 1.
Name
page_size
Type
integer
Description
Обмеження розміру сторінки. За замовчуванням — 10 елементів. Максимально дозволено 50 елементів.
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
progress завдання. Якщо завдання ще не розпочато, ця властивість буде 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
}