Перетворіть вихідне фото на колекційну 3D-мініфігурку у стилі цеглинок за два етапи:
prototype генерує стилізоване концептуальне зображення з вашого вхідного фото, а потім
build перетворює це концептуальне зображення на текстуровану 3D-модель. Обидва етапи
пов'язані через input_task_id.
POST /openapi/creative-lab/brick-figure/v1/prototype
Згенерувати одне концептуальне зображення у стилі цеглинок з вихідної фотографії. Отриманий ID завдання — це те, що ви передаєте як 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,<ваші base64-закодовані дані зображення>.
Name
name
Type
string
Description
Необов'язкова назва завдання для відображення. Максимум 100 символів.
Name
remove_background
Type
boolean
за замовчуванням false
Description
Якщо встановлено значення true, зображення прототипу повертається у вигляді прозорого RGBA PNG з видаленим фоном, щоб ви могли скомпонувати об'єкт з будь-яким фоном.
Результат
Властивість 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.
Name
401 - Unauthorized
Description
Автентифікація не вдалася. Будь ласка, перевірте свій API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
403 - Forbidden
Description
Вхідне зображення було позначено через порушення прав інтелектуальної власності.
Name
429 - Too Many Requests
Description
Ви перевищили обмеження частоти.
Request
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
ID завдання прототипу, створеного через цю саму кінцеву точку 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
Ви перевищили обмеження частоти.
Request
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
Унікальний ідентифікатор завдання фігурки з блоків для стрімінгу.
Повертає
Повертає потік об'єктів завдань Brick Figure Prototype
або Brick 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: Сортування за часом створення у порядку спадання.
Об'єкт завдання прототипу фігурки з цеглинок — це робоча одиниця, яку 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 за Гринвічем представлена як 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,
тому поля результату відображають об'єкт завдання цієї кінцевої точки.
Властивості
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
Посилання для завантаження згенерованої 3D моделі. Побудова фігурки з цеглинок видає текстурований GLB, а також пару OBJ + MTL для конвеєрів, які надають перевагу формату Wavefront OBJ. Форма поля відповідає об'єкту model_urls з Зображення у 3D, тому майбутні формати можна буде додати без порушення сумісності.
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
Посилання для завантаження зображення карти базового кольору.