Превратите исходное фото в коллекционную 3D-фигурку в стиле чиби в два этапа:
прототип создаёт стилизованное концептуальное изображение на основе вашего исходного фото, а затем
сборка превращает это концептуальное изображение в текстурированную 3D-модель. Эти два этапа
связаны между собой через input_task_id.
Сгенерируйте одно концептуальное изображение в стиле чиби из исходного фото. Возвращённый ID задачи — это то, что вы передаёте как input_task_id в эндпоинт сборки. Обратитесь к разделу
The Figure Prototype Task Object
для описания формата ответа.
Параметры
Name
image_url
Type
string
Обязательный
Description
Исходное фото, которое Meshy стилизует под фигурку в стиле чиби. В настоящее время поддерживаются форматы .jpg, .jpeg, .png и .webp.
Есть два способа предоставить изображение:
Общедоступный URL: URL, доступный из публичного интернета.
Data URI: изображение, закодированное в base64 в виде data URI. Пример 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 задачи только что созданного прототипа фигурки. Опрашивайте эндпоинт Get a Task или подпишитесь на stream, пока задача не достигнет статуса SUCCEEDED, а затем передайте этот ID в эндпоинт сборки в качестве input_task_id.
Размеры изображения вне допустимого диапазона: изображение слишком мало, превышает максимальный размер файла или превышает максимальное количество пикселей.
Недоступный URL: не удалось загрузить image_url (404 или timeout).
Недопустимый Data URI: строка base64 некорректна.
Контент помечен: входное изображение было помечено при moderation на NSFW или на нарушение интеллектуальной собственности.
Name
401 - Unauthorized
Description
Ошибка аутентификации. Пожалуйста, проверьте свой API-ключ.
Name
402 - Payment Required
Description
Недостаточно кредитов для выполнения этой задачи.
Name
429 - Too Many Requests
Description
Вы превысили ограничение частоты запросов.
Request
POST
/openapi/creative-lab/figure/v1/prototype
# Stage 1: generate a chibi-style concept imagecurlhttps://api.meshy.ai/openapi/creative-lab/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>" }'
Response
{"result":"018a210d-8ba4-705c-b111-1f1776f7f578"}
Prototype example
Start with a source portrait, then generate the prototype image used by the build stage.
Сгенерировать финальную текстурированную 3D-фигурку на основе успешно завершённой прототипной задачи.
Сборка выполняется по тому же конвейеру изображение-в-3D, что и
Изображение в 3D, поэтому формат объекта ответа и
список URL-адресов выходных файлов полностью совпадают. Обратитесь к
Объект задачи сборки фигурки для описания
формы ответа.
Параметры
Name
input_task_id
Type
string
Обязательный
Description
ID задачи прототипа, созданной через этот же OpenAPI эндпоинт. Прототип должен быть создан с тем же API-ключом, должен достигнуть статуса SUCCEEDED и должен был сгенерировать ровно одно изображение-кандидат.
Прототипные задачи, созданные через веб-приложение, не принимаются — эндпоинт сборки принимает только прототипные задачи, созданные через POST /openapi/creative-lab/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.
Нет кандидата: Прототипная задача завершилась успешно, но не сгенерировала изображение-кандидат.
Указанная прототипная задача не существует, принадлежит другому пользователю или была создана через веб-приложение (только прототипные задачи, созданные в режиме API, могут быть переданы в сборку).
Name
429 - Too Many Requests
Description
Вы превысили ограничение частоты.
Request
POST
/openapi/creative-lab/figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurlhttps://api.meshy.ai/openapi/creative-lab/figure/v1/build \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578" }'
Response
{"result":"019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"}
Build example
The build task turns the selected prototype image into a downloadable textured 3D model.
Получите задачу прототипа или сборки по действительному 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
Уникальный идентификатор задачи фигурки для потоковой передачи.
Возвращаемые данные
Возвращает поток объектов задач Figure Prototype
или 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: Сортировка по времени создания в порядке убывания.
Объект Figure Prototype Task — это единица работы, которую Meshy отслеживает
для создания концептуального изображения в стиле чиби на основе исходной фотографии. Результат
этого этапа передаётся на этап сборки
через input_task_id.
Свойства
Name
id
Type
string
Description
Уникальный идентификатор задачи. Хотя в качестве технической детали реализации мы используем k-сортируемый UUID для идентификаторов задач, вам не следует делать никаких предположений о формате id.
Name
type
Type
string
Description
Тип задачи. Значение — creative-lab-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 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
Ссылки для скачивания вариантов концептуального изображения, сгенерированных данной задачей прототипирования. В настоящее время API всегда возвращает ровно один вариант; поле представлено массивом, чтобы в будущих версиях можно было предоставлять несколько вариантов без обратной несовместимости.
Объект Figure Build Task — это единица работы, отслеживаемая Meshy для
генерации текстурированной 3D-фигурки из успешно выполненной задачи-прототипа. Он
выполняет тот же конвейер image-to-3D, который используется в Изображение в 3D,
поэтому выходные поля повторяют объект задачи этого эндпоинта.
Свойства
Name
id
Type
string
Description
Уникальный идентификатор задачи.
Name
type
Type
string
Description
Тип задачи. Значение — creative-lab-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
Всегда пусто для figure build. Присутствует для совместимости между эндпоинтами с общей структурой V2ImageTo3DTaskResponse, используемой в Изображение в 3D.
Name
negative_prompt
Type
string
Description
Всегда пусто для figure build. Присутствует для совместимости между эндпоинтами.
Name
texture_prompt
Type
string
Description
Всегда пусто для figure build. Присутствует для совместимости между эндпоинтами.
Name
texture_image_url
Type
string
Description
Всегда пусто для figure build. Присутствует для совместимости между эндпоинтами.
Name
model_urls
Type
object
Description
Ссылки для скачивания сгенерированной 3D-модели. Figure build выдаёт текстурированный GLB, а также пару OBJ + MTL для конвейеров, предпочитающих Wavefront OBJ. Форма поля соответствует объекту model_urls из Изображение в 3D, поэтому добавление новых форматов в будущем не приведёт к breaking change.
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
Массив объектов URL текстур, сгенерированных этой задачей. В настоящее время содержит один объект с картой базового цвета.
Name
base_color
Type
string
Description
Ссылка для скачивания изображения карты базового цвета.