lowpoly будет отключён 30 окт. 2026 г.. Перейдите на другую модель до этих дат, чтобы избежать ошибок в запросах. Все устаревшие функции

API многоцветной печати

Конвертируйте 3D-модель в многоцветный файл 3MF для 3D-печати. Выберите палитру из до 16 цветов и пресет слайсера для вашего бренда принтера.

POST/openapi/v1/print/multi-color

Создать задачу Multi-Color Print

Создаёт задачу Multi-Color Print, которая конвертирует 3D-модель в многоцветный файл 3MF для 3D-печати. Задача выполняется в фоновом режиме. О том, сколько обычно занимает выполнение задачи, см. Время обработки.

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"
}

Параметры

  • Name
    input_task_id
    Type
    string
    Обязательный
    Description

    Обязателен, если не отправлен model_url. ID задачи, модель которой вы хотите напечатать, например задачи Изображение в 3D, Мульти-изображение в 3D, Текст в 3D, Ремешинг или Ретекстурирование. Задача должна быть создана вами через API и иметь статус SUCCEEDED.

    Multi-Color Print считывает файл GLB задачи, который может содержать не более 8 000 000 граней. Если в модели граней больше, возвращается 400. В этом случае сначала запустите задачу Ремешинг для неё и отправьте ID задачи Ремешинга вместо исходного.

  • Name
    model_url
    Type
    string
    Обязательный
    Description

    Обязателен, если не отправлен input_task_id. Модель для печати, в виде публичного URL или data URI. Если отправлены оба параметра, Meshy использует input_task_id.

    URL с http или https должен указывать на файл .glb или .fbx размером не более 400 МБ. Data URI должен содержать GLB-файл в base64 размером не более 100 МБ. Используйте data:model/gltf-binary;base64,. Файл .fbx отправляйте как URL с http или https.

    Файл размером более 100 МБ также должен соответствовать следующим правилам:

    • В нём должно быть не более 8 000 000 граней. Meshy считает грани как треугольники, поэтому четырёхугольник считается за 2, а сетка, нарисованная несколько раз, считается один раз за каждую копию.
    • Файл FBX должен быть бинарным FBX версии 7.1 или новее.
    • Файл GLB не должен использовать сжатие Draco.
  • Name
    max_colors
    Type
    integer
    по умолчанию 4
    Description

    Максимальное число цветов в выходной палитре, от 1 до 16. Чтобы использовать значение по умолчанию, не указывайте параметр вместо отправки 0.

  • Name
    style
    Type
    string
    по умолчанию realistic
    Description

    Цветовой стиль файла 3MF.

    Доступные значения:

    • realistic: берёт цвета напрямую из текстуры модели для тонкой, фотореалистичной детализации, при этом создаётся файл большего размера.
    • cartoon: сводит цвета в чистые, однородные области для стилизованного вида, при этом создаётся файл меньшего размера.

    У модели должен быть цвет. Для realistic нужна единая базовая цветовая текстура с UV-развёрткой на каждой части сетки, а cartoon также принимает цвета вершин. Meshy отклоняет нетекстурированную (белую) модель. См. model_missing_texture.

  • Name
    max_depth
    Type
    integer
    по умолчанию 4
    Description

    Глубина подразделения, которую Meshy использует для наложения цветов текстуры на сетку, от 3 до 6. 0 равнозначно отсутствию параметра. Более высокие значения захватывают более тонкие цветовые детали и создают файл большего размера. Используется только для стиля realistic, стиль cartoon его игнорирует.

  • Name
    printer_brand
    Type
    string
    по умолчанию bambu
    Description

    Бренд принтера, пресет слайсера которого Meshy записывает в файл 3MF. Затем файл открывается в слайсере этого бренда с соответствующим профилем принтера, филамента и процесса. Пресет использует принтер этого бренда по умолчанию с соплом 0,4 мм.

    Доступные значения:

    • bambu
    • anycubic
    • creality
    • elegoo
    • flashforge
    • prusa
    • qidi
    • snapmaker
    • ankermake

    Любое другое значение возвращает 400.

Возвращаемое значение

Поле result в ответе содержит ID новой задачи Multi-Color Print.

