API Rozwinięcia UV

API Rozwinięcia UV automatycznie generuje wysokiej jakości rozwinięcie UV dla istniejącego modelu 3D. Użyj go jako wymaganego kroku przed teksturowaniem — lub zawsze wtedy, gdy potrzebujesz czystego, nienakładającego się układu UV dla narzędzi używanych dalej w procesie (Blender, Substance Painter, Unreal).

Wynikiem jest „biały model UV” — o takim samym kształcie jak dane wejściowe, ale z całkowicie nowymi współrzędnymi UV i bez prawdziwej tekstury (dołączony jest szary materiał zastępczy 2×2, aby zachować prawidłowy slot materiału glTF; standardowe narzędzia traktują to jako model bez tekstury).

Ograniczenia. Automatyczne UV obecnie obsługuje siatki do 40 000 ścian — większe modele są odrzucane z kodem 400; najpierw uruchom Remesh, aby zmniejszyć liczbę wielokątów. Siatki z czworokątami i n-gonami są triangulowane podczas generowania UV, więc wynikiem jest zawsze siatka trójkątów.

POST/openapi/v1/uv-unwrap

Utwórz zadanie Rozwinięcia UV

Ten punkt końcowy tworzy nowe zadanie Rozwinięcia UV.

Parametry

Wymagany jest dokładnie jeden z parametrów input_task_id lub model_url. Jeśli podano oba, input_task_id ma priorytet.

Name
input_task_id
Type
string
Wymagane
Description
ID ukończonego zadania Meshy API, którego wynik GLB chcesz poddać Rozwinięciu UV (na przykład wynik Obraz na 3D, Tekst na 3D lub Remesh). Zadanie źródłowe musi mieć status SUCCEEDED i wygenerować plik GLB.
Jeśli siatka źródłowa przekracza limit 40 000 ścian, żądanie zostanie odrzucone z kodem 400 i należy najpierw uruchomić Remesh, aby zmniejszyć liczbę wielokątów.

Name
model_url
Type
string
Wymagane
Description
Podaj model 3D bezpośrednio za pomocą publicznie dostępnego adresu URL lub Data URI. Obsługiwane jest tylko .glb — API odczytuje binarny glTF i nie analizuje innych formatów. Aby wykonać Rozwinięcie UV modelu w innym formacie (.fbx, .obj, .stl, .gltf), najpierw przekonwertuj go na .glb za pomocą Convert API, a następnie przekaż wynikowy ID zadania jako input_task_id lub jego wyjściowy adres URL GLB tutaj.
W przypadku Data URI użyj MIME type application/octet-stream.
Obowiązuje ten sam limit 40 000 ścian co dla input_task_id: zbyt duże siatki są odrzucane z kodem 400 — najpierw uruchom Remesh.

Zwraca

Właściwość result odpowiedzi zawiera id nowo utworzonego zadania Rozwinięcia UV.

Tryby niepowodzenia

Name
400 - Bad Request
Description
Żądanie było niedopuszczalne. Typowe przyczyny:
- Brakujący parametr: Należy podać input_task_id albo model_url.
- Nieprawidłowe zadanie wejściowe: input_task_id musi odnosić się do zadania zakończonego powodzeniem z wynikiem GLB.
- Przekroczono liczbę ścian: Siatka źródłowa ma więcej ścian niż limit Rozwinięcia UV. Najpierw uruchom Remesh.
- Nieprawidłowy format modelu: model_url wskazuje plik z nieobsługiwanym rozszerzeniem.
- Nieosiągalny URL: Nie można było pobrać model_url.
Name
401 - Unauthorized
Description
Uwierzytelnianie nie powiodło się. Sprawdź swój klucz API.
Name
402 - Payment Required
Description
Niewystarczająca liczba kredytów do wykonania tego zadania. Rozwinięcie UV kosztuje 5 kredytów za wywołanie.
Name
404 - Not Found
Description
Funkcja nie jest włączona dla Twojego konta. Rozwinięcie UV jest ograniczone flagą Statsig podczas wdrażania — skontaktuj się z pomocą techniczną Meshy, jeśli potrzebujesz dostępu.
Name
429 - Too Many Requests
Description
Przekroczono limit szybkości.

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

Pobierz zadanie Rozwinięcia UV

Ten punkt końcowy pobiera bieżący stan zadania Rozwinięcia UV według identyfikatora.

Zwraca

Zwraca obiekt zadania Rozwinięcia 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}"

Zobacz przykładowy obiekt zadania poniżej.

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

Usuń zadanie Rozwinięcia UV

Trwale usuń zadanie Rozwinięcia UV. Zadanie i jego wyniki staną się niedostępne.

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

Wyświetl listę zadań Rozwinięcia UV

Zwraca stronicowaną listę zadań Rozwinięcia UV wywołującego, od najnowszych. Standardowe stronicowanie za pomocą page_num i 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

Strumieniuj zadanie Rozwinięcia UV

Subskrybuj progress zadania jako Server-Sent Events. Każde zdarzenie message zawiera obiekt zadania Rozwinięcia UV; strumień zostaje zamknięty, gdy zadanie osiągnie stan SUCCEEDED, FAILED lub CANCELED.

Użyj tego zamiast odpytywania GET /openapi/v1/uv-unwrap/:id, aby uzyskać mniejsze opóźnienie przy ukończeniu.

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

Obiekt zadania Rozwinięcie UV

Name
id
Type
string
Description
Unikalny identyfikator zadania.
Name
type
Type
string
Description
Zawsze uv-unwrap.
Name
model_urls
Type
object
Description
Wstępnie podpisane adresy URL pobierania dla wygenerowanego białego modelu UV. Rozwinięcie UV zawsze zwraca pojedynczy wpis glb — dane wyjściowe zachowują wejściową geometrię, zastępują ją świeżymi współrzędnymi UV i używają domyślnego szarego materiału zamiast dowolnej tekstury.
Name
thumbnail_url
Type
string
Description
Wstępnie podpisany adres URL do podglądu PNG białego modelu UV.
Name
progress
Type
integer
Description
Progress zadania, od 0 do 100.
Name
status
Type
string
Description
Jedna z wartości: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
preceding_tasks
Type
integer
Description
Liczba zadań w kolejce przed tym zadaniem. Obecne, gdy status to PENDING.
Name
created_at
Type
timestamp
Description
Znacznik czasu utworzenia zadania, w milisekundach.
Name
started_at
Type
timestamp
Description
Znacznik czasu rozpoczęcia przetwarzania, w milisekundach. 0 do momentu rozpoczęcia.
Name
finished_at
Type
timestamp
Description
Znacznik czasu ukończenia, w milisekundach. 0 do momentu zakończenia.
Name
expires_at
Type
timestamp
Description
Znacznik czasu, po którym podpisane adresy URL pobierania wygasają, w milisekundach.
Name
task_error
Type
object
Description
Szczegóły błędu dla zadań zakończonych niepowodzeniem. Zobacz Błędy, aby uzyskać pełną dokumentację obiektu task_error.
Name
consumed_credits
Type
integer
Description
Kredyty zużyte przez to zadanie. Zwraca 0 dla zadań FAILED (kredyty są zwracane w przypadku niepowodzenia). Rozwinięcie UV pobiera 5 kredytów w przypadku powodzenia.

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
}