Retexture API — це функція, яка дозволяє інтегрувати можливості AI-ретекстурування Meshy у ваш власний додаток. У цьому розділі ви знайдете всю необхідну інформацію для початку роботи з цим API.
Цей endpoint дозволяє створити нове завдання для Ретекстурування. Зверніться до Об'єкт Завдання Ретекстурування, щоб побачити, які властивості входять до об'єкта завдання Ретекстурування.
Параметри
Лише один з параметрів input_task_id або model_url є обов'язковим. Якщо обидва надано, пріоритет має input_task_id.
Name
input_task_id
Type
string
Обов'язковий
Description
ID завершеного завдання Зображення у 3D або Текст у 3D, яке ви бажаєте зретекстурувати.
Це завдання має бути одним з наступних: Текст у 3D Попередній перегляд, Текст у 3D Уточнення, Зображення у 3D або Ремеш. Крім того, воно повинно мати статус SUCCEEDED.
Name
model_url
Type
string
Обов'язковий
Description
Надайте 3D модель, щоб Meshy міг її покрити текстурою. Підтримувані формати: .glb, .gltf, .obj, .fbx, .stl.
Є два способи надати модель:
Загальнодоступний URL: URL, доступний з Інтернету.
Data URI: Base64-кодований Data URI моделі. Використовуйте MIME type application/octet-stream. Приклад: data:application/octet-stream;base64,<your base64-encoded model data>.
Рівно один стильовий вхід є обов'язковим: 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
Опишіть бажаний стиль текстури об'єкта за допомогою тексту. Максимум 600 символів.
Name
image_style_url
Type
string
Обов'язковий
Description
Надайте 2D-зображення, щоб керувати процесом текстурування. Ми підтримуємо формати .jpg, .jpeg, і .png.
Є два способи надати зображення:
Загальнодоступний URL: URL, доступний з Інтернету
Data URI: Base64-кодований Data URI зображення. Приклад Data URI: data:image/jpeg;base64,<your base64-encoded image data>
Текстурування зображень може працювати не оптимально, якщо є значні відмінності в геометрії між оригінальним asset'ом і завантаженим зображенням.
Name
multiview_image_urls
Type
string[]
Обов'язковий
Description
Надайте від 1 до 4 зображень, що показують той самий об'єкт з різних ракурсів для керування текстуруванням. Перше зображення — це основний (фронтальний) вид; порядок інших виглядів (ліве, заднє, праве) не має значення.
Кожен елемент приймає ті самі формати, що і image_style_url (загальнодоступний URL або Base64, .jpg/.jpeg/.png).
Потрібно ai_model: "meshy-7" (або latest).
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-карти (металічність, шорсткість, карта нормалей) на додаток до основного кольору. Карта емісії також включена, коли 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" (або latest).
Модель недоступна: 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
# Ретекстурування з текстовим 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 }'# Ретекстурування з стилем зображення та 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 }'
Цей endpoint дозволяє отримати завдання Ретекстурування за вказаним дійсним 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
Унікальний ідентифікатор завдання. Хоча ми використовуємо UUID, що сортується по ключу, для ідентифікаторів завдань як деталь реалізації, ви не повинні робити жодних припущень щодо формату ідентифікатора.
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 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 завдань (кредити повертаються при невдачі).
Приклад Моделі Завдання Ретекстурування
{"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}