Ретекстурування API - це функція, яка дозволяє інтегрувати можливості AI ретекстурування від Meshy у ваш власний додаток. У цьому розділі ви знайдете всю необхідну інформацію, щоб почати роботу з цим API.
Ця кінцева точка дозволяє створити нове завдання Ретекстурування. Зверніться до
Об'єкта завдання Ретекстурування, щоб побачити, які
властивості включені в об'єкт завдання Ретекстурування.
Параметри
Обов'язковим є лише один з параметрів input_task_id або model_url. Якщо надано обидва, input_task_id має пріоритет.
Name
input_task_id
Type
string
Обов'язковий
Description
ID завершеного завдання Зображення у 3D або Текст у 3D, яке ви хочете ретекстурувати.
Це завдання має бути одним з таких: Text to 3D Preview, Text to 3D Refine, Image to 3D або Remesh. Крім того, воно повинно мати статус SUCCEEDED.
Публічно доступний URL: URL, доступний з публічного інтернету.
Data URI: base64-кодований data URI моделі. Використовуйте MIME type application/octet-stream. Приклад: data:application/octet-stream;base64,<ваші base64-кодовані дані моделі>.
Обов'язковим є рівно один вхідний параметр стилю: text_style_prompt, image_style_url або multiview_image_urls. multiview_image_urls не можна поєднувати з жодним з двох інших; якщо надано і text_style_prompt, і image_style_url, пріоритет має image_style_url.
Name
text_style_prompt
Type
string
Обов'язковий
Description
Опишіть бажаний стиль текстури об'єкта за допомогою тексту. Максимум 800 символів.
Name
image_style_url
Type
string
Обов'язковий
Description
Надайте 2D-зображення для спрямування процесу текстурування. Наразі ми підтримуємо формати .jpg, .jpeg та .png.
Існує два способи надання зображення:
Публічно доступний URL: URL, доступний з публічного інтернету
Data URI: base64-кодований data URI зображення. Приклад data URI: data:image/jpeg;base64,<ваші base64-кодовані дані зображення>
Текстурування за зображенням може працювати не оптимально, якщо між оригінальним асетом та завантаженим зображенням є суттєві геометричні відмінності.
Name
multiview_image_urls
Type
string[]
Обов'язковий
Description
Надайте від 1 до 4 зображень, що показують один і той же об'єкт з різних ракурсів, для спрямування текстурування. Перше зображення є основним (переднім) видом; порядок решти видів (лівий, задній, правий) не має значення.
Кожен елемент приймає ті ж формати, що й image_style_url (публічно доступний URL або base64 data URI, .jpg/.jpeg/.png).
Вимагає явного вказання ai_model: "meshy-7".
Name
ai_model
Type
string
за замовчуванням latest
Description
ID AI-моделі для використання при ретекстуруванні. Доступні значення: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
за замовчуванням false
Description
Зберегти існуючу UV-розкладку моделі замість генерування нової.
Якщо ви ретекстуруєте модель, згенеровану Meshy (через input_task_id або model_url, що вказує на результат роботи Meshy), встановіть значення true, щоб повторно використати її оптимізовану UV-розкладку.
Якщо ви ретекстуруєте завантажену вами сторонню модель, встановіть true, якщо вона вже має гарні UV, які ви хочете зберегти, або залиште false, щоб дозволити Meshy розгорнути нові UV (найкраще підходить для моделей без коректного UV-мапінгу).
Name
enable_pbr
Type
boolean
за замовчуванням false
Description
Генерувати PBR-карти (металевість, шорсткість, нормалі) на додаток до базового кольору. Карта випромінювання (emission) також включається, коли ai_model дорівнює meshy-6, за винятком texture_resolution: 8k. meshy-7 та latest не створюють карту випромінювання.
Name
texture_resolution
Type
string
за замовчуванням 2k
Description
Роздільна здатність текстури базового кольору. Одне зі значень 2k (2048×2048), 4k (4096×4096) або 8k (8192×8192). Вища роздільна здатність фіксує більше деталей поверхні.
4k та 8k вимагають ai_modelmeshy-6, meshy-7 або latest. При 8k карта випромінювання не створюється.
Name
hd_texture
Type
boolean
⚠ застарілий
за замовчуванням false
Description
Використовуйте замість цього texture_resolution — еквівалентно texture_resolution: "4k". Коли встановлено обидва, texture_resolution має пріоритет.
Name
remove_lighting
Type
boolean
за замовчуванням true
Description
Видаляє відблиски та тіні з текстури базового кольору, забезпечуючи чистіший результат, який краще працює за умов кастомного освітлення.
Підтримується лише коли ai_model дорівнює meshy-6.
Name
target_formats
Type
string[]
Description
Вказує, які формати 3D-файлів включати у вихідний результат. Будуть згенеровані та повернуті лише запитані формати, що може зменшити час виконання завдання. Якщо параметр не вказано, включаються всі підтримувані формати.
Доступні значення: glb, obj, fbx, stl, usdz, 3mf
Якщо параметр не вказано, генеруються всі формати, крім 3mf. 3mf включається лише якщо явно вказаний.
Name
alpha_thumbnail
Type
boolean
за замовчуванням false
Description
Коли встановлено значення true, завдання додатково рендерить версію попереднього перегляду з прозорим фоном (RGBA) і повертає її як alpha_thumbnail_url у відповіді GET. Існуюче поле thumbnail_url залишається без змін.
Результати
Властивість result відповіді містить id завдання новоствореного завдання Ретекстурування.
Режими помилок
Name
400 - Bad Request
Description
Запит було неприпустимо. Поширені причини:
Відсутній параметр: Має бути надано або model_url, або input_task_id.
Відсутній стиль: Має бути надано один з параметрів text_style_prompt, image_style_url або multiview_image_urls.
Конфліктуючі вхідні дані стилю: multiview_image_urls не можна поєднувати з text_style_prompt або image_style_url.
Непідтримувана модель для мультивиду: multiview_image_urls вимагає явного вказання ai_model: "meshy-7".
Модель недоступна: ai_model: "meshy-7" впроваджується поступово і ще не активована для вашого облікового запису.
Недійсне вхідне завдання: input_task_id повинен посилатися на успішне завдання від підтримуваної моделі.
Недійсний формат моделі: model_url вказує на файл з непідтримуваним розширенням.
Недоступний URL: model_url, image_style_url або елемент multiview_image_urls не вдалося завантажити.
Name
401 - Unauthorized
Description
Автентифікація не вдалася. Будь ласка, перевірте свій API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
429 - Too Many Requests
Description
Ви перевищили обмеження частоти запитів.
Request
POST
/openapi/v1/retexture
# Retexture with text promptcurlhttps://api.meshy.ai/openapi/v1/retexture \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style", "enable_original_uv": true, "enable_pbr": true }'# Retexture with image style and PBRcurlhttps://api.meshy.ai/openapi/v1/retexture \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "image_style_url": "https://cdn.meshy.ai/image/example_image.jpg", "ai_model": "latest", "enable_pbr": true, "enable_original_uv": true }'
Ця кінцева точка дозволяє отримати завдання на Ретекстурування за дійсним id завдання.
Зверніться до Об'єкт Завдання на Ретекстурування, щоб дізнатися, які
властивості включені в об'єкт завдання на Ретекстурування.
Параметри
Name
id
Type
path
Description
Унікальний ідентифікатор для завдання на Ретекстурування, яке потрібно отримати.
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","obj":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***","stl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","texture_image_url":"","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"task_error": {"message":"" },"consumed_credits":10}
[ {"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"preceding_tasks":0,"task_error": {"message":"" },"consumed_credits":10 }]
Об'єкт Завдання Ретекстурування — це робоча одиниця, яку Meshy використовує для створення 3D текстури з текстових або зображувальних вхідних даних.
Модель має наступні властивості:
Властивості
Name
id
Type
string
Description
Унікальний ідентифікатор для завдання. Хоча ми використовуємо k-сортуємий UUID для ідентифікаторів завдань як деталь реалізації, ви не повинні робити жодних припущень щодо формату id.
Name
type
Type
string
Description
Тип завдання Ретекстурування. Значення — retexture.
Name
model_urls
Type
object
Description
Завантажуване посилання на файл текстурованої 3D моделі, створеної Meshy.
Name
glb
Type
string
Description
Завантажуване посилання на файл GLB.
Name
fbx
Type
string
Description
Завантажуване посилання на файл FBX.
Name
obj
Type
string
Description
Завантажуване посилання на файл OBJ.
Name
usdz
Type
string
Description
Завантажуване посилання на файл USDZ.
Name
mtl
Type
string
Description
Завантажуване посилання на файл MTL, повертається разом з експортами OBJ, коли текстури присутні.
Name
stl
Type
string
Description
Завантажуване посилання на файл STL.
Name
3mf
Type
string
Description
Завантажуване посилання на файл 3MF. Присутнє лише тоді, коли 3mf було запитано через target_formats.
Name
text_style_prompt
Type
string
Description
Це текстовий prompt, який був використаний для створення завдання текстурування.
Name
image_style_url
Type
string
Description
Це зображувальний вхід, який був використаний для створення завдання текстурування.
Name
multiview_image_urls
Type
string[]
Description
Завантажувані посилання на мультивидові референсні зображення, які були використані для створення завдання текстурування. Присутнє лише тоді, коли завдання було створено з multiview_image_urls.
Name
thumbnail_url
Type
string
Description
Завантажуване посилання на зображення мініатюри файлу моделі.
Name
alpha_thumbnail_url
Type
string
Description
Завантажуване посилання на версію thumbnail_url з прозорим фоном (RGBA). Присутнє лише тоді, коли завдання було створено з alpha_thumbnail: true і прозорий попередній перегляд був успішно відтворений; інакше це поле опускається.
Name
progress
Type
integer
Description
Прогрес завдання. Якщо завдання ще не розпочато, ця властивість буде 0. Після успішного завершення завдання це значення стане 100.
Name
started_at
Type
timestamp
Description
Мітка часу, коли завдання було розпочато, в мілісекундах. Якщо завдання ще не розпочато, ця властивість буде 0.
Мітка часу представляє кількість мілісекунд, що минули з 1 січня 1970 року UTC, відповідно до стандарту RFC 3339.
Наприклад, п'ятниця, 1 вересня 2023 року, 12:00:00 GMT представлена як 1693569600000. Це стосується всіх міток часу в Meshy API.
Name
created_at
Type
timestamp
Description
Мітка часу, коли завдання було створено, в мілісекундах.
Name
expires_at
Type
timestamp
Description
Мітка часу, коли результат завдання закінчується, в мілісекундах.
Name
finished_at
Type
timestamp
Description
Мітка часу, коли завдання було завершено, в мілісекундах. Якщо завдання ще не завершено, ця властивість буде 0.
Name
status
Type
string
Description
Статус завдання. Можливі значення: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Масив об'єктів URL текстур, які створені з завдання. Зазвичай містить лише один об'єкт URL текстури. Кожен URL текстури має наступні властивості:
Name
base_color
Type
string
Description
Завантажуване посилання на зображення базової карти кольору.
Name
metallic
Type
string
Description
Завантажуване посилання на зображення металевої карти.
Якщо завдання створено з enable_pbr: false, ця властивість буде опущена.
Name
normal
Type
string
Description
Завантажуване посилання на зображення карти нормалей.
Якщо завдання створено з enable_pbr: false, ця властивість буде опущена.
Name
roughness
Type
string
Description
Завантажуване посилання на зображення карти шорсткості.
Якщо завдання створено з enable_pbr: false, ця властивість буде опущена.
Name
emission
Type
string
Description
Завантажуване посилання на зображення карти емісії.
Якщо завдання створено з enable_pbr: false, або ai_model є meshy-5, ця властивість буде опущена.
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 (кредити повертаються у разі невдачі).
Example Retexture Task Model
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***" },"text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","image_style_url":"https://assets.meshy.ai/***/image/example_image.jpg?Expires=***","thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"preceding_tasks":0,"task_error": {"message":"" },"consumed_credits":10}