Перетворіть вихідне фото на колекційну 3D-фігурку у стилі чібі у два етапи:
prototype генерує стилізоване концептуальне зображення з вашого вхідного фото, а потім
build перетворює це концептуальне зображення на 3D-модель із мапами матеріалів. Два етапи
пов’язані через input_task_id.
Згенеруйте одне концептуальне зображення у стилі чібі з вихідної фотографії.
Повернений ID завдання — це те, що ви передаєте як input_task_id до кінцевої точки
build. Див.
Об’єкт завдання прототипу фігурки
для форми відповіді.
Параметри
Name
image_url
Type
string
Обов'язковий
Description
Вихідна фотографія, яку Meshy стилізує як фігурку чібі. Наразі ми підтримуємо формати .jpg, .jpeg, .png і .webp.
Є два способи надати зображення:
Публічно доступна URL-адреса: URL-адреса, доступна з публічного інтернету.
Data URI: Data URI зображення, закодований у base64. Приклад Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
Name
name
Type
string
Description
Необов’язкова назва завдання для відображення. Максимум 100 символів.
Повертає
Властивість 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 або moderation щодо інтелектуальної власності.
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 imagecurl https://api.meshy.ai/openapi/creative-lab/figure/v1/prototype \ -X POST \ -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"}
Prototype example
Start with a source portrait, then generate the prototype image used by the build stage.
Згенеруйте фінальну текстуровану 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-mode переходять до побудови).
Name
429 - Too Many Requests
Description
Ви перевищили своє обмеження частоти.
Request
POST
/openapi/creative-lab/figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurl https://api.meshy.ai/openapi/creative-lab/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" }'
Response
{"result":"019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"}
Build example
The build task turns the selected prototype image into a downloadable textured 3D model.
Отримайте завдання прототипу або побудови за дійсним 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.
Properties
Name
id
Type
string
Description
Унікальний ідентифікатор завдання. Хоча як деталь реалізації ми використовуємо k-sortable UUID для ідентифікаторів завдань, вам не слід робити жодних припущень щодо формату ідентифікатора.
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
progress завдання. Якщо завдання ще не запущено, ця властивість матиме значення 0. Щойно завдання буде успішно виконано, значення стане 100.
Name
created_at
Type
timestamp
Description
Мітка часу створення завдання, у мілісекундах.
Мітка часу представляє кількість мілісекунд, що минули з 1 січня 1970 року UTC, відповідно до
стандарту RFC 3339.
Наприклад, п’ятниця, 1 вересня 2023 року, 12:00:00 PM GMT представлена як 1693569600000. Це стосується
усіх міток часу в Meshy API.
Name
started_at
Type
timestamp
Description
Мітка часу запуску завдання, у мілісекундах. Якщо завдання ще не запущено, ця властивість матиме значення 0.
Name
finished_at
Type
timestamp
Description
Мітка часу завершення завдання, у мілісекундах. Якщо завдання ще не завершено, ця властивість матиме значення 0.
Name
expires_at
Type
timestamp
Description
Мітка часу, коли результат завдання expires_at, у мілісекундах.
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
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-адреса для завантаження зображення мапи базового кольору.