UV Unwrap API

Wygeneruj Rozwinięcie UV dla istniejącego modelu 3D. Uruchom je przed teksturowaniem modelu lub gdy narzędzie takie jak Blender, Substance Painter czy Unreal wymaga czystego, nienakładającego się układu UV.

Wynikiem jest biały model UV. Ma ten sam kształt co model wejściowy, nowe współrzędne UV i brak rzeczywistej tekstury. Zawiera placeholder materiału w postaci szarej siatki 2×2, dzięki czemu gniazdo materiału glTF pozostaje prawidłowe, a standardowe narzędzia traktują go jako nieteksturowany.

Rozwinięcie UV obsługuje siatki o maksymalnie 40 000 ścianek. Większy model zwraca 400. Aby zmniejszyć liczbę ścianek, uruchom najpierw Remesh.

Meshy triangularyzuje siatki składające się z czworokątów i n-kątów podczas generowania UV, dzięki czemu wynikowa siatka zawsze jest siatką trójkątów.

POST/openapi/v1/uv-unwrap

Utwórz zadanie Rozwinięcia UV

Tworzy zadanie Rozwinięcia UV.

Zadanie działa w tle. Informacje o tym, ile zwykle trwa zadanie, znajdziesz w sekcji Czasy przetwarzania.

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

Parametry

Name
input_task_id
Type
string
Wymagane
Description
Wymagane, chyba że wyślesz model_url. ID zadania Meshy API, którego wynik GLB chcesz rozwinąć, na przykład zadania Obraz na 3D, Tekst na 3D lub Remesh. Zadanie musi mieć status SUCCEEDED i musi wygenerować plik GLB.
Siatka może mieć co najwyżej 40 000 ścianek. Siatka z większą liczbą ścianek zwraca 400. Aby zmniejszyć liczbę ścianek, najpierw uruchom Remesh.

Name
model_url
Type
string
Wymagane
Description
Wymagane, chyba że wyślesz input_task_id. Model do rozwinięcia, podany jako publiczny URL lub Data URI. Jeśli wyślesz oba parametry, Meshy użyje input_task_id.
Model musi być plikiem .glb. Aby rozwinąć inny format, najpierw przekonwertuj go na GLB za pomocą Convert API.
Plik może mieć maksymalnie 400 MB, jeśli pochodzi z adresu URL http lub https, lub 100 MB jako Data URI. W przypadku Data URI użyj MIME type application/octet-stream. Plik GLB powyżej 100 MB nie może używać kompresji Draco.
Obowiązuje ten sam limit 40 000 ścianek co w przypadku input_task_id. Siatka z większą liczbą ścianek zwraca 400, więc najpierw uruchom Remesh.

Zwracana wartość

Pole result w odpowiedzi zawiera ID nowego zadania Rozwinięcia UV.

Tryby niepowodzenia

Name
400 - Bad Request
Description
Żądanie nie może zostać wykonane. Komunikat błędu wskazuje, jaki problem wykryto. Na przykład:
- Brakujący parametr: Nie wysłano ani input_task_id, ani model_url.
- Nieprawidłowe zadanie wejściowe: input_task_id nie jest zakończonym powodzeniem zadaniem API z wynikiem GLB.
- Przekroczona liczba ścianek: Siatka ma więcej ścianek, niż dopuszcza Rozwinięcie UV. Najpierw uruchom Remesh.
- Nieprawidłowy format modelu: Plik model_url ma nieobsługiwane rozszerzenie.
- Nieosiągalny URL: Meshy nie może pobrać pliku spod model_url.
- Zbyt duży plik modelu: Plik model_url ma ponad 400 MB, jeśli pochodzi z adresu URL http lub https, lub ponad 100 MB jako Data URI.
- Zbyt wiele ścianek: Plik model_url ma ponad 100 MB i więcej niż 10 000 000 ścianek. Zmniejsz liczbę ścianek i wyślij plik ponownie.
- Nieodczytywalny plik modelu: Plik model_url ma ponad 100 MB, a Meshy nie może odczytać jego nagłówka. Na przykład jest to plik GLB skompresowany za pomocą Draco.
- Zbyt złożony nagłówek modelu: Plik 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.
Popraw żądanie i wyślij je ponownie. Zobacz Błędy.
Name
401 - Unauthorized
Description
Brak klucza API lub jest on nieprawidłowy. Sprawdź nagłówek Authorization.
Name
402 - Payment Required
Description
Na przykład:
- Niewystarczające kredyty: Konto nie ma wystarczającej liczby kredytów na to zadanie lub konto osiągnęło limit kredytów. Zadanie Rozwinięcia UV kosztuje 5 kredytów. Sprawdź saldo kredytów, a następnie spróbuj ponownie.
- Plan darmowy: Utworzenie zadania wymaga płatnego planu. Uaktualnij swój plan w ustawieniach subskrypcji, a następnie spróbuj ponownie.
Name
403 - Forbidden
Description
input_task_id wskazuje na model płaskorzeźby, którego ten punkt końcowy nie może rozwinąć. Komunikat brzmi This model type does not support this operation. Wyślij inny model.
Name
404 - Not Found
Description
input_task_id nie pasuje do żadnego z Twoich zadań. Sprawdź ID zadania i wyślij żądanie ponownie.
Name
429 - Too Many Requests
Description
Przekroczono limit szybkości. Poczekaj, a następnie spróbuj ponownie. Zobacz Limity szybkości.

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

