Перетворіть вихідне фото на колекційну 3D мініфігурку у стилі цегли у два етапи:
прототип створює стилизоване концепт-зображення з вашої вхідної фотографії, а потім
будівництво перетворює це концепт-зображення на 3D модель з текстурою. Два етапи
пов'язані через input_task_id.
POST /openapi/creative-lab/brick-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 завдання щойно створеного завдання прототипу фігурки. Опитуйте Отримати завдання endpoint або підписуйтесь на потік до тих пір, поки завдання не досягне SUCCEEDED, потім передайте цей ID у build endpoint як input_task_id.
Генеруйте фінальну текстуровану 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
# Етап 2: зв'язати побудову з успішного завдання-прототипуcurl https://api.meshy.ai/openapi/creative-lab/brick-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" }'
Отримати завдання на прототип або побудову, вказавши дійсний 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. Для завдань у статусі PENDING або IN_PROGRESS, потік відповідей
включатиме лише необхідні поля progress та status.
// Приклад події помилки (неправильний етап або завдання не знайдено)event: errordata: {"status_code": 404,"message": "Task not found"}// Приклади подій повідомлень ілюструють прогрес завдання.// Для завдань у стані PENDING або IN_PROGRESS, потік відповідей не включатиме всі поля.event: messagedata: {"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb","progress": 0,"status": "PENDING"}event: messagedata: {"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb","type": "creative-lab-brick-figure-build","status": "SUCCEEDED","progress": 100,"created_at": 1729123500000,"started_at": 1729123510000,"finished_at": 1729123535000,"expires_at": 1729382735000,"task_error": null,"consumed_credits": 30,"prompt": "","negative_prompt": "","texture_prompt": "","texture_image_url": "","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***","obj":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***" },"thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/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
Обмеження розміру сторінки. Максимально дозволено 100 елементів.
Name
sort_by
Type
string
за замовчуванням -created_at
Description
Поле для сортування. Доступні значення:
+created_at: Сортувати за часом створення у зростаючому порядку.
-created_at: Сортувати за часом створення у спадному порядку.
Об'єкт Завдання Прототипу Фігурки З Цегли — це робоча одиниця, яку Meshy відстежує, щоб створити концептуальне зображення в стилі цегли з вихідної фотографії. Вихід цього етапу зв'язаний з етапом побудови через input_task_id.
Властивості
Name
id
Type
string
Description
Унікальний ідентифікатор для завдання. Хоча ми використовуємо k-сортований UUID для ідентифікаторів завдань як елемент реалізації, ви не повинні робити жодних припущень про формат цього ідентифікатора.
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, тому вихідні поля відображають об'єкт завдання тієї кінцевої точки об'єкт завдання.
Властивості
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
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, щоб майбутні доповнення формату вставлялися без зникнення зворотної сумісності.
Name
glb
Type
string
Description
Скачуваний URL на текстурований GLB файл.
Name
obj
Type
string
Description
Скачуваний URL на Wavefront OBJ файл (геометрія + UV).
Name
mtl
Type
string
Description
Скачуваний URL на MTL файл матеріалу-партнера для OBJ. Використовується разом з 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 на зображення основної карти кольорів.