lowpoly будет отключён 30 окт. 2026 г.. Перейдите на другую модель до этих дат, чтобы избежать ошибок в запросах. Все устаревшие функции

UV Unwrap API

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

Результатом является UV белая модель. Она имеет ту же форму, что и исходная модель, новые UV-координаты и не содержит настоящей текстуры. Она включает серый материал-заполнитель размером 2×2, благодаря которому слот материала glTF остаётся корректным, а стандартные инструменты считают её нетекстурированной.

UV-развёртка поддерживает сетки с числом граней до 40 000. Для более крупной модели возвращается 400. Чтобы уменьшить число граней, сначала выполните Ремешинг.

Во время генерации 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.

    Размер файла по ссылке http или https не должен превышать 400 МБ, а в виде Data URI — 100 МБ. Для 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 МБ по ссылке 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

Трансляция задачи UV-развёртки

Передаёт обновления задачи 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-развёртки описывает одну 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

    Подписанные ссылки для скачивания UV белой модели. UV-развёртка всегда возвращает единственный ключ glb. Модель сохраняет исходную геометрию, получает новые UV-координаты и использует стандартный серый материал вместо текстуры.

  • Name
    thumbnail_url
    Type
    string
    Description

    Подписанная ссылка для скачивания 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

    Время истечения срока действия подписанных ссылок для скачивания, в миллисекундах Unix.

  • Name
    task_error
    Type
    object
    Description

    Детали ошибки в случае сбоя задачи. См. Ошибки.

  • Name
    consumed_credits
    Type
    integer
    Description

    Количество кредитов, использованных задачей. Успешная задача UV-развёртки стоит 5 кредитов. Для задачи со статусом FAILED это значение равно 0, так как Meshy возвращает кредиты при сбое задачи.