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
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
Идентификатор задачи многоцветной 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 для идентификаторов задач как деталь реализации, вам не следует делать какие-либо предположения о формате идентификатора.
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
}