Преобразуйте исходное фото в коллекционную 3D минифигурку в стиле кирпичиков в два этапа:
прототип генерирует стилизованное концептуальное изображение из вашего входного фото, затем
сборка превращает это концептуальное изображение в 3D модель с текстурой. Два этапа
связаны через input_task_id.
POST /openapi/creative-lab/brick-figure/v1/prototype
Создайте одно изображение концепции в стиле кирпичиков из исходного фото. Возвращаемый идентификатор задачи — это то, что вы передаете как input_task_id в эндпоинт сборки. Обратитесь к Объект задачи прототипа фигурки из кирпичиков для формы ответа.
Параметры
Name
image_url
Type
string
Обязательный
Description
Исходное фото для стилизации Meshy в виде минифигурки из кирпичиков. В настоящее время мы поддерживаем форматы .jpg, .jpeg, .png и .webp.
Существует два способа предоставления изображения:
Публично доступный URL: URL, доступный из публичного интернета.
Data URI: Данные URI изображения, закодированные в base64. Пример Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
name
Type
string
Description
Необязательное имя задачи для отображения. Максимум 100 символов.
Name
remove_background
Type
boolean
по умолчанию false
Description
Если установлено значение true, прототип изображения возвращается в виде прозрачного RGBA PNG с удаленным фоном, чтобы вы могли наложить объект на любой фон.
Возвращает
Свойство result ответа содержит идентификатор задачи id вновь созданной задачи прототипа фигурки из кирпичиков. Опросите эндпоинт Получить задачу или подпишитесь на поток до тех пор, пока задача не достигнет состояния SUCCEEDED, затем передайте этот идентификатор в эндпоинт сборки как input_task_id.
Генерация финальной 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
Вы превысили ваше ограничение частоты.
Запрос
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
Уникальный идентификатор задачи фигурки из кирпичиков для потоковой передачи.
Возвращает
Возвращает поток объектов задач Прототип фигурки из кирпичиков
или Сборка фигурки из кирпичиков в виде
Server-Sent Events. Для задач со статусом PENDING или IN_PROGRESS поток ответа
будет включать только необходимые поля progress и status.
Получите пагинированный список ваших задач по фигуркам из кирпичиков для одного этапа. Путь 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
Уникальный идентификатор задачи. Хотя мы используем UUID, сортируемый по k, для идентификаторов задач как деталь реализации, вы не должны делать никаких предположений о формате 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
Скачиваемые URL-адреса для сгенерированной 3D модели. Создание фигурки из кирпичиков выдает текстурированный GLB плюс пару OBJ + MTL для конвейеров, предпочитающих Wavefront OBJ. Форма поля соответствует объекту Image to 3D model_urls, чтобы будущие добавления форматов не приводили к нарушению совместимости.