Преобразуйте исходное фото в коллекционную 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: Базовый64-кодированный Data URI изображения. Пример Data URI: data:image/jpeg;base64,<ваши данные изображения в формате base64>.
Name
name
Type
string
Description
Необязательное имя задачи для отображения. Максимум 100 символов.
Возвращаемые значения
Свойство result ответа содержит идентификатор задачи id вновь созданной задачи прототипирования фигурки из кирпичиков. Опросите Получить задачу эндпоинт или подпишитесь на поток до тех пор, пока задача не достигнет состояния SUCCEEDED, затем передайте этот ID в эндпоинт сборки как input_task_id.
Режимы отказа
Name
400 - Bad Request
Description
Запрос был неприемлемым. Общие причины:
Отсутствует параметр: image_url требуется.
Неверный формат изображения: Предоставленный image_url не является поддерживаемым форматом (.jpg, .jpeg, .png, .webp).
Размер изображения вне диапазона: Изображение слишком маленькое, превышает максимальный размер файла или количество пикселей.
Недоступный URL: image_url не удалось загрузить (404 или timeout).
Неверный Data URI: Строка base64 неправильно сформирована.
Контент помечен: Входное изображение было отмечено модерацией как NSFW или нарушающее интеллектуальную собственность.
Name
401 - Unauthorized
Description
Аутентификация не удалась. Пожалуйста, проверьте ваш API-ключ.
Name
402 - Payment Required
Description
Недостаточно кредитов для выполнения этой задачи.
Name
403 - Forbidden
Description
Входное изображение было помечено за нарушение прав интеллектуальной собственности.
Name
429 - Too Many Requests
Description
Вы превысили свое ограничение частоты.
Запрос
POST
/openapi/creative-lab/brick-figure/v1/prototype
# Stage 1: generate a brick-style concept imagecurl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/prototype \ -X POST \ -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 фигурку из кирпичиков с текстурой на основе успешной задачи прототипа. Сборка использует ту же самую pipeline конвертации изображения в 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
# Шаг 2: сборка из успешной задачи прототипаcurl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/build \ -X POST \ -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.
// Пример события ошибки (неправильная стадия или задача не найдена)event: errordata: {"status_code": 404,"message": "Task not found"}// Примеры события сообщения иллюстрируют ход задачи.// Для задач со статусами PENDING или IN_PROGRESS поток ответов не будет включать все поля.event: messagedata: {"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb","progress": 0,"status": "PENDING"}event: messagedata: {"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb","type": "creative-lab-brick-figure-build","status": "SUCCEEDED","progress": 100,"created_at": 1729123500000,"started_at": 1729123510000,"finished_at": 1729123535000,"expires_at": 1729382735000,"task_error": null,"consumed_credits": 30,"prompt": "","negative_prompt": "","texture_prompt": "","texture_image_url": "","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***","obj":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***" },"thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?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
Лимит размера страницы. Максимально допустимое значение — 100
элементов.
Name
sort_by
Type
string
по умолчанию -created_at
Description
Поле для сортировки. Доступные значения:
+created_at: Сортировать по времени создания в порядке
возрастания.
-created_at: Сортировать по времени создания в порядке
убывания.
# Список задач прототипаcurl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/prototype?page_size=10 \ -H "Authorization: Bearer ${YOUR_API_KEY}"# Список задач сборкиcurl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/build?page_size=10 \ -H "Authorization: Bearer ${YOUR_API_KEY}"
Объект задачи прототипа фигурки из кирпича — это единица работы, которую Meshy отслеживает для генерации концептуального изображения в стиле кирпича из исходной фотографии. Выходные данные этого этапа соединяются с этапом сборки через input_task_id.
Свойства
Name
id
Type
string
Description
Уникальный идентификатор задачи. Мы используем k-сортируемый UUID для идентификаторов задач как деталь реализации, однако вы не должны делать никаких предположений о формате идентификатора.
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,
поэтому выходные поля отражают объект задачи этого эндпоинта task object.
Свойства
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. Форма поля соответствует объекту Изображение в 3D model_urls, чтобы будущие дополнения формата встраивались без ломки изменений.
Name
glb
Type
string
Description
Скачиваемый URL для текстурированного GLB файла.
Name
obj
Type
string
Description
Скачиваемый URL для Wavefront OBJ файла (геометрия + UV).
Name
mtl
Type
string
Description
Скачиваемый URL для сопровождающего OBJ файла MTL материала. Парируются с obj и входом из texture_urls[0].base_color.
Name
thumbnail_url
Type
string
Description
Скачиваемый URL для изображения миниатюры файла модели.
Name
texture_urls
Type
array
Description
Массив объектов URL текстур, сгенерированных этой задачей. В настоящее время содержит единственный объект с картой базового цвета.
Name
base_color
Type
string
Description
Скачиваемый URL для изображения карты базового цвета.