Перетворіть вихідне фото на колекційну 3D фігурку в стилі чибі у два етапи:
прототип генерує стилізоване концептуальне зображення з вашого вхідного фото, потім
побудова перетворює це концептуальне зображення на 3D модель з текстурою. Обидва етапи
пов'язані через input_task_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,<your base64-encoded image data>.
Name
name
Type
string
Description
Необов'язкова назва завдання для відображення. Максимум 100 символів.
Name
remove_background
Type
boolean
за замовчуванням false
Description
Коли встановлено значення true, прототип зображення повертається як прозорий RGBA PNG з видаленим фоном, щоб ви могли компонувати об'єкт на будь-якому фоні.
Повертає
Властивість result відповіді містить ідентифікатор завдання новоствореного завдання прототипу фігурки. Опитуйте Отримати Завдання кінцеву точку або підпишіться на потік, поки завдання не досягне 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 key.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
429 - Too Many Requests
Description
Ви перевищили своє обмеження частоти.
Запит
POST
/openapi/creative-lab/figure/v1/prototype
# Stage 1: generate a chibi-style concept imagecurlhttps://api.meshy.ai/openapi/creative-lab/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>" }'
Відповідь
{"result":"018a210d-8ba4-705c-b111-1f1776f7f578"}
Приклад прототипу
Почніть з вихідного портрета, потім згенеруйте зображення прототипу, яке використовується на етапі збірки.
Генерація фінальної текстурованої 3D фігурки з успішного прототипного завдання. Побудова виконує той самий процес зображення у 3D, що й Зображення у 3D, тому формат об'єкта відповіді та список вихідних URL-адрес точно збігаються. Зверніться до Об'єкт Завдання на Побудову Фігурки для форми відповіді.
Параметри
Name
input_task_id
Type
string
Обов'язковий
Description
Ідентифікатор завдання прототипу, створеного через цю ж кінцеву точку OpenAPI. Прототип повинен бути створений з тим самим API-ключем, досягти SUCCEEDED і створити рівно одне кандидатське зображення.
Прототипні завдання, створені через веб-додаток, не приймаються — кінцева точка побудови приймає лише прототипні завдання, створені за допомогою POST /openapi/creative-lab/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/figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurlhttps://api.meshy.ai/openapi/creative-lab/figure/v1/build \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578" }'
Відповідь
{"result":"019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"}
Приклад побудови
Завдання на побудову перетворює вибране прототипне зображення у завантажувану текстуровану 3D модель.
Отримайте завдання на прототип або збірку, вказавши дійсний 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
Обмеження розміру сторінки. Максимально дозволено 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-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
Мітка часу початку завдання, в мілісекундах. Якщо завдання ще не розпочато, це властивість буде 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,
тому вихідні поля відображають об'єкт завдання кінцевої точки.
Властивості
Name
id
Type
string
Description
Унікальний ідентифікатор для завдання.
Name
type
Type
string
Description
Тип завдання. Значення — creative-lab-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, щоб майбутні додавання форматів не викликали збоїв.
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-адреса для зображення карти базового кольору.