Варианты сбоя

  • Name
    400 - Bad Request
    Description

    Запрос не может быть выполнен. Сообщение об ошибке указывает, какая именно проблема обнаружена. Например:

    • Отсутствует параметр: не отправлены ни model_url, ни input_task_id.
    • Неверный формат модели: файл model_url не является файлом .glb или .fbx.
    • Недоступный URL: Meshy не может скачать файл по model_url.
    • Файл модели слишком большой: файл model_url превышает 400 МБ при URL с http или https, либо превышает 100 МБ как data URI.
    • Слишком много граней: файл model_url превышает 100 МБ и содержит более 8 000 000 граней. Уменьшите число граней и отправьте файл снова.
    • ASCII FBX более 100 МБ: файл model_url — это ASCII FBX размером более 100 МБ. Отправьте его как бинарный FBX или GLB.
    • Нечитаемый файл модели: файл model_url превышает 100 МБ, и Meshy не может прочитать его заголовок. Например, это GLB со сжатием Draco или бинарный FBX старше версии 7.1.
    • Заголовок модели слишком сложный: файл model_url превышает 100 МБ, и в его заголовке слишком много сеток, узлов или записей для проверки. Уменьшите число объектов в файле и отправьте его снова.
    • Неверная входная задача: input_task_id не является успешно выполненной задачей.
    • Слишком много граней во входной задаче: модель input_task_id содержит более 8 000 000 граней. Запустите для неё задачу Ремешинга, а затем отправьте ID задачи Ремешинга вместо исходного.
    • Неверный max_colors: max_colors отрицателен или превышает 16.
    • Неверный style: style не равен realistic или cartoon.
    • Неверный max_depth: max_depth выходит за пределы диапазона 3–6 и не равен 0.
    • Неверный printer_brand: printer_brand не входит в число доступных значений.
    • Нет источника цвета: у модели отсутствует цвет, необходимый для style. Для realistic нужна единая базовая цветовая текстура с UV-развёрткой на каждой части сетки. cartoon принимает базовую цветовую текстуру или цвета вершин. Сначала затекстурируйте модель или используйте cartoon для модели с цветами вершин. Meshy проверяет загруженный .fbx только после нормализации задачи, поэтому задача завершится сбоем с ошибкой model_missing_texture.

    Исправьте запрос и отправьте его снова. См. Ошибки.

  • Name
    401 - Unauthorized
    Description

    API-ключ отсутствует или недействителен. Проверьте заголовок Authorization.

  • Name
    402 - Payment Required
    Description

    Например:

    • Недостаточно кредитов: на аккаунте недостаточно кредитов для выполнения этой задачи, либо аккаунт достиг лимита кредитов. Проверьте баланс кредитов и повторите попытку.
    • Бесплатный план: для создания задачи требуется платный план. Обновите свой план в настройках подписки и повторите попытку.
  • Name
    403 - Forbidden
    Description

    input_task_id указывает на модель с барельефом, которую этот эндпоинт не может напечатать. Сообщение: This model type does not support this operation. Отправьте другую модель.

  • Name
    404 - Not Found
    Description

    input_task_id не соответствует ни одной из ваших задач. Проверьте ID задачи и отправьте запрос снова.

  • Name
    429 - Too Many Requests
    Description

    Вы превысили ограничение частоты запросов. Подождите и повторите попытку. См. Ограничения частоты.

GET/openapi/v1/print/multi-color/:id

Получить задачу многоцветной печати

Возвращает задачу многоцветной печати по её ID.

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,
  "expires_at": 1700259201000,
  "task_error": null,
"consumed_credits": 10
}

Параметры

  • Name
    id
    Type
    path
    Description

    ID задачи из ответа на создание.

Возвращает

Объект задачи многоцветной печати.

DELETE/openapi/v1/print/multi-color/:id

Удалить задачу многоцветной печати

Безвозвратно удаляет задачу многоцветной печати, включая её модели и данные. Отменить удаление нельзя.

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 keeps 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."
}

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

  • Name
    id
    Type
    path
    Description

    Идентификатор задачи, которую нужно удалить.

Статус задачи

Удаление задачи со статусом PENDING возвращает кредиты, потраченные при её создании.

