Błędy

Dowiedz się, dlaczego żądanie lub zadanie zakończyło się niepowodzeniem oraz co zrobić dalej. Żądanie może zakończyć się niepowodzeniem od razu, zwracając błąd HTTP, a zadanie może zakończyć się niepowodzeniem później, zwracając task_error.

Błędy żądania

Meshy zwraca te błędy natychmiast, gdy odrzuca żądanie. Aby dowiedzieć się, co poszło nie tak, sprawdź kod statusu HTTP oraz pole message.

{
  "message": "Invalid model file extension: .3dm"
}

Błędy zadania

Zadanie utworzone przez Meshy może zakończyć się niepowodzeniem w trakcie wykonywania. Jego status zmienia się na FAILED, Meshy zwraca kredyty, a task_error wyjaśnia przyczynę.

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "invalid_input",
    "code": "image_too_complex",
    "message": "The uploaded image is too complex for 3D generation.",
    "doc_url": "https://docs.meshy.ai/en/api/errors#image-too-complex"
  }
}

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "server_error",
    "message": "An internal error occurred. Please retry."
  }
}

Rodzaje błędów

type to ogólna kategoria błędu. Na jej podstawie decydujesz, co zrobić dalej.

Kody błędów

Gdy pole code jest obecne, oznacza ono jeden z poniższych problemów.

image_too_complex

Obraz wejściowy lub prompt opisuje temat, który jest zbyt złożony geometrycznie dla generowania 3D.

Na przykład:

• Gęste skupiska małych obiektów, takie jak skrzynka pełna owoców lub stos książek
• Skomplikowane powtarzające się wzory, takie jak struktury kratowe, rusztowania lub siatki drutowe
• Złożone budynki, takie jak wielopiętrowe budynki z wieloma oknami i balkonami
• Kilka odrębnych obiektów na jednym obrazie zamiast pojedynczego tematu

Te dane wejściowe są prawdopodobnie zbyt złożone:

Aby to naprawić, spróbuj jednego lub kilku z poniższych rozwiązań:

• Używaj jednego obiektu na obraz. Meshy działa najlepiej z jednym wyraźnym tematem, więc nie umieszczaj kilku oddzielnych obiektów na tym samym obrazie lub w tym samym promptcie.
• Uprość swój temat. Na przykład użyj prostego wazonu zamiast wazonu wypełnionego dziesiątkami kwiatów.
• Unikaj scen. Całe budynki, bloki miejskie, umeblowane pokoje i krajobrazy są prawdopodobnie zbyt złożone. Skup się na pojedynczym obiekcie.
• Unikaj gęstych, powtarzających się struktur. Rusztowania, siatki drutowe, kraty i stosy małych przedmiotów to częste przyczyny problemów.

model_missing_uv

Wysłano model do teksturowania z parametrem enable_original_uv ustawionym na true, ale model nie ma współrzędnych UV. Współrzędne UV określają sposób, w jaki tekstura 2D jest nakładana na powierzchnię 3D.

Aby to naprawić, wykonaj jedną z poniższych czynności:

• Aby zachować własny układ UV modelu, na przykład w celu niestandardowego rozmieszczenia szwów, dodaj współrzędne UV do modelu w swoim oprogramowaniu 3D. Sprawdź je w jego edytorze UV, a następnie prześlij model ponownie. Pliki STL nie mogą przechowywać UV, dlatego użyj formatu GLB, FBX lub OBJ.
• Jeśli nie potrzebujesz własnego układu lub nie masz pewności, pomiń enable_original_uv lub ustaw go na false. Meshy utworzy wtedy układ UV dla modelu. Nowe współrzędne UV dobrze pokrywają model, ale nie masz kontroli nad tym, gdzie znajdą się szwy tekstury.

model_insufficient_uv

