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.
- Недопустимое значение style: Значение должно быть 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 и по умолчанию равен 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
Скачиваемая ссылка на файл 3D-модели, сгенерированный Meshy. Свойство для формата будет отсутствовать, если формат не был сгенерирован, вместо возврата пустой строки.
- Name
  3mf
  Type
  string
  Description
  Скачиваемая ссылка на многоцветный файл 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
}