API UV-розгортки

API UV-розгортки автоматично генерує високоякісну UV-розгортку для існуючої 3D моделі. Використовуйте це як попередній крок перед текстуруванням — або будь-коли, коли вам потрібна чиста, без перекриттів UV-розкладка для подальших інструментів (Blender, Substance Painter, Unreal).

Вихідний результат — це "UV біла модель" — та сама форма, що й вхідна, але з новими UV-координатами та без реальної текстури (включено матеріал-заповнювач 2×2 сірого кольору, щоб зберегти слот матеріалу glTF дійсним; стандартні інструменти трактують це як нетекстуроване).

Обмеження. Авто UV наразі підтримує сітки до 40,000 граней — більші моделі відхиляються з 400; спочатку запустіть Ремеш, щоб зменшити кількість полігонів. Квадратні та n-кутні сітки триангуляються під час генерації UV, тому вихід завжди є трикутною сіткою.

POST/openapi/v1/uv-unwrap

Create an UV Unwrap Task

Ця кінцева точка створює нове завдання UV-розгортки.

Завдання виконується у фоновому режимі. Про те, скільки це зазвичай триває, див. Час обробки.

Параметри

Потрібен рівно один із параметрів input_task_id або model_url. Якщо вказано обидва, пріоритет має input_task_id.

Name
input_task_id
Type
string
Обов'язковий
Description
ID завершеного завдання Meshy API, чий результат у форматі GLB ви хочете піддати UV-розгортці (наприклад, результат Зображення у 3D, Текст у 3D або Ремеш). Вихідне завдання повинно мати статус SUCCEEDED і повинно було створити файл GLB.
Якщо вихідна сітка перевищує стелю в 40 000 граней, запит буде відхилено з кодом 400, і вам слід спочатку виконати Ремеш, щоб зменшити кількість полігонів.

Name
model_url
Type
string
Обов'язковий
Description
Надайте 3D-модель безпосередньо через публічно доступну URL-адресу або data URI. Підтримується лише .glb — API зчитує glTF у двійковому форматі й не розбирає інші формати. Щоб виконати UV-розгортку моделі в іншому форматі (.fbx, .obj, .stl, .gltf), спочатку конвертуйте її у .glb через Convert API, а потім передайте отриманий ID завдання як input_task_id або URL-адресу його результату GLB тут.
Для Data URI використовуйте MIME type application/octet-stream.
Максимальний розмір файлу: 400 МБ для URL-адреси http або https, 100 МБ для data: URI. GLB розміром понад 100 МБ не повинен використовувати стиснення Draco.
Діє та сама стеля в 40 000 граней, що й для input_task_id: завеликі сітки відхиляються з кодом 400 — спочатку виконайте Ремеш.

Результати

Властивість result у відповіді містить id щойно створеного завдання UV-розгортки.

Режими збою

Name
400 - Bad Request
Description
Запит був неприйнятним. Поширені причини:
- Відсутній параметр: Необхідно надати input_task_id або model_url.
- Недійсне вихідне завдання: input_task_id повинен посилатися на успішне завдання з результатом у форматі GLB.
- Перевищено кількість граней: Вихідна сітка має більше граней, ніж стеля для UV-розгортки. Спочатку виконайте Ремеш.
- Недійсний формат моделі: model_url посилається на файл з непідтримуваним розширенням.
- Недоступна URL-адреса: Не вдалося завантажити файл за адресою model_url.
- Файл моделі занадто великий: Файл model_url перевищує 400 МБ (URL-адреса http або https) або 100 МБ (data: URI).
- Забагато граней: Файл model_url перевищує 100 МБ і має більше ніж 10 000 000 граней. Зменшіть кількість граней, а потім надішліть файл знову.
- Непридатний для читання файл моделі: Файл model_url перевищує 100 МБ, і його заголовок неможливо прочитати, наприклад, GLB зі стисненням Draco.
- Заголовок моделі занадто складний: Файл model_url перевищує 100 МБ, і його заголовок містить забагато сіток, вузлів або записів для перевірки. Зменшіть кількість об'єктів у файлі, а потім надішліть його знову.
Name
401 - Unauthorized
Description
Автентифікація не вдалася. Будь ласка, перевірте свій API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання. UV-розгортка коштує 5 кредитів за виклик.
Name
404 - Not Found
Description
Ця функція не ввімкнена для вашого облікового запису. UV-розгортка контролюється прапорцем Statsig під час поступового впровадження — зверніться до служби підтримки Meshy, якщо вам потрібен доступ.
Name
429 - Too Many Requests
Description
Ви перевищили обмеження частоти.

Request

POST

/openapi/v1/uv-unwrap

# Chain from an existing Meshy task
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "input_task_id": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
    }'

# Or from a publicly accessible model URL
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "model_url": "https://example.com/path/to/model.glb"
    }'

Response

{
  "result": "019361c6-9b34-7b23-bef2-d0107c4d92e2"
}

GET/openapi/v1/uv-unwrap/:id

Отримання завдання UV-розгортки

Ця кінцева точка отримує поточний стан завдання UV-розгортки за ID.

Повертає

Повертає об'єкт завдання UV-розгортки.

Запит

GET

/openapi/v1/uv-unwrap/:id

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Дивіться приклад об'єкта завдання нижче.

DELETE/openapi/v1/uv-unwrap/:id

Видалити задачу UV-розгортки

Остаточно видалити задачу UV-розгортки. Задача та її результати стають недоступними.

Задача, яка все ще має статус PENDING, видаляється, а кредити, витрачені під час створення, повертаються.

Задачу, яка вже має статус IN_PROGRESS, видалити неможливо: запит відхиляється з кодом 409 Conflict, а задача продовжує виконуватися. Кредити за задачу, яку воркер уже почав виконувати, не підлягають поверненню, тому видалення її під час виконання коштуватиме вам і кредитів, і результату. Дочекайтеся, поки вона досягне статусу SUCCEEDED, FAILED або CANCELED, а потім видаліть її.

Задача у кінцевому стані (SUCCEEDED, FAILED або CANCELED) видаляється без повернення коштів.

Request

DELETE

/openapi/v1/uv-unwrap/:id

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/uv-unwrap

Перелік завдань UV-розгортки

Повертає пагінований список завдань UV-розгортки викликувача, починаючи з найновіших. Стандартна пагінація через page_num та page_size.

Request

GET

/openapi/v1/uv-unwrap

curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/uv-unwrap/:id/stream

Потокове передавання завдання UV-розгортка

Підписка на progress завдання як події, що надсилаються сервером. Кожна подія message несе об'єкт завдання UV-розгортка; потік закривається, коли завдання досягає SUCCEEDED, FAILED або CANCELED.

Використовуйте це замість опитування GET /openapi/v1/uv-unwrap/:id для зменшення затримки при завершенні.

Запит

GET

/openapi/v1/uv-unwrap/:id/stream

curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-N

Об'єкт завдання UV-розгортки

Name
id
Type
string
Description
Унікальний ідентифікатор для завдання.
Name
type
Type
string
Description
Завжди uv-unwrap.
Name
model_urls
Type
object
Description
Попередньо підписані URL-адреси для завантаження згенерованої UV білої моделі. UV-розгортка завжди повертає один запис glb — вихідний файл зберігає вхідну геометрію, замінює нові UV-координати та використовує матеріал сірого кольору замість будь-якої текстури.
Name
thumbnail_url
Type
string
Description
Попередньо підписана URL-адреса для PNG-прев'ю UV білої моделі.
Name
progress
Type
integer
Description
Прогрес завдання, від 0 до 100.
Name
status
Type
string
Description
Один з PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
preceding_tasks
Type
integer
Description
Кількість завдань, що стоять у черзі перед цим. Присутній, коли статус PENDING.
Name
created_at
Type
timestamp
Description
Мітка часу створення завдання, в мілісекундах.
Name
started_at
Type
timestamp
Description
Мітка часу початку обробки, в мілісекундах. 0 до початку.
Name
finished_at
Type
timestamp
Description
Мітка часу завершення, в мілісекундах. 0 до завершення.
Name
expires_at
Type
timestamp
Description
Мітка часу, після якої підписані URL-адреси для завантаження стають недійсними, в мілісекундах.
Name
task_error
Type
object
Description
Деталі помилки для невдалих завдань. Див. Помилки для повної довідки по об'єкту task_error.
Name
consumed_credits
Type
integer
Description
Кредити, спожиті цим завданням. Повертає 0 для завдань зі статусом FAILED (кредити повертаються у разі невдачі). UV-розгортка стягує 5 кредитів у разі успіху.

Приклад об'єкта завдання UV-розгортки

{
  "id": "019361c6-9b34-7b23-bef2-d0107c4d92e2",
  "type": "uv-unwrap",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1716579120000,
  "started_at": 1716579122000,
  "finished_at": 1716579180000,
  "expires_at": 1716665580000,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 5
}