Перетворіть вихідне фото на колекційну 3D мініфігурку в стилі цеглинок у два етапи:
прототип генерує стилізоване концептуальне зображення з вашого вхідного фото, потім
побудова перетворює це концептуальне зображення на 3D модель з текстурою. Обидва етапи
пов'язані через input_task_id.
POST /openapi/creative-lab/brick-figure/v1/prototype
Генерація єдиного концептуального зображення у стилі цеглинок з вихідного фото. Повернений ID завдання - це те, що ви передаєте як input_task_id до кінцевої точки build. Зверніться до
Об'єкт завдання прототипу фігурки з цеглинок
для форми відповіді.
Параметри
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 завдання новоствореного прототипу фігурки з цеглинок. Опитуйте Отримати завдання кінцеву точку або підпишіться на потік до тих пір, поки завдання не досягне SUCCEEDED, потім передайте цей ID до кінцевої точки build як 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 key.
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 imagecurlhttps://api.meshy.ai/openapi/creative-lab/brick-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>" }'
Генеруйте фінальну 3D фігурку з цеглинок з текстурою з успішного прототипу
завдання. Побудова використовує той самий конвеєр зображення у 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
Ви перевищили своє обмеження частоти.
Запит
POST
/openapi/creative-lab/brick-figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurlhttps://api.meshy.ai/openapi/creative-lab/brick-figure/v1/build \-XPOST \-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.
Отримайте пагінований список ваших завдань з фігурками з цеглинок для одного етапу. Шлях 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: Сортувати за часом створення у спадному порядку.
Об'єкт Завдання Прототипу Фігурки з Цеглинок — це робоча одиниця, за якою Meshy відстежує процес створення концептуального зображення в стилі цеглинок з вихідної фотографії. Вихід цього етапу пов'язаний з етапом створення через input_task_id.
Властивості
Name
id
Type
string
Description
Унікальний ідентифікатор завдання. Хоча ми використовуємо k-сортований UUID для ідентифікаторів завдань як деталь реалізації, ви не повинні робити жодних припущень щодо формату id.
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 GMT представлена як 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. Форма поля відповідає об'єкту Image to 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-адреса для зображення карти базового кольору.