UV Unwrap API

Згенеруйте UV-розгортку для наявної 3D-моделі. Запускайте її перед текстуруванням моделі або коли такому інструменту, як Blender, Substance Painter чи Unreal, потрібна чиста UV-розкладка без накладень.

Результатом є UV біла модель. Вона має таку саму форму, як і вхідна модель, свіжі UV-координати та без справжньої текстури. Вона містить сірий заповнювач-матеріал розміром 2×2, щоб слот матеріалу glTF залишався дійсним, а стандартні інструменти сприймали її як нетекстуровану.

UV-розгортка підтримує сітки з кількістю граней до 40 000. Для більшої моделі повертається 400. Щоб зменшити кількість граней, спочатку запустіть Remesh.

Під час генерації UV Meshy тріангулює сітки з чотирикутниками та n-кутниками, тож результатом завжди є трикутна сітка.

POST/openapi/v1/uv-unwrap

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

Створює задачу UV-розгортки.

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

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

Параметри

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

Name
model_url
Type
string
Обов'язковий
Description
Обов'язковий, якщо не надіслано input_task_id. Модель для розгортки у вигляді публічної URL-адреси або data URI. Якщо надіслано обидва параметри, Meshy використовує input_task_id.
Модель повинна бути файлом .glb. Щоб розгорнути інший формат, спершу конвертуйте його у GLB за допомогою Convert API.
Файл може бути розміром не більше 400 МБ, якщо це URL-адреса http або https, або не більше 100 МБ як data URI. Для data URI використовуйте MIME type application/octet-stream. 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 не є успішною задачею API з результатом у форматі GLB.
- Перевищено кількість граней: сітка має більше граней, ніж дозволяє UV-розгортка. Спершу виконайте Ремеш.
- Недійсний формат моделі: файл model_url має непідтримуване розширення.
- Недоступна URL-адреса: Meshy не може завантажити файл за адресою model_url.
- Файл моделі завеликий: файл model_url перевищує 400 МБ для URL-адреси http або https, або 100 МБ як data URI.
- Забагато граней: файл model_url перевищує 100 МБ і має більше ніж 10 000 000 граней. Зменшіть кількість граней і надішліть файл знову.
- Файл моделі неможливо прочитати: файл model_url перевищує 100 МБ, і Meshy не може прочитати його заголовок. Наприклад, це GLB зі стисненням Draco.
- Заголовок моделі занадто складний: файл model_url перевищує 100 МБ, і його заголовок містить забагато сіток, вузлів або записів для перевірки. Зменшіть кількість об'єктів у файлі й надішліть його знову.
Виправте запит і надішліть його знову. Див. Помилки.
Name
401 - Unauthorized
Description
API-ключ відсутній або недійсний. Перевірте заголовок Authorization.
Name
402 - Payment Required
Description
Наприклад:
- Недостатньо кредитів: на обліковому записі недостатньо кредитів для цієї задачі, або обліковий запис досяг ліміту кредитів. Задача UV-розгортки коштує 5 кредитів. Перевірте баланс кредитів і повторіть спробу.
- Безкоштовний план: для створення задачі потрібен платний план. Оновіть свій план у налаштуваннях підписки, а потім повторіть спробу.
Name
403 - Forbidden
Description
input_task_id є моделлю барельєфу, яку ця кінцева точка не може розгорнути. Повідомлення: This model type does not support this operation. Надішліть іншу модель.
Name
404 - Not Found
Description
input_task_id не відповідає жодній із ваших задач. Перевірте ID задачі й надішліть запит знову.
Name
429 - Too Many Requests
Description
Ви перевищили обмеження частоти. Зачекайте, а потім повторіть спробу. Див. Обмеження частоти.

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

Отримати задачу UV-розгортки

Повертає поточний стан задачі UV-розгортки за її ID.

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

Приклад відповіді дивіться у прикладі об'єкта задачі UV-розгортки.

Повертає

Об'єкт задачі UV-розгортки.

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

Статус задачі

Видалення задачі зі статусом PENDING повертає кредити, витрачені на її створення.

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

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

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

Stream a UV Unwrap task

Транслює оновлення завдання UV-розгортки у вигляді подій Server-Sent Events (SSE). Кожна подія 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-розгортки

Об'єкт завдання UV Unwrap описує одну UV-розгортку 3D-моделі. Він містить статус, progress і файл моделі, коли завдання завершується успішно.

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
}

Name
id
Type
string
Description
ID завдання. Сприймайте його як непрозорий рядок і не покладайтеся на його формат.
Name
type
Type
string
Description
Тип завдання, завжди uv-unwrap.
Name
model_urls
Type
object
Description
Підписані URL-адреси для завантаження UV білої моделі. UV Unwrap завжди повертає єдиний ключ 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
Час створення завдання, у мілісекундах Unix.
Name
started_at
Type
timestamp
Description
Час початку виконання завдання, у мілісекундах Unix. Дорівнює 0, доки завдання не почнеться.
Name
finished_at
Type
timestamp
Description
Час завершення завдання, у мілісекундах Unix. Дорівнює 0, доки завдання не завершиться.
Name
expires_at
Type
timestamp
Description
Час, коли закінчується термін дії підписаних URL-адрес для завантаження, у мілісекундах Unix.
Name
task_error
Type
object
Description
Деталі помилки, коли завдання завершується невдало. Див. Помилки.
Name
consumed_credits
Type
integer
Description
Кількість кредитів, витрачених на завдання. Успішне завдання UV Unwrap коштує 5 кредитів. Дорівнює 0 для завдання зі статусом FAILED, оскільки Meshy повертає кредити, якщо завдання завершується невдало.