Превратите исходное фото в коллекционную 3D-минифигурку в кирпичном стиле в два этапа:
прототип создаёт стилизованное концептуальное изображение на основе вашего исходного фото, а затем
сборка превращает это концептуальное изображение в текстурированную 3D-модель. Два этапа
связаны через input_task_id.
POST /openapi/creative-lab/brick-figure/v1/prototype
Генерирует единое концептуальное изображение в стиле кирпичиков на основе исходной фотографии. Возвращённый ID задачи передаётся в качестве input_task_id в эндпоинт сборки. Формат ответа описан в разделе
Объект задачи прототипа фигурки из кирпичиков.
Параметры
Name
image_url
Type
string
Обязательный
Description
Исходная фотография, которую Meshy стилизует в виде миниатюрной фигурки из кирпичиков. В настоящее время поддерживаются форматы .jpg, .jpeg, .png и .webp.
Есть два способа предоставить изображение:
Общедоступный URL: URL, доступный из публичного интернета.
Data URI: base64-кодированный data URI изображения. Пример data URI: data:image/jpeg;base64,<ваши base64-кодированные данные изображения>.
Name
name
Type
string
Description
Необязательное имя задачи для отображения. Максимум 100 символов.
Name
remove_background
Type
boolean
по умолчанию false
Description
Если установлено значение true, изображение прототипа возвращается в виде прозрачного PNG формата RGBA с удалённым фоном, что позволяет размещать объект на любом фоне.
Возвращаемое значение
Свойство result ответа содержит id задачи только что созданного прототипа фигурки из кирпичиков. Опрашивайте эндпоинт Получение задачи или подпишитесь на поток до тех пор, пока задача не достигнет статуса SUCCEEDED, а затем передайте этот ID в эндпоинт сборки в качестве input_task_id.
Режимы сбоя
Name
400 - Bad Request
Description
Запрос был некорректным. Распространённые причины:
Размеры изображения вне допустимого диапазона: изображение слишком маленькое, превышает максимальный размер файла или максимальное количество пикселей.
Недоступный URL: не удалось загрузить image_url (404 или timeout).
Неверный Data URI: строка base64 сформирована некорректно.
Контент помечен: входное изображение было помечено системой NSFW moderation.
Name
401 - Unauthorized
Description
Ошибка аутентификации. Пожалуйста, проверьте свой API-ключ.
Name
402 - Payment Required
Description
Недостаточно кредитов для выполнения этой задачи.
Name
403 - Forbidden
Description
Входное изображение было помечено как нарушающее права интеллектуальной собственности.
Name
429 - Too Many Requests
Description
Вы превысили ограничение частоты запросов.
Request
POST
/openapi/creative-lab/brick-figure/v1/prototype
# Stage 1: generate a brick-style concept imagecurlhttps://api.meshy.ai/openapi/creative-lab/brick-figure/v1/prototype \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "image_url": "<your publicly accessible image url or base64-encoded data URI>" }'
Генерирует финальную текстурированную 3D-фигурку из кирпичиков на основе успешно завершённой задачи прототипа. Сборка выполняется по тому же пайплайну «изображение в 3D», что и
Изображение в 3D, поэтому формат объекта ответа и список URL-адресов результатов полностью совпадают. Форма ответа описана в разделе
Объект задачи сборки фигурки из кирпичиков.
Параметры
Name
input_task_id
Type
string
Обязательный
Description
Идентификатор задачи прототипа, созданной через этот же эндпоинт OpenAPI. Прототип должен быть создан с тем же API-ключом, должен достичь статуса SUCCEEDED и должен был сформировать ровно одно изображение-кандидат.
Задачи прототипа, созданные через веб-приложение, не принимаются — эндпоинт сборки принимает только задачи прототипа, созданные через POST /openapi/creative-lab/brick-figure/v1/prototype, и отклоняет любой другой источник с кодом 404.
Name
name
Type
string
Description
Необязательное название задачи для отображения. Максимум 100 символов.
Возвращаемое значение
Свойство result в ответе содержит id задачи вновь созданной сборки фигурки из кирпичиков. Опрашивайте эндпоинт Получение задачи или подпишитесь на поток, пока задача не достигнет статуса SUCCEEDED, после чего скачайте текстурированный GLB из model_urls.glb (или пару OBJ + MTL из model_urls.obj и model_urls.mtl, если ваш последующий пайплайн предпочитает OBJ).
Режимы сбоя
Name
400 - Bad Request
Description
Запрос не может быть обработан. Распространённые причины:
Отсутствует параметр: требуется input_task_id.
Недопустимый UUID: значение input_task_id не является допустимым UUID.
Родительская задача не завершена успешно: указанная задача прототипа ещё не достигла статуса SUCCEEDED.
Нет кандидата: задача прототипа завершилась успешно, но не сформировала изображение-кандидат.
Name
401 - Unauthorized
Description
Ошибка аутентификации. Проверьте свой API-ключ.
Name
402 - Payment Required
Description
Недостаточно кредитов для выполнения этой задачи.
Name
404 - Not Found
Description
Указанная задача прототипа не существует, принадлежит другому пользователю или была создана через веб-приложение (в сборку можно связать только задачи прототипа, созданные в режиме API).
Name
429 - Too Many Requests
Description
Превышено ограничение частоты.
Request
POST
/openapi/creative-lab/brick-figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurlhttps://api.meshy.ai/openapi/creative-lab/brick-figure/v1/build \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578" }'
Получите задачу прототипа или сборки по действительному 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
Уникальный идентификатор задачи фигурки из кирпичиков для стриминга.
Возвращает
Возвращает поток объектов задач Brick Figure Prototype
или Brick Figure Build в виде
Server-Sent Events. Каждый кадр содержит полный объект задачи для данного этапа — в том же формате, что возвращает
эндпоинт Get, — поэтому пока задача находится в статусе PENDING или IN_PROGRESS,
выходные поля просто ещё не заполнены (null, [] или {}), а
finished_at равно null.
Получите постраничный список ваших задач по созданию фигурок из кирпичиков для одного этапа. Путь 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
Ограничение размера страницы. Максимально допустимое значение — 100 элементов.
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-brick-figure-prototype.
Name
name
Type
string
Description
Название задачи, указанное при её создании. Пустая строка, если название не было указано.
Name
status
Type
string
Description
Статус задачи. Возможные значения: одно из PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Прогресс выполнения задачи. Если задача ещё не начата, это свойство будет равно 0. Как только задача успешно завершится, оно станет равным 100.
Name
created_at
Type
timestamp
Description
Временная метка создания задачи, в миллисекундах.
Временная метка представляет собой количество миллисекунд, прошедших с 1 января 1970 года UTC, в соответствии со
стандартом RFC 3339.
Например, пятница, 1 сентября 2023 года, 12:00:00 по Гринвичу представлена как 1693569600000. Это относится
ко всем временным меткам в Meshy API.
Name
started_at
Type
timestamp
Description
Временная метка начала выполнения задачи, в миллисекундах. Если задача ещё не начата, это свойство будет равно null.
Name
finished_at
Type
timestamp
Description
Временная метка завершения задачи, в миллисекундах. Если задача ещё не завершена, это свойство будет равно null.
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-кирпичной фигурки на основе успешно завершённой задачи прототипа. Она
использует тот же конвейер изображение-в-3D, что и Изображение в 3D,
поэтому выходные поля повторяют объект задачи этого эндпоинта.
Свойства
Name
id
Type
string
Description
Уникальный идентификатор задачи.
Name
type
Type
string
Description
Тип задачи. Значение — creative-lab-brick-figure-build.
Name
name
Type
string
Description
Название задачи, указанное при её создании. Пустая строка, если название не было указано.
Name
status
Type
string
Description
Статус задачи. Возможные значения: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Прогресс выполнения задачи. Если задача ещё не запущена, это свойство будет равно 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
prompt
Type
string
Description
Всегда пусто для сборки кирпичной фигурки. Присутствует для совместимости между эндпоинтами с общей структурой V2ImageTo3DTaskResponse, используемой в Изображение в 3D.
Name
negative_prompt
Type
string
Description
Всегда пусто для сборки кирпичной фигурки. Присутствует для совместимости между эндпоинтами.
Name
texture_prompt
Type
string
Description
Всегда пусто для сборки кирпичной фигурки. Присутствует для совместимости между эндпоинтами.
Name
texture_image_url
Type
string
Description
Всегда пусто для сборки кирпичной фигурки. Присутствует для совместимости между эндпоинтами.
Name
model_urls
Type
object
Description
Ссылки для скачивания сгенерированной 3D-модели. Сборка кирпичной фигурки создаёт текстурированный GLB, а также пару OBJ + MTL для конвейеров, предпочитающих формат Wavefront OBJ. Структура поля соответствует объекту model_urls из Изображение в 3D, поэтому добавление новых форматов в будущем не нарушит совместимость.
Name
glb
Type
string
Description
Ссылка для скачивания текстурированного файла GLB.
Name
obj
Type
string
Description
Ссылка для скачивания файла Wavefront OBJ (геометрия + UV).
Name
mtl
Type
string
Description
Ссылка для скачивания сопутствующего файла материала MTL для OBJ. Используется в паре с obj и записью из texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
Ссылка для скачивания миниатюры файла модели.
Name
texture_urls
Type
array
Description
Массив объектов ссылок на текстуры, сгенерированных этой задачей. В настоящее время содержит один объект с картой базового цвета.
Name
base_color
Type
string
Description
Ссылка для скачивания изображения карты базового цвета.