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

Create an UV Unwrap Task

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

Zadanie działa w tle. Informacje o tym, jak długo to zwykle trwa, znajdziesz w Czasach przetwarzania.

Parametry

Wymagane jest dokładnie jedno z pól 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 musi wygenerować plik GLB.
Jeśli siatka źródłowa przekracza limit 40 000 ścianek, żądanie zostanie odrzucone z kodem 400 i w takim przypadku należy najpierw uruchomić Remesh, aby zmniejszyć liczbę wielokątów.

Name
model_url
Type
string
Wymagane
Description
Podaj model 3D bezpośrednio poprzez publicznie dostępny adres URL lub Data URI. Obsługiwany jest wyłącznie format .glb — API odczytuje binarny glTF i nie parsuje innych formatów. Aby poddać Rozwinięciu UV model w innym formacie (.fbx, .obj, .stl, .gltf), najpierw przekonwertuj go do .glb za pomocą Convert API, a następnie przekaż tutaj ID powstałego zadania jako input_task_id lub adres URL jego wyniku GLB.
W przypadku Data URI użyj MIME type application/octet-stream.
Maksymalny rozmiar pliku: 400 MB dla adresu URL http lub https, 100 MB dla URI data:. Plik GLB przekraczający 100 MB nie może używać kompresji Draco.
Obowiązuje ten sam limit 40 000 ścianek co w przypadku input_task_id: zbyt duże siatki są odrzucane z kodem 400 — najpierw uruchom Remesh.

Zwracane wartości

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

Tryby niepowodzenia

Name
400 - Bad Request
Description
Żądanie było nieprawidłowe. Typowe przyczyny:
- Brak parametru: Należy podać input_task_id lub model_url.
- Nieprawidłowe zadanie wejściowe: input_task_id musi wskazywać na zakończone powodzeniem zadanie z wynikiem GLB.
- Przekroczona liczba ścianek: Siatka źródłowa ma więcej ścianek niż limit Rozwinięcia UV. Najpierw uruchom Remesh.
- Nieprawidłowy format modelu: model_url wskazuje na plik o nieobsługiwanym rozszerzeniu.
- Niedostępny adres URL: Nie udało się pobrać pliku spod model_url.
- Plik modelu zbyt duży: Plik pod model_url przekracza 400 MB (adres URL http lub https) lub 100 MB (URI data:).
- Zbyt wiele ścianek: Plik pod model_url ma ponad 100 MB i więcej niż 10 000 000 ścianek. Zmniejsz liczbę ścianek i wyślij plik ponownie.
- Nieczytelny plik modelu: Plik pod model_url ma ponad 100 MB i nie można odczytać jego nagłówka, na przykład w przypadku pliku GLB skompresowanego za pomocą Draco.
- Nagłówek modelu zbyt złożony: Plik pod model_url ma ponad 100 MB, a jego nagłówek zawiera zbyt wiele siatek, węzłów lub rekordów do sprawdzenia. Zmniejsz liczbę obiektów w pliku i wyślij go ponownie.
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
Ta funkcja nie jest włączona dla Twojego konta. Rozwinięcie UV jest objęte 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ę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ęcia UV

Trwale usuwa zadanie Rozwinięcia UV. Zadanie i jego wyniki stają się niedostępne.

Zadanie, które nadal ma status PENDING, zostaje usunięte, a kredyty zużyte w momencie tworzenia są zwracane.

Zadanie, które jest już w stanie IN_PROGRESS, nie może zostać usunięte: żądanie jest odrzucane z kodem 409 Conflict, a zadanie nadal działa. Kredyty za zadanie, które worker już rozpoczął, nie podlegają zwrotowi, więc usunięcie go w trakcie wykonywania kosztowałoby Cię zarówno kredyty, jak i wynik. Poczekaj, aż osiągnie status SUCCEEDED, FAILED lub CANCELED, a następnie je usuń.

Zadanie w stanie końcowym (SUCCEEDED, FAILED lub CANCELED) zostaje usunięte bez zwrotu kredytów.

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
}