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-розгортки

Ця кінцева точка створює нове завдання 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 через API Конвертувати, а потім передайте ID отриманого завдання як input_task_id або його URL-адресу виводу GLB тут.
Для 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-ключ.
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-розгортки.

Request

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

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 завдання як Server-Sent Events. Кожна подія message містить об’єкт завдання UV-розгортки; потік закривається, щойно завдання досягає SUCCEEDED, FAILED або CANCELED.

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

Request

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-адреса для попереднього перегляду UV білої моделі у форматі PNG.
Name
progress
Type
integer
Description
progress завдання, від 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 кредитів у разі успіху.

Example UV Unwrap Task Object

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