Преобразуйте исходное фото в коллекционную 3D фигурку с большой головой в два этапа: прототип генерирует стилизованное концептуальное изображение из вашего входного фото, затем сборка превращает это концептуальное изображение в 3D модель с текстурой. Два этапа связаны через input_task_id.
POST /openapi/creative-lab/vinyl-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/vinyl-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/vinyl-figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurlhttps://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "input_task_id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de" }'
Получите задачу прототипа или сборки, указав действительный id задачи. Путь URL
должен соответствовать стадии задачи — задача сборки, полученная через
/prototype/:id, вернет 404, и наоборот.
Отменить задачу vinyl figure. Если задача все еще находится в состоянии PENDING, кредиты, использованные при создании, возвращаются. Задачи, которые уже находятся в состоянии IN_PROGRESS, отменяются без возврата (работник может уже использовать ресурсы). Задачи, которые уже достигли конечного состояния (SUCCEEDED, FAILED, CANCELED), не могут быть отменены.
Путь URL должен соответствовать стадии задачи — DELETE на
/prototype/:buildId возвращает 404.
Параметры пути
Name
id
Type
path
Description
Уникальный идентификатор задачи vinyl figure для отмены.
Возвращает
Возвращает 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
Лимит размера страницы. Максимально допустимое количество — 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-vinyl-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
Временная метка начала задачи в миллисекундах. Если задача еще не начата, это свойство будет 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
Скачиваемые URL-адреса для кандидатов концептуальных изображений, созданных этой задачей прототипа. В настоящее время API всегда возвращает ровно одного кандидата; поле является массивом, чтобы будущие версии могли отображать нескольких кандидатов без изменения, нарушающего совместимость.
Объект задачи создания виниловой фигурки — это рабочая единица, которую Meshy отслеживает для генерации текстурированной 3D виниловой фигурки из успешной прототипной задачи. Он использует тот же конвейер "Изображение в 3D", что и Изображение в 3D, поэтому поля вывода отражают объект задачи этого эндпоинта task object.
Свойства
Name
id
Type
string
Description
Уникальный идентификатор задачи.
Name
type
Type
string
Description
Тип задачи. Значение — creative-lab-vinyl-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, чтобы будущие добавления форматов не приводили к нарушению совместимости.