Преобразуйте исходное фото в коллекционную 3D фигурку с большой головой в два
этапа: прототип создает стилизованное концептуальное изображение из вашего
входного фото, затем сборка превращает это концептуальное изображение в 3D модель с 3D texture.
Оба этапа связаны с помощью 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: закодированный в base64 Data URI изображения. Пример 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
Запрос был неприемлемым. Распространенные причины:
Создайте окончательную текстурированную 3D виниловую фигурку из успешной задачи прототипа. Сборка использует ту же технологию преобразования Изображение в 3D, поэтому формат объекта ответа и список выходных URL совпадают точно. Обратитесь к Объекту задачи сборки виниловой фигурки для формы ответа.
Параметры
Name
input_task_id
Type
string
Обязательный
Description
ID задачи прототипа, созданной через этот же эндпоинт 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
# Этап 2: сборка на основе успешной задачи прототипаcurl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build \ -X POST \ -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, и наоборот.
Отмените задачу виниловой фигурки. Если задача все еще 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": "Задача не найдена"}// Примеры событий Message иллюстрируют прогресс задачи.// Для задач со статусом PENDING или IN_PROGRESS поток ответа не будет содержать все поля.event: messagedata: {"id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef","progress": 0,"status": "PENDING"}event: messagedata: {"id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef","type": "creative-lab-vinyl-figure-build","status": "SUCCEEDED","progress": 100,"created_at": 1752969700000,"started_at": 1752969710000,"finished_at": 1752969735000,"expires_at": 1753228935000,"task_error": null,"consumed_credits": 30,"prompt": "","negative_prompt": "","texture_prompt": "","texture_image_url": "","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.glb?Expires=***","obj":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.obj?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.mtl?Expires=***" },"thumbnail_url": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/preview.png?Expires=***","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/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
Лимит размера страницы. Максимальное количество — 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 PM 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
Загружаемые URL для концептуальных изображений, созданных этой прототипной задачей. В настоящее время API всегда возвращает ровно одного кандидата; поле является массивом, так что будущие версии могут отображать нескольких кандидатов без изменения, разрушающего совместимость.
Объект задачи сборки виниловой фигурки — это рабочая единица, которую отслеживает Meshy
для создания текстурированной 3D виниловой фигурки из задания-прототипа со статусом SUCCEEDED.
Он использует тот же конвейер "Изображение в 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. Форма поля соответствует объекту Изображение в 3D model_urls, чтобы в будущем можно было добавлять форматы без повреждений.