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 kroku wstępnego przed teksturowaniem — lub za każdym razem, gdy potrzebujesz czystego, nieprzesuniętego układu UV dla narzędzi dalszego przetwarzania (Blender, Substance Painter, Unreal).

Wynikiem jest "biały model UV" — ten sam kształt co wejściowy, ale z nowymi współrzędnymi UV i bez rzeczywistej tekstury (dołączony jest materiał zastępczy 2×2 szary, aby zachować ważność slotu materiału glTF; standardowe narzędzia traktują to jako nieoteksturowane).

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

POST/openapi/v1/uv-unwrap

Utwórz zadanie Rozwinięcie UV

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

Parametry

Dokładnie jeden z input_task_id lub model_url jest wymagany. Jeśli oba są podane, input_task_id ma priorytet.

Name
input_task_id
Type
string
Wymagane
Description
ID zakończonego zadania Meshy API, którego wynik GLB chcesz rozwijać UV (na przykład wynik Obraz na 3D, Tekst na 3D lub Remesh). Źródłowe zadanie musi mieć status SUCCEEDED i wygenerować plik GLB.
Jeśli źródłowa siatka przekracza limit liczby ścianek wynoszący 40 000, żą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 URL lub Data URI. Obsługiwany jest tylko .glb — API odczytuje binarny glTF i nie analizuje innych formatów. Aby rozwijać UV model 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 URL wyjściowy GLB tutaj.
Dla Data URI użyj MIME type application/octet-stream.
Ten sam limit 40 000 ścianek dotyczy 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ęcie UV.

Tryby awarii

Name
400 - Bad Request
Description
Żądanie było nieakceptowalne. Typowe przyczyny:
- Brakujący parametr: Musi być podany input_task_id lub model_url.
- Nieprawidłowe zadanie wejściowe: input_task_id musi odnosić się do zakończonego sukcesem zadania z wynikiem GLB.
- Przekroczona liczba ścianek: Źródłowa siatka ma więcej ścianek niż limit Rozwinięcie UV. Najpierw uruchom Remesh.
- Nieprawidłowy format modelu: model_url wskazuje na plik z nieobsługiwanym rozszerzeniem.
- Nieosiągalny URL: model_url nie mógł zostać pobrany.
Name
401 - Unauthorized
Description
Uwierzytelnianie nie powiodło się. Proszę sprawdzić 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 każde wywołanie.
Name
404 - Not Found
Description
Funkcja nie jest włączona dla Twojego konta. Rozwinięcie UV jest ograniczone przez flagę Statsig podczas wdrażania — skontaktuj się z wsparciem Meshy, jeśli potrzebujesz dostępu.
Name
429 - Too Many Requests
Description
Przekroczyłeś swój 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ęcie UV

Ten punkt końcowy pobiera aktualny stan zadania Rozwinięcie UV według ID.

Zwraca

Zwraca obiekt zadania Rozwinięcie 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 poniżej przykładowy obiekt zadania.

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

Usuń zadanie Rozwinięcie UV

Trwale usuń zadanie Rozwinięcie UV. Zadanie i jego wyniki stają 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

Lista zadań Rozwinięcie UV

Zwraca stronicowaną listę zadań Rozwinięcie 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

Strumieniowanie zadania Rozwinięcie UV

Subskrybuj progress zadania jako zdarzenia wysyłane przez serwer. Każde zdarzenie message niesie obiekt zadania Rozwinięcie UV; strumień zamyka się, gdy zadanie osiągnie SUCCEEDED, FAILED lub CANCELED.

Użyj tego zamiast odpytywania GET /openapi/v1/uv-unwrap/:id dla niższej latencji przy zakoń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ęcia 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 URL do pobrania wygenerowanego białego modelu UV. Rozwinięcie UV zawsze zwraca pojedynczy wpis glb — wynik zachowuje wejściową geometrię, zamienia współrzędne UV na nowe i używa domyślnego szarego materiału zamiast jakiejkolwiek tekstury.
Name
thumbnail_url
Type
string
Description
Wstępnie podpisany URL do podglądu PNG białego modelu UV.
Name
progress
Type
integer
Description
Postęp zadania, od 0 do 100.
Name
status
Type
string
Description
Jeden z PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
preceding_tasks
Type
integer
Description
Liczba zadań w kolejce przed tym. 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 zakończenia, w milisekundach. 0 do momentu zakończenia.
Name
expires_at
Type
timestamp
Description
Znacznik czasu, po którym wygasają podpisane URL do pobrania, w milisekundach.
Name
task_error
Type
object
Description
Szczegóły błędu dla nieudanych zadań. Zobacz Błędy dla pełnej referencji 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 kosztuje 5 kredytów w przypadku sukcesu.

Przykład Obiektu Zadania Rozwinięcia UV

{
  "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
}