Model posiada współrzędne UV, ale pokrywają one zbyt mały obszar przestrzeni UV, aby umożliwić prawidłowe teksturowanie. Zdarza się to często w przypadku modeli, których eksporter zapisał zastępcze lub zapadnięte UV-y bez odpowiedniego rozwinięcia (unwrap).

Aby to naprawić, wykonaj jedną z poniższych czynności:

• Aby zachować własny układ UV, ponownie rozwiń współrzędne UV modelu w swoim oprogramowaniu 3D. Rozmieść wyspy UV na całej przestrzeni UV, zamiast ściskać je w małym rogu.
• Jeśli nie potrzebujesz własnego układu, pomiń enable_original_uv lub ustaw go na false. Meshy utworzy wtedy nowy układ UV. Stracisz swoje rozmieszczenie szwów, ale nowe UV-y będą pokrywać wystarczający obszar do teksturowania.

model_missing_texture

Model wejściowy zadania Multi-Color Print nie ma żadnego koloru, który Meshy mogłoby podzielić na kolory druku. Meshy buduje wielokolorowy plik 3MF na podstawie kolorów modelu, więc zwykła biała siatka nie daje nic, na czym można by pracować. Na przykład podgląd Tekst na 3D lub Obraz na 3D, który nigdy nie został otakturowany, nie ma koloru. Podobnie jest z wynikiem Napraw drukowalność lub zadaniem Auto Split, które nie zachowało tekstury.

To, co liczy się jako kolor, zależy od żądanego style:

• realistic próbkuje teksturę koloru bazowego na podstawie UV modelu. Wymaga pojedynczej tekstury koloru bazowego oraz UV na każdej części siatki.
• cartoon spłaszcza kolory dla każdej ściany. Akceptuje teksturę koloru bazowego na dowolnej części lub kolory przypisane do wierzchołków (COLOR_0).

Meshy odrzuca model, który nie ma ani tekstury koloru bazowego, ani kolorów wierzchołków, dla obu stylów, zamiast pozwolić, by cartoon zamieniło go w jednokolorowy druk.

Meshy odrzuca większość takich żądań jeszcze przed utworzeniem zadania, zwracając kod 400 wraz z tym samym wyjaśnieniem. Zazwyczaj ten kod otrzymasz tylko wtedy, gdy Meshy nie jest w stanie z góry sprawdzić danych wejściowych. Na przykład przesłany plik .fbx Meshy sprawdza dopiero po tym, jak zadanie go przekonwertuje.

Aby to naprawić, wybierz opcję odpowiednią dla Twojego modelu:

• Najpierw otakturuj model. Uruchom na nim Reteksturowanie lub wygeneruj go za pomocą zadania Tekst na 3D w etapie refine albo zadania Obraz na 3D z should_texture: true. Następnie wyślij to zadanie jako input_task_id.
• W przypadku modelu z kolorami wierzchołków, np. skanu fotogrametrycznego lub ręcznie malowanej siatki, użyj style: "cartoon", który odczytuje COLOR_0.
• W przypadku częściowo otakturowanego modelu lub modelu z wieloma teksturami przy realistic, nadaj UV każdej części siatki i zastosuj tę samą pojedynczą teksturę koloru bazowego. Aby to zrobić, otakturuj pozostałe części lub połącz tekstury w jeden atlas. Możesz też przełączyć się na style: "cartoon".

textured_split_refused

Zadanie Auto Split z keep_texture: true nie może zachować tekstury modelu wejściowego na częściach. Na przykład model nie ma UV-ów albo jego tekstura nie ma miejsca na nowe ścianki powstałe w wyniku cięć. Meshy zwraca kredyty.

Aby to naprawić, wyślij żądanie ponownie bez keep_texture lub z keep_texture: false. Części zostaną wówczas zwrócone z jednolitym kolorem każda.

invalid_input

Dane wejściowe nie przeszły kontroli, a żaden bardziej szczegółowy kod nie ma zastosowania. message podaje przyczynę.