Задачу со статусом IN_PROGRESS удалить нельзя. Запрос вернёт 409 Conflict, а задача продолжит выполняться. Meshy не возвращает кредиты за задачу, которая уже началась, поэтому её удаление обойдётся вам как в кредиты, так и в результат. Дождитесь, пока она перейдёт в статус SUCCEEDED, FAILED или CANCELED, и только потом удаляйте её.

Удаление задачи в финальном статусе (SUCCEEDED, FAILED или CANCELED) не возвращает кредиты.

Возвращает

200 OK, когда задача удалена, или 409 Conflict, когда задача имеет статус IN_PROGRESS.

GET/openapi/v1/print/multi-color

Список задач многоцветной печати

Возвращает список ваших задач многоцветной печати.

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,
    "expires_at": 1700259201000,
    "task_error": null,
  "consumed_credits": 10
  }
]

Параметры

  • Name
    page_num
    Type
    integer
    по умолчанию 1
    Description

    Номер страницы для возврата. Нумерация страниц начинается с 1.

  • Name
    page_size
    Type
    integer
    по умолчанию 10
    Description

    Количество задач на странице, до 100.

  • Name
    sort_by
    Type
    string
    Description

    Порядок сортировки.

    Доступные значения:

    • +created_at: сначала старые
    • -created_at: сначала новые

Возвращает

Постраничный список объектов задач многоцветной печати.

GET/openapi/v1/print/multi-color/:id/stream

Поток обновлений задачи многоцветной печати

Передаёт обновления задачи многоцветной печати в виде потока Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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,
  "expires_at": 1700259201000,
  "task_error": null,
"consumed_credits": 10
}

Параметры

  • Name
    id
    Type
    path
    Description

    ID задачи из ответа на создание.

Возвращает

Поток объектов задачи многоцветной печати в виде Server-Sent Events.

Каждое событие содержит полный объект задачи, в том же виде, в каком его возвращает эндпоинт получения. Пока задача находится в статусе PENDING или IN_PROGRESS, поля результата ещё не имеют значений.

Объект задачи многоцветной печати

Объект задачи многоцветной печати описывает одно преобразование 3D-модели в многоцветный файл 3MF. Он содержит статус, progress и файл 3MF, когда задача завершается успешно.

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,
  "expires_at": 1700259201000,
  "task_error": null,
"consumed_credits": 10
}
  • Name
    id
    Type
    string
    Description

    ID задачи. Рассматривайте его как непрозрачную строку и не полагайтесь на её формат.

  • Name
    type
    Type
    string
    Description

    Тип задачи, всегда print-multi-color.

  • Name
    model_urls
    Type
    object
    Description

    Ссылки для скачивания напечатанной модели, по одной на каждый формат файла. Для формата, который задача не сгенерировала, ключ отсутствует, а не содержит пустую строку.

    • Name
      3mf
      Type
      string
      Description

      Многоцветный файл 3MF.

  • Name
    progress
    Type
    integer
    Description

    Насколько выполнена задача, в процентах. Значение равно 0, пока задача не началась, и 100, когда она завершается успешно.

  • Name
    status
    Type
    string
    Description

    Статус задачи, один из PENDING, IN_PROGRESS, SUCCEEDED, FAILED или CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Количество задач перед этой в очереди. Значение имеет смысл только пока задача находится в статусе PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Время создания задачи, в миллисекундах Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Время начала задачи, в миллисекундах Unix. Значение равно 0, пока задача не началась.

  • Name
    finished_at
    Type
    timestamp
    Description

    Время завершения задачи, в миллисекундах Unix. Значение равно 0, пока задача не завершится.

  • Name
    expires_at
    Type
    timestamp
    Description

    Время истечения срока действия результата задачи, в миллисекундах Unix. Значение равно 0, пока задача не завершится.

  • Name
    task_error
    Type
    object
    Description

    Детали ошибки, если задача завершилась неудачно. См. Ошибки.

  • Name
    consumed_credits
    Type
    integer
    Description

    Количество кредитов, использованных задачей. Присутствует, когда статус — PENDING, IN_PROGRESS или SUCCEEDED. Для задачи со статусом FAILED значение равно 0, так как Meshy возвращает кредиты, если задача завершилась неудачно.