Перетворіть вихідне фото на колекційну 3D-фігурку у стилі чібі за два етапи:
prototype генерує стилізоване концептуальне зображення з вашого вхідного фото, потім
build перетворює це концептуальне зображення на текстуровану 3D-модель. Ці два етапи
пов'язані через input_task_id.
Згенеруйте єдине концептуальне зображення у стилі chibi з вихідної фотографії. Отриманий ID завдання — це те, що ви передаєте як input_task_id до endpoint для побудови. Зверніться до
Об'єкта Figure Prototype Task
щоб дізнатися про формат відповіді.
Параметри
Name
image_url
Type
string
Обов'язковий
Description
Вихідна фотографія, яку Meshy стилізує як фігурку chibi. Наразі підтримуються формати .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 завдання новоствореного прототипу фігурки. Опитуйте endpoint Get a Task або підпишіться на stream, доки завдання не досягне статусу SUCCEEDED, а потім передайте цей ID до endpoint для побудови як input_task_id.
Режими відмови
Name
400 - Bad Request
Description
Запит було неприйнятно. Поширені причини:
Відсутній параметр: image_url є обов'язковим.
Недійсний формат зображення: наданий image_url не має підтримуваного формату (.jpg, .jpeg, .png, .webp).
Розміри зображення поза межами діапазону: зображення занадто мале, перевищує максимальний розмір файлу або максимальну кількість пікселів.
Недоступний URL: не вдалося завантажити image_url (404 або timeout).
Недійсний Data URI: рядок base64 некоректний.
Контент позначено: вхідне зображення було позначено moderation щодо NSFW або інтелектуальної власності.
Name
401 - Unauthorized
Description
Автентифікація не вдалася. Будь ласка, перевірте свій API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
429 - Too Many Requests
Description
Ви перевищили своє обмеження частоти.
Request
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>" }'
Response
{"result":"018a210d-8ba4-705c-b111-1f1776f7f578"}
Приклад прототипу
Почніть з вихідного портрета, а потім згенеруйте прототипне зображення, яке використовується на етапі побудови.
Згенерувати фінальну текстуровану 3D-фігурку з успішного прототипного завдання.
Побудова виконується за тим самим конвеєром зображення-у-3D, що й
Зображення у 3D, тому формат об'єкта відповіді та
перелік URL-адрес результатів повністю збігаються. Дивіться
Об'єкт завдання побудови фігурки для
формату відповіді.
Параметри
Name
input_task_id
Type
string
Обов'язковий
Description
ID завдання прототипу, створеного через ту саму 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
Ви перевищили обмеження частоти.
Request
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" }'
Response
{"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
Унікальний ідентифікатор завдання фігурки для стрімінгу.
Повертає
Повертає потік об'єктів завдання Figure Prototype
або 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: Сортувати за часом створення у порядку спадання.
Об'єкт Figure Prototype Task — це одиниця роботи, яку 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 за Гринвічем, представлена як 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. Для завдань зі статусом FAILED повертає 0 (у разі невдачі кредити повертаються).
Name
image_urls
Type
array of strings
Description
URL-адреси для завантаження варіантів концептуального зображення, згенерованих цим завданням-прототипом. Наразі API завжди повертає рівно один варіант; поле є масивом, щоб майбутні версії могли повертати кілька варіантів без критичних змін.
Об'єкт завдання побудови фігурки — це одиниця роботи, яку Meshy відстежує для
генерації текстурованої 3D-фігурки з успішно завершеного прототипного завдання. Воно
виконує той самий конвеєр image-to-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. Форма поля відповідає об'єкту model_urls зі Зображення у 3D, тому додавання нових форматів у майбутньому не порушить сумісність.
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-адреса для завантаження зображення карти базового кольору.