API UV-развёртки

API UV-развёртки автоматически генерирует высококачественную UV-развёртку для существующей 3D-модели. Используйте её как обязательный предварительный шаг перед текстурированием — или в любой момент, когда вам нужна чистая, непересекающаяся UV-раскладка для последующих инструментов (Blender, Substance Painter, Unreal).

Выходной результат — это "UV белая модель": та же форма, что и у входной модели, но с совершенно новыми UV-координатами и без настоящей текстуры (включён серый материал-заполнитель 2×2, чтобы слот материала glTF оставался действительным; стандартные инструменты воспринимают это как отсутствие текстуры).

Ограничения. Auto 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.

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

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