Na przykład:

• Pusty lub uszkodzony plik modelu
• Nieobsługiwany wariant formatu pliku, taki jak plik FBX w formacie ASCII lub plik GLB skompresowany za pomocą meshopt
• Przesłany model bez prawidłowych obiektów 3D, na przykład plik zawierający tylko szkielety (armatury), kamery lub światła
• Treść, która nie przechodzi filtrów bezpieczeństwa

Aby to naprawić, zapoznaj się z message, aby poznać konkretny problem. Sprawdź, czy pliki wejściowe i parametry spełniają wymagania punktu końcowego.

moderation_blocked

Filtry bezpieczeństwa odrzuciły Twój prompt lub obrazy referencyjne. Filtry sprawdzają tekst i obrazy razem.

Aby to naprawić, wykonaj jedną lub obie z poniższych czynności:

• Przeformułuj prompt, usuwając sugestywne lub wrażliwe opisy.
• Zmień obrazy referencyjne przedstawiające treści, które mogą zostać zablokowane przez filtry.

moderation_unavailable

Typ: server_error. Moderacja treści była tymczasowo niedostępna, więc Meshy zakończyło zadanie niepowodzeniem zamiast pominąć sprawdzenie. Z Twoją treścią wszystko jest w porządku.

Aby to naprawić, utwórz zadanie ponownie.

timeout

Zadanie przekroczyło limit czasu po stronie serwera, dotyczący przetwarzania lub oczekiwania w kolejce, w związku z czym Meshy zakończyło je niepowodzeniem i zwróciło kredyty. Przyczyną może być duże obciążenie lub dane wejściowe zbyt złożone, by zostały przetworzone na czas.

To coś innego niż timeout we własnym kodzie. Jeśli klient przestał czekać, zadanie nadal się wykonuje. Zobacz Jak długo czekać.

Aby to naprawić, wykonaj poniższe kroki:

1. Utwórz zadanie ponownie. Timeouty są często tymczasowe, więc nowe zadanie może zakończyć się powodzeniem.
2. Jeśli błąd nadal występuje, uprość dane wejściowe, na przykład zmniejszając poziom szczegółowości obrazu lub promptu. W przypadku danych wejściowych trudniejszych do przetworzenia zobacz image_too_complex.

queue_timeout

Typ: timeout. Zadanie zbyt długo czekało w kolejce bez rozpoczęcia, dlatego Meshy oznaczyło je jako nieudane i zwróciło wszelkie kredyty pobrane za nie. Twoje dane wejściowe nie spowodowały tego błędu.

Aby to naprawić, utwórz zadanie ponownie.

format_conversion_failed

Meshy wygenerowało model, ale konwersja do żądanego formatu nie powiodła się.

Aby to naprawić, wykonaj następujące kroki:

1. Utwórz zadanie ponownie.
2. Jeśli konwersja do jednego formatu wciąż się nie udaje, poproś o inny format, który odpowiada Twoim potrzebom.

Dobre praktyki

• Ponawiaj nieudane zadania. W przypadku zadania zakończonego niepowodzeniem z kodem timeout, service_unavailable lub server_error, utwórz nowe zadanie z wykładniczym backoffem.
• Nie twórz nowego zadania, gdy wygaśnie limit czasu Twojego własnego żądania. Pierwsze zadanie może nadal być wykonywane, więc sprawdź, czy istnieje, zanim utworzysz kolejne. Zobacz Jak długo czekać.
• Rejestruj identyfikatory zadań. Dołącz identyfikator podczas kontaktu z pomocą techniczną.
• Sprawdzaj dane wejściowe przed ich wysłaniem. Upewnij się, że obrazy i modele spełniają wymagania formatu punktu końcowego.
• Wywołuj API ze swojego serwera. Kod uruchamiany w przeglądarce ujawnia Twój klucz API każdemu, kto otworzy stronę.