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

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 через 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

Delete an UV Unwrap Task

Безвозвратно удаляет задачу 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.

Запрос

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-адрес для предварительного просмотра UV белой модели в формате PNG.

  • 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 кредитов при успешном выполнении.

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
}