Перетворіть вихідну фотографію на колекційну 3D фігурку з великою головою у два
етапи: прототип генерує стилізоване концептуальне зображення з вашої вхідної
фотографії, потім побудова перетворює це концептуальне зображення на модель з 3D текстурами.
Ці два етапи пов'язані через input_task_id.
POST /openapi/creative-lab/vinyl-figure/v1/prototype
Генерація єдиного зображення концепції у стилі вінілової фігурки з вихідного фото. Повернене ідентифікатор завдання – це те, що ви передаєте як input_task_id до кінцевої точки build. Зверніться до Об'єкта Завдання Прототипу Вінілової Фігурки для форми відповіді.
Параметри
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 завдання новоствореного прототипу вінілової фігурки. Опитати Отримати Завдання кінець або підписатися на stream до моменту, коли завдання досягне стану SUCCEEDED, потім передайте цей ID до build 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 рядок неправильно сформований.
Контент помічено: Вхідне зображення було заблоковано NSFW або через модерацію інтелектуальної власності.
Name
401 - Unauthorized
Description
Автентифікація не вдалося. Будь ласка, перевірте свій API ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
429 - Too Many Requests
Description
Ви перевищили своє обмеження частоти.
Запит
POST
/openapi/creative-lab/vinyl-figure/v1/prototype
# Стадія 1: створення зображення концепції у стилі вінілової фігуркиcurl https://api.meshy.ai/openapi/creative-lab/vinyl-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>" }'
Відповідь
{"result":"019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de"}
Prototype example
Start with a source portrait, then generate the prototype image used by the build stage.
Створіть фінальну текстуровану 3D вінілову фігурку на основі успішного прототипу. Побудова використовує той самий процес перетворення Зображення у 3D, тому формат об'єкта відповіді та список вихідних URL збігаються точно. Звертайтеся до Об'єкт Завдання на Складання Вінілової Фігурки для форми відповіді.
Параметри
Name
input_task_id
Type
string
Обов'язковий
Description
Ідентифікатор завдання прототипу, створеного через цю ж кінцеву точку 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
Ви перевищили своє обмеження частоти.
Запит
POST
/openapi/creative-lab/vinyl-figure/v1/build
# Етап 2: складання на основі успішного завдання прототипуcurl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build \ -X POST \ -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.
Передавати оновлення в реальному часі для завдання фігурки з вінілу через події, що відправляються сервером (SSE). Шлях URL повинен відповідати стадії завдання — відкриття потоку на
/prototype/:buildId/stream передає єдиний event: error корисне навантаження з
status_code: 404 і закриває потік.
Параметри
Name
id
Type
path
Description
Унікальний ідентифікатор для завдання фігурки з вінілу, яке потрібно передавати.
Повертається
Повертає потік об'єктів завдань Прототипу Фігурки з Вінілу або Побудови Фігурки з Вінілу як події, що відправляються сервером. Для завдань PENDING або IN_PROGRESS потік відповідей включатиме лише необхідні поля progress та status.
// Приклад події помилки (помилкова стадія або завдання не знайдено)event: errordata: {"status_code": 404,"message": "Завдання не знайдено"}// Приклади подій повідомлень для ілюстрації прогресу завдання.// Для завдань в статусі PENDING або IN_PROGRESS потік відповідей не включатиме всі поля.event: messagedata: {"id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef","progress": 0,"status": "PENDING"}event: messagedata: {"id": "019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef","type": "creative-lab-vinyl-figure-build","status": "SUCCEEDED","progress": 100,"created_at": 1752969700000,"started_at": 1752969710000,"finished_at": 1752969735000,"expires_at": 1753228935000,"task_error": null,"consumed_credits": 30,"prompt": "","negative_prompt": "","texture_prompt": "","texture_image_url": "","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.glb?Expires=***","obj":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.obj?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/model.mtl?Expires=***" },"thumbnail_url": "https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/output/preview.png?Expires=***","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/019c8a31-6e2f-7b4d-9a55-4c3098b2d5ef/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
Обмеження на розмір сторінки. Максимально дозволяється 50 елементів.
Name
sort_by
Type
string
за замовчуванням -created_at
Description
Поле для сортування. Доступні значення:
+created_at: Сортувати за часом створення у зростаючому порядку.
-created_at: Сортувати за часом створення у спадаючому порядку.
# Список завдань прототипуcurl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/prototype?page_size=10 \ -H "Authorization: Bearer ${YOUR_API_KEY}"# Список завдань будівництваcurl https://api.meshy.ai/openapi/creative-lab/vinyl-figure/v1/build?page_size=10 \ -H "Authorization: Bearer ${YOUR_API_KEY}"
Об'єкт завдання прототипу фігурки з вінілу — це одиниця роботи, за якою Meshy стежить, щоб створити концептуальне зображення у стилі фігурки з вінілу з джерельної фотографії. Результат цього етапу об'єднується у
етап збирання через input_task_id.
Властивості
Name
id
Type
string
Description
Унікальний ідентифікатор для завдання. Хоча ми використовуємо k-сортований UUID для ідентифікаторів завдань як деталь реалізації, вам не слід робити жодних припущень щодо формату ідентифікатора.
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 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
Мітка часу, коли результат завдання спливає, в мілісекундах.
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 вінілової фігурки з завершеного прототипного завдання.
Він використовує ту ж саму pipeline Зображення у 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
Завантажувані URLs для створеної 3D моделі. Збірка вінілової фігурки випускає текстурований GLB плюс пару OBJ + MTL для ланцюгів обробки, що вважають за краще Wavefront OBJ. Форма поля відповідає об'єкту Image to 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 companion 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 для зображення з основною картою кольору.