Перетворіть вихідне фото на колекційну 3D фігурку з великою головою у два
етапи: прототип генерує стилізоване концептуальне зображення з вашого
вхідного фото, потім створення перетворює це концептуальне зображення на 3D модель з текстурою.
Два етапи пов'язані через input_task_id.
POST /openapi/creative-lab/vinyl-figure/v1/prototype
Генеруйте єдине зображення концепту в стилі вінілової фігурки з вихідної фотографії. Повернений ідентифікатор завдання - це те, що ви передаєте як input_task_id до кінцевої точки створення. Зверніться до Об'єкт завдання прототипу вінілової фігурки для форми відповіді.
Параметри
Name
image_url
Type
string
Обов'язковий
Description
Вихідна фотографія для Meshy, щоб стилізувати як вінілову фігурку з великою головою. Ми наразі підтримуємо формати .jpg, .jpeg, .png та .webp.
Існує два способи надати зображення:
Публічно доступний URL: URL, доступний з публічного інтернету.
Data URI: Базовий 64-кодований 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, потім передайте цей ідентифікатор до кінцевої точки створення як input_task_id.
Режими відмови
Name
400 - Bad Request
Description
Запит був неприйнятним. Загальні причини:
Відсутній параметр: image_url є обов'язковим.
Неприпустимий формат зображення: Наданий image_url не є підтримуваним форматом (.jpg, .jpeg, .png, .webp).
Розміри зображення поза діапазоном: Зображення занадто мале, перевищує максимальний розмір файлу або перевищує максимальну кількість пікселів.
Недоступний URL: image_url не вдалося завантажити (404 або timeout).
Неприпустимий Data URI: Базовий 64-рядок має неправильний формат.
Контент позначено: Вхідне зображення було позначено модерацією NSFW або інтелектуальної власності.
Name
401 - Unauthorized
Description
Автентифікація не вдалася. Будь ласка, перевірте свій API key.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
429 - Too Many Requests
Description
Ви перевищили своє обмеження частоти.
Запит
POST
/openapi/creative-lab/vinyl-figure/v1/prototype
# Stage 1: generate a vinyl-figure-style concept imagecurlhttps://api.meshy.ai/openapi/creative-lab/vinyl-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":"019c8a2e-4b7d-7c3a-8d21-3f2987a1c4de"}
Приклад прототипу
Почніть з вихідної фотографії, потім згенеруйте зображення прототипу, яке використовується на етапі створення.
Генерація фінальної 3D вінілової фігурки з текстурою з успішного прототипу
завдання. Побудова використовує той самий конвеєр зображення у 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
# 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.
Транслюйте оновлення в реальному часі для завдання з вініловою фігуркою через 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-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 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-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
Завантажувані 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-адреса для зображення карти базового кольору.