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: Преобразует цвета в чистые, однородные области для стилизованного вида. Создает меньший файл.

Возвращает

Свойство 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 печать с несколькими цветами

Этот эндпоинт навсегда удаляет задачу на 3D печать с несколькими цветами, включая все связанные модели и данные. Это действие необратимо.

Параметры пути

Name
id
Type
path
Description
ID задачи на 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-печать

Этот эндпоинт позволяет получить список задач на многоцветную 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
}