Multi-Color Print 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 модели в формате .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 также допускает цвета по вершинам (vertex colors). Модели без текстуры (белые) отклоняются — см. 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, которое также используется по умолчанию.
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
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
}