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

Створення завдання UV-розгортки

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

Параметри

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

Name
input_task_id
Type
string
Обов'язковий
Description
Ідентифікатор завершеного завдання 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, потім передайте отриманий ідентифікатор завдання як input_task_id або його GLB вихідний URL тут.
Для Data URI використовуйте MIME type application/octet-stream.
Той самий ліміт у 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 не вдалося завантажити.
Name
401 - Unauthorized
Description
Автентифікація не вдалася. Будь ласка, перевірте ваш API key.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання. UV-розгортка коштує 5 кредитів за виклик.
Name
404 - Not Found
Description
Функція не активована для вашого облікового запису. UV-розгортка обмежена прапором Statsig під час розгортання — зверніться до підтримки Meshy, якщо вам потрібен доступ.
Name
429 - Too Many Requests
Description
Ви перевищили своє обмеження частоти.

Запит

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"
    }'

Відповідь

{
  "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-розгортки. Завдання та його результати стають недоступними.

Запит

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
}