meshy-5 буде вимкнено 10 жовт. 2026 р.. lowpoly буде вимкнено 30 жовт. 2026 р.. Перейдіть на іншу модель до цих дат, щоб уникнути помилок у запитах.
Creative Lab — API вінілової фігурки
Перетворіть вихідне фото на колекційну 3D-фігурку у стилі вінілової іграшки з великою головою у два
етапи: прототип генерує стилізоване концептуальне зображення з вашого вихідного
фото, а потім побудова перетворює це концептуальне зображення на текстуровану 3D-модель.
Обидва етапи пов'язані через input_task_id.
POST /openapi/creative-lab/vinyl-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.
Згенеруйте фінальну текстуровану 3D-вінілову фігурку на основі успішно виконаного завдання створення прототипу. Побудова виконується за тим самим конвеєром зображення-у-3D, що й
Зображення у 3D, тому формат об'єкта відповіді та список URL-адрес результатів повністю збігаються. Зверніться до
Об'єкт завдання побудови вінілової фігурки
для отримання інформації про формат відповіді.
Параметри
Name
input_task_id
Type
string
Обов'язковий
Description
ID завдання прототипу, створеного через цю саму кінцеву точку OpenAPI. Прототип має бути створений з тим самим API-ключем, повинен мати статус SUCCEEDED та повинен був згенерувати рівно одне кандидатне зображення.
Завдання прототипу, створені через вебзастосунок, не приймаються — кінцева точка побудови приймає лише завдання прототипу, створені через POST /openapi/creative-lab/vinyl-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/vinyl-figure/v1/build
# Stage 2: chain build off a succeeded prototype taskcurlhttps://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "input_task_id": "019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de" }'
Отримайте завдання прототипу або збірки за дійсним 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.
Стрімінг оновлень у реальному часі для завдання vinyl figure через Server-Sent Events
(SSE). Шлях URL повинен відповідати етапу завдання — відкриття потоку за адресою
/prototype/:buildId/stream видає одне корисне навантаження event: error зі
status_code: 404 і закриває потік.
Параметри
Name
id
Type
path
Description
Унікальний ідентифікатор завдання vinyl figure для стрімінгу.
Повертає
Повертає потік об'єктів завдання Vinyl Figure Prototype
або Vinyl Figure Build у вигляді Server-Sent Events.
Кожен кадр містить повний об'єкт завдання для цього етапу — таку саму структуру, яку
повертає кінцева точка Get — тож, поки завдання має статус PENDING або IN_PROGRESS, поля
виводу просто ще не заповнені (null, [] або {}), а
finished_at дорівнює null.
Отримайте список ваших завдань з вінілових фігурок для одного етапу з пагінацією.
Шлях URL визначає етап — /prototype повертає завдання прототипу;
/build повертає завдання побудови. Завдання з іншого етапу не включаються
в жодну з відповідей.
Path Parameters
Name
stage
Type
path
Обов'язковий
Description
prototype або build. Колекція повертає лише завдання,
чий етап відповідає URL — запит до /prototype ніколи не повертає
завдання побудови, і навпаки.
Query Parameters
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-vinyl-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. Повертає 0 для завдань зі статусом FAILED (кредити повертаються у разі невдачі).
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-vinyl-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
Масив об'єктів посилань на текстури, згенерованих цим завданням. Наразі містить один об'єкт із картою базового кольору.
Name
base_color
Type
string
Description
Посилання для завантаження зображення карти базового кольору.