Превратите исходную фотографию в пригодный для 3D-печати медальон-брелок — рельеф
с глубиной в форме значка и с цветовой раскраской — в два этапа: prototype генерирует раскрашенное
концептуальное изображение из вашей входной фотографии, затем build превращает это концептуальное изображение
в рельефную 3D-модель. Два этапа связаны через input_task_id.
Сгенерируйте одно цветное концепт-изображение из исходной фотографии. Возвращаемый
ID задачи — это то, что нужно передать как input_task_id в эндпоинт
сборки. См.
Объект задачи прототипа брелока
для формата ответа.
Параметры
Name
image_url
Type
string
Обязательный
Description
Исходная фотография, которую Meshy должен раскрасить в концепт-изображение, готовое для брелока. Сейчас мы поддерживаем форматы .jpg, .jpeg, .png и .webp.
Есть два способа предоставить изображение:
Публично доступный URL: URL, доступный из публичного интернета.
Data URI: Data URI изображения в кодировке base64. Пример Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
name
Type
string
Description
Необязательное имя задачи для отображения. Максимум 100 символов.
Возвращает
Свойство result в ответе содержит id задачи новой задачи прототипа брелока. Опрашивайте эндпоинт Получить задачу или подпишитесь на поток, пока задача не достигнет SUCCEEDED, затем передайте этот ID в эндпоинт сборки как input_task_id.
Сценарии ошибок
Name
400 - Bad Request
Description
Запрос был неприемлемым. Распространенные причины:
Сгенерируйте финальный медальон брелока, пригодный для 3D-печати, из успешно выполненной
задачи прототипа. Сборка запускает конвейер рельефа на основе карты глубины для
раскрашенного концепт-изображения прототипа и отправляет один артефакт сетки в
запрошенном вами формате. См.
Объект задачи сборки брелока, чтобы узнать
форму ответа.
Параметры
Name
input_task_id
Type
string
Обязательный
Description
ID задачи прототипа, созданной через этот же эндпоинт OpenAPI. Прототип должен быть создан с тем же API-ключом, должен достичь SUCCEEDED и должен создать ровно одно изображение-кандидат.
Задачи прототипов, созданные через веб-приложение, не принимаются — эндпоинт сборки принимает только задачи прототипов, созданные с помощью POST /openapi/creative-lab/keychain/v1/prototype, и отклоняет любой другой источник с 404.
Name
name
Type
string
Description
Необязательное имя задачи для отображения. Максимум 100 символов.
options
Необязательные параметры настройки геометрии рельефа. У каждого поля есть разумное значение по умолчанию — отправляйте только те, которые хотите переопределить.
Низкочастотный порог для значений карты глубины; все, что ниже него, ограничивается нулем. Диапазон: [0, 1].
Name
remove_background
Type
boolean
по умолчанию true
Description
Автоматически удалить фон концепт-изображения прототипа перед созданием рельефа.
Name
export_resolution
Type
integer
по умолчанию 512
Description
Разрешение сетки, используемое для экспорта. Диапазон: [64, 2048].
output
Необязательный селектор формата передачи. По умолчанию используется glb.
Name
format
Type
string
по умолчанию glb
Description
Набор артефактов, возвращаемый сборкой. Доступные значения:
glb (по умолчанию) — возвращает один model.glb в model_urls.glb.
obj — упаковывает model.obj + model.mtl + texture.png в zip и возвращает набор в model_urls.obj.
zip — упаковывает в zip каждый артефакт, созданный генератором, и возвращает набор в model_urls.bundle_zip.
Возвращает
Свойство result в ответе содержит id задачи новой задачи сборки брелока. Опросите эндпоинт Получить задачу или подпишитесь на поток, пока задача не достигнет SUCCEEDED, затем скачайте артефакт из единственной записи в model_urls.
Режимы ошибок
Name
400 - Bad Request
Description
Запрос был неприемлемым. Распространенные причины:
Отсутствует параметр: input_task_id обязателен.
Недопустимый UUID: input_task_id не является допустимым UUID.
Родительская задача не выполнена успешно: указанная задача прототипа еще не достигла SUCCEEDED.
Нет кандидата: задача прототипа выполнена успешно, но не создала изображение-кандидат.
Параметры вне диапазона: одно из полей options вышло за пределы разрешенного диапазона или набора enum.
Name
401 - Unauthorized
Description
Аутентификация не удалась. Проверьте ваш API-ключ.
Name
402 - Payment Required
Description
Недостаточно кредитов для выполнения этой задачи.
Name
404 - Not Found
Description
Указанная задача прототипа не существует, принадлежит другому пользователю или была создана через веб-приложение (только задачи прототипов в API-mode могут связываться в сборку).
Получает задачу прототипа или сборки по действительному id задачи. Путь URL
должен соответствовать этапу задачи — задача сборки, полученная через
/prototype/:id, возвращает 404, и наоборот.
Отменяет задачу брелока. Если задача всё ещё находится в состоянии PENDING, кредиты,
израсходованные при создании, возвращаются. Задачи, которые уже находятся в состоянии
IN_PROGRESS, отменяются без возврата (воркер, возможно, уже
расходует ресурсы). Задачи, которые уже достигли конечного состояния
(SUCCEEDED, FAILED, CANCELED), не могут быть отменены.
Путь URL должен соответствовать этапу задачи — DELETE для
/prototype/:buildId возвращает 404.
Параметры пути
Name
id
Type
path
Description
Уникальный идентификатор задачи брелока, которую нужно отменить.
Возвращает
Возвращает 204 No Content при успешном выполнении с пустым телом.
Варианты сбоев
Name
400 - Bad Request
Description
Задача уже находится в конечном состоянии и не может быть отменена.
Name
404 - Not Found
Description
Задача не существует, принадлежит другому пользователю или её этап не соответствует пути URL.
Передавайте обновления задачи брелока в реальном времени через Server-Sent Events (SSE).
Путь URL должен соответствовать этапу задачи — открытие потока по
/prototype/:buildId/stream отправляет одну полезную нагрузку event: error с
status_code: 404 и закрывает поток.
Параметры
Name
id
Type
path
Description
Уникальный идентификатор задачи брелока для потоковой передачи.
Возвращаемое значение
Возвращает поток объектов задач прототипа брелока
или сборки брелока в виде
Server-Sent Events. Для задач PENDING или IN_PROGRESS поток ответа
будет включать только необходимые поля progress и status.
// Error event example (wrong stage or task not found)event: errordata: {"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: messagedata: {"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb","progress": 0,"status": "PENDING"}event: messagedata: {"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb","type": "creative-lab-keychain-build","status": "SUCCEEDED","progress": 100,"created_at": 1729123500000,"started_at": 1729123510000,"finished_at": 1729123535000,"expires_at": 1729382735000,"task_error": null,"consumed_credits": 20,"model_urls": {"glb":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***" }}
Получите пагинированный список ваших задач брелока для одного этапа. Путь
URL выбирает этап — /prototype возвращает задачи прототипа; /build
возвращает задачи сборки. Задачи другого этапа не включаются ни в один
ответ.
Параметры пути
Name
stage
Type
path
Обязательный
Description
Либо prototype, либо build. Коллекция возвращает только задачи,
этап которых соответствует URL — запрос /prototype никогда не возвращает
задачи сборки, и наоборот.
Параметры запроса
Name
page_num
Type
integer
по умолчанию 1
Description
Номер страницы для пагинации.
Name
page_size
Type
integer
по умолчанию 10
Description
Ограничение размера страницы. Максимально допустимое значение — 50 элементов.
Name
sort_by
Type
string
по умолчанию -created_at
Description
Поле для сортировки. Доступные значения:
+created_at: Сортировка по времени создания в порядке возрастания.
-created_at: Сортировка по времени создания в порядке убывания.
Объект задачи прототипа брелока — это рабочая единица, которую Meshy отслеживает для
генерации раскрашенного концептуального изображения из исходной фотографии. Вывод
этого этапа передается по цепочке в этап сборки
через input_task_id.
Свойства
Name
id
Type
string
Description
Уникальный идентификатор задачи. Хотя в качестве детали реализации для идентификаторов задач мы используем k-сортируемый UUID, вам не следует делать какие-либо предположения о формате id.
Name
type
Type
string
Description
Тип задачи. Значение — creative-lab-keychain-prototype.
Name
name
Type
string
Description
Имя задачи, указанное при ее создании. Пустая строка, если имя не было предоставлено.
Name
status
Type
string
Description
Статус задачи. Возможные значения: одно из PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
progress задачи. Если задача еще не запущена, это свойство будет равно 0. После успешного завершения задачи оно станет 100.
Name
created_at
Type
timestamp
Description
Временная метка создания задачи, в миллисекундах.
Временная метка представляет количество миллисекунд, прошедших с 1 января 1970 года UTC, в соответствии со
стандартом RFC 3339.
Например, пятница, 1 сентября 2023 г., 12:00:00 PM GMT представляется как 1693569600000. Это применяется
ко всем временным меткам в Meshy API.
Name
started_at
Type
timestamp
Description
Временная метка запуска задачи, в миллисекундах. Если задача еще не запущена, это свойство будет равно 0.
Name
finished_at
Type
timestamp
Description
Временная метка завершения задачи, в миллисекундах. Если задача еще не завершена, это свойство будет равно 0.
Name
expires_at
Type
timestamp
Description
Временная метка истечения срока действия результата задачи, в миллисекундах.
Name
preceding_tasks
Type
integer
Description
Количество предшествующих задач.
Значение этого поля имеет смысл только если статус задачи — PENDING.
Name
task_error
Type
object
Description
Сведения об ошибке для неудачных задач. См. Ошибки для полной справки по объекту task_error.
Name
consumed_credits
Type
integer
Description
Количество кредитов, израсходованных этой задачей. Присутствует, когда статус задачи — PENDING, IN_PROGRESS или SUCCEEDED. Возвращает 0 для задач FAILED (кредиты возвращаются при сбое).
Name
image_urls
Type
array of strings
Description
Загружаемые URL для вариантов концепт-изображения, сгенерированных этой задачей прототипа. В настоящее время API всегда возвращает ровно один вариант; поле является массивом, чтобы в будущих версиях можно было предоставлять несколько вариантов без критического изменения.
Объект задачи сборки брелока — это рабочая единица, которую Meshy отслеживает для
генерации финальной 3D-сетки брелока из задачи прототипа со статусом SUCCEEDED. Сборка
запускает конвейер рельефа на основе карты глубины для концептуального изображения прототипа и
публикует единый артефакт сетки в формате, запрошенном вызывающей стороной.
Свойства
Name
id
Type
string
Description
Уникальный идентификатор задачи.
Name
type
Type
string
Description
Тип задачи. Значение — creative-lab-keychain-build.
Name
name
Type
string
Description
Имя задачи, указанное при создании задачи. Пустая строка, если имя не было указано.
Name
status
Type
string
Description
Статус задачи. Возможные значения: одно из PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
progress задачи. Если задача еще не запущена, это свойство будет 0. После успешного завершения задачи оно станет 100.
Name
created_at
Type
timestamp
Description
Временная метка создания задачи, в миллисекундах.
Name
started_at
Type
timestamp
Description
Временная метка запуска задачи, в миллисекундах.
Name
finished_at
Type
timestamp
Description
Временная метка завершения задачи, в миллисекундах.
Name
expires_at
Type
timestamp
Description
Временная метка истечения срока действия результата задачи, в миллисекундах.
Name
preceding_tasks
Type
integer
Description
Количество предшествующих задач. Имеет значение только когда статус — PENDING.
Name
task_error
Type
object
Description
Сведения об ошибке для неудачно завершенных задач. См. Ошибки для полного справочника по объекту task_error.
Name
consumed_credits
Type
integer
Description
Количество кредитов, израсходованных этой задачей. Возвращает 0 для задач со статусом FAILED (кредиты возвращаются при сбое).
Name
model_urls
Type
object
Description
Загружаемые URL для сгенерированного артефакта, сгруппированные по имени артефакта. Всегда содержит ровно одну запись — формат, запрошенный через output.format в запросе на сборку. Ключ соответствует запрошенному формату:
Name
glb
Type
string
Description
Загружаемый URL к файлу GLB. Присутствует, когда output.format был glb (по умолчанию).
Name
obj
Type
string
Description
Загружаемый URL к zip-пакету, содержащему model.obj, model.mtl и texture.png. Присутствует, когда output.format был obj.
Name
bundle_zip
Type
string
Description
Загружаемый URL к zip-пакету со всеми артефактами, которые генерирует генератор. Присутствует, когда output.format был zip.