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 или его 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-ключ.

  • 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.

Запрос

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
}