Превратите исходное фото в коллекционную 3D-фигурку в стиле чиби за два этапа:
прототип генерирует стилизованное концепт-изображение на основе вашего входного фото, затем
сборка превращает это концепт-изображение в 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
Запрос был неприемлемым. Частые причины:
Отсутствующий параметр: требуется image_url.
Недопустимый формат изображения: предоставленный image_url не является поддерживаемым форматом (.jpg, .jpeg, .png, .webp).
Размеры изображения вне допустимого диапазона: изображение слишком маленькое, превышает максимальный размер файла или превышает максимальное количество пикселей.
Недоступный URL: image_url не удалось загрузить (404 или timeout).
Недопустимый Data URI: строка base64 имеет неверный формат.
Контент помечен: входное изображение было помечено NSFW- или intellectual property moderation.
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 imagecurl https://api.meshy.ai/openapi/creative-lab/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>" }'
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.
Нет кандидата: задача прототипа выполнена успешно, но не создала изображение-кандидат.
Name
401 - Unauthorized
Description
Аутентификация не удалась. Проверьте свой API-ключ.
Name
402 - Payment Required
Description
Недостаточно кредитов для выполнения этой задачи.
Name
404 - Not Found
Description
Указанная задача прототипа не существует, принадлежит другому пользователю или была создана через веб-приложение (только задачи прототипа в API-mode могут быть связаны со сборкой).
Name
429 - Too Many Requests
Description
Вы превысили свое ограничение частоты.
Request
POST
/openapi/creative-lab/figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurl https://api.meshy.ai/openapi/creative-lab/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" }'
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, отменяются без возврата (worker, возможно, уже
расходует ресурсы). Задачи, которые уже достигли терминального состояния
(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 возвращает задачи prototype; /build
возвращает задачи build. Задачи с другого этапа не включаются ни в один
из ответов.
Параметры пути
Name
stage
Type
path
Обязательный
Description
Либо prototype, либо build. Коллекция возвращает только задачи,
этап которых соответствует URL — запрос /prototype никогда не возвращает
задачи build и наоборот.
Параметры запроса
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-figure-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 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
Количество кредитов, consumed_credits этой задачей. Присутствует, когда статус задачи — 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-figure-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
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, поэтому будущие добавления форматов можно будет встроить без критического изменения.