Retexture API — це функція, яка дозволяє інтегрувати можливості ШІ-ретекстурування 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 (загальнодоступне посилання або 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-карти (metallic, roughness, normal) на додаток до базового кольору. Карта emission також включається, якщо ai_model — це meshy-6, окрім випадку texture_resolution: 8k. meshy-7 та latest не створюють карту emission.
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 карта emission не створюється.
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
URL-адреса для завантаження файлу текстурованої 3D моделі, згенерованої Meshy.
Name
glb
Type
string
Description
URL-адреса для завантаження файлу GLB.
Name
fbx
Type
string
Description
URL-адреса для завантаження файлу FBX.
Name
obj
Type
string
Description
URL-адреса для завантаження файлу OBJ.
Name
usdz
Type
string
Description
URL-адреса для завантаження файлу USDZ.
Name
mtl
Type
string
Description
URL-адреса для завантаження файлу MTL, що повертається разом з експортом OBJ, коли присутні текстури.
Name
stl
Type
string
Description
URL-адреса для завантаження файлу STL.
Name
3mf
Type
string
Description
URL-адреса для завантаження файлу 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
URL-адреси для завантаження референсних зображень Мультивид, які були використані для створення завдання текстурування. Присутні лише якщо завдання було створено з multiview_image_urls.
Name
thumbnail_url
Type
string
Description
URL-адреса для завантаження мініатюри файлу моделі.
Name
alpha_thumbnail_url
Type
string
Description
URL-адреса для завантаження версії 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 PM 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
URL-адреса для завантаження зображення карти базового кольору.
Name
metallic
Type
string
Description
URL-адреса для завантаження зображення карти металевості.
Якщо завдання створено з enable_pbr: false, ця властивість буде відсутня.
Name
normal
Type
string
Description
URL-адреса для завантаження зображення карти нормалей.
Якщо завдання створено з enable_pbr: false, ця властивість буде відсутня.
Name
roughness
Type
string
Description
URL-адреса для завантаження зображення карти шорсткості.
Якщо завдання створено з enable_pbr: false, ця властивість буде відсутня.
Name
emission
Type
string
Description
URL-адреса для завантаження зображення карти випромінювання.
Якщо завдання створено з 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}