Pobierz zadanie Rozwinięcia UV

Zwraca bieżący stan zadania Rozwinięcia UV na podstawie jego ID.

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

Przykładową odpowiedź znajdziesz w przykładowym obiekcie zadania Rozwinięcia UV.

Zwraca

Obiekt zadania Rozwinięcia UV.

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

Usuń zadanie Rozwinięcia UV

Trwale usuwa zadanie Rozwinięcia UV, łącznie z jego wynikami. Nie można cofnąć usunięcia.

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

Status zadania

Usunięcie zadania o statusie PENDING zwraca kredyty użyte przy jego tworzeniu.

Zadania o statusie IN_PROGRESS nie można usunąć. Żądanie zwraca 409 Conflict, a zadanie nadal się wykonuje. Meshy nie zwraca kredytów za zadanie, które zostało uruchomione, więc jego usunięcie kosztowałoby Cię zarówno kredyty, jak i wynik. Poczekaj, aż osiągnie status SUCCEEDED, FAILED lub CANCELED, a następnie je usuń.

Usunięcie zadania o statusie końcowym (SUCCEEDED, FAILED lub CANCELED) nie zwraca za nie kredytów.

GET/openapi/v1/uv-unwrap

Lista zadań Rozwinięcia UV

Zwraca podzieloną na strony listę Twoich zadań Rozwinięcia UV, od najnowszych. Aby przeglądać listę strona po stronie, użyj 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

Streamowanie zadania Rozwinięcia UV

Strumieniuje aktualizacje zadania Rozwinięcia UV jako zdarzenia Server-Sent Events (SSE). Każde zdarzenie message zawiera obiekt zadania Rozwinięcia UV. Strumień zamyka się, gdy zadanie osiągnie status SUCCEEDED, FAILED lub CANCELED.

Aby szybciej dowiedzieć się, że zadanie zostało zakończone, użyj tego punktu końcowego zamiast odpytywania 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

Obiekt zadania Rozwinięcia UV

Obiekt zadania Rozwinięcia UV opisuje jedno rozwinięcie UV modelu 3D. Zawiera status, progress oraz plik modelu, gdy zadanie zakończy się powodzeniem.

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
}

Name
id
Type
string
Description
ID zadania. Traktuj je jako nieprzezroczysty ciąg znaków i nie polegaj na jego formacie.
Name
type
Type
string
Description
Typ zadania, zawsze uv-unwrap.
Name
model_urls
Type
object
Description
Podpisane adresy URL do pobrania białego modelu UV. Rozwinięcie UV zawsze zwraca pojedynczy klucz glb. Model zachowuje geometrię wejściową, posiada nowe współrzędne UV i korzysta z domyślnego szarego materiału zamiast tekstury.
Name
thumbnail_url
Type
string
Description
Podpisany adres URL do pobrania obrazu podglądu PNG białego modelu UV.
Name
progress
Type
integer
Description
Jak dużą część zadania wykonano, jako wartość procentowa od 0 do 100.
Name
status
Type
string
Description
Status zadania, jedna z wartości PENDING, IN_PROGRESS, SUCCEEDED, FAILED lub CANCELED.
Name
preceding_tasks
Type
integer
Description
Liczba zadań znajdujących się przed tym zadaniem w kolejce. Obecne, gdy zadanie ma status PENDING.
Name
created_at
Type
timestamp
Description
Czas utworzenia zadania, w milisekundach Unix.
Name
started_at
Type
timestamp
Description
Czas rozpoczęcia zadania, w milisekundach Unix. Wynosi 0, dopóki zadanie się nie rozpocznie.
Name
finished_at
Type
timestamp
Description
Czas zakończenia zadania, w milisekundach Unix. Wynosi 0, dopóki zadanie się nie zakończy.
Name
expires_at
Type
timestamp
Description
Czas wygaśnięcia podpisanych adresów URL do pobrania, w milisekundach Unix.
Name
task_error
Type
object
Description
Szczegóły błędu, gdy zadanie zakończy się niepowodzeniem. Zobacz Błędy.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez zadanie. Zadanie Rozwinięcia UV zakończone powodzeniem kosztuje 5 kredytów. Wynosi 0 dla zadania ze statusem FAILED, ponieważ Meshy zwraca kredyty, gdy zadanie zakończy się niepowodzeniem.