Błędy

W tym przewodniku omówimy, co się dzieje, gdy coś pójdzie nie tak podczas pracy z Meshy API.

Błędy żądania

Te błędy są zwracane natychmiast, gdy Twoje żądanie API zostanie odrzucone. Sprawdź kod statusu HTTP i pole message, aby zrozumieć, co poszło nie tak.

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

Błędy zadań

Te błędy występują po utworzeniu zadania i w trakcie jego przetwarzania. Sprawdź obiekt task_error w odpowiedzi zadania, aby uzyskać szczegóły błędu.

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

Typy błędów

Pole type informuje o ogólnej kategorii niepowodzenia. Użyj go, aby zdecydować o strategii ponowienia próby.

Kody błędów

Gdy pole code jest obecne, identyfikuje konkretny problem, wobec którego można podjąć działanie. Poniżej znajduje się pełna dokumentacja każdego kodu błędu.

image_too_complex

Ten błąd występuje, gdy obraz wejściowy lub prompt opisuje obiekt, który jest zbyt złożony geometrycznie, aby model generowania 3D mógł go przetworzyć.

Typowe przykłady obejmują:

• Gęste stosy małych obiektów (np. skrzynka pełna owoców, stos książek)
• Skomplikowane powtarzające się wzory (np. struktury kratowe, rusztowania, siatki druciane)
• Złożone konstrukcje budynków (np. wielopiętrowe budynki z wieloma oknami i balkonami)
• Wiele odrębnych obiektów na jednym obrazie zamiast pojedynczego obiektu

Przykłady danych wejściowych, które prawdopodobnie są zbyt złożone:

Rozwiązanie:

1. Użyj jednego obiektu na obraz. Model działa najlepiej z jednym wyraźnym obiektem. Nie umieszczaj wielu oddzielnych obiektów na tym samym obrazie ani w tym samym prompcie.
2. Uprość swój obiekt. Zmniejsz poziom szczegółowości. Na przykład prosty wazon zamiast wazonu wypełnionego dziesiątkami kwiatów.
3. Unikaj promptów na poziomie sceny. Całe budynki, kwartały miejskie, wnętrza wypełnione meblami lub krajobrazy prawdopodobnie przekroczą możliwości modelu. Zamiast tego skup się na pojedynczym obiekcie.
4. Unikaj gęstych powtarzających się struktur. Obiekty takie jak rusztowania, siatki druciane, wzory kratowe lub stosy wielu małych elementów są częstymi wyzwalaczami.

model_missing_uv

Ten błąd występuje, gdy przesyłasz model do teksturowania z enable_original_uv ustawionym na true, ale model nie ma współrzędnych UV. Współrzędne UV definiują, jak tekstura 2D owija się wokół powierzchni 3D modelu.

Rozwiązanie:

Właściwe rozwiązanie zależy od tego, dlaczego ustawiono enable_original_uv na true:

• Jeśli musisz zachować oryginalny układ UV modelu (np. niestandardowe rozmieszczenie szwów do precyzyjnego mapowania tekstury): model musi mieć prawidłowe współrzędne UV. Przed przesłaniem sprawdź w edytorze UV swojego oprogramowania 3D, czy współrzędne UV istnieją. Pamiętaj, że pliki STL nie mogą przechowywać danych UV, więc zamiast tego użyj GLB, FBX lub OBJ.
• Jeśli nie potrzebujesz konkretnej kontroli UV (albo nie masz pewności): pomiń enable_original_uv lub ustaw je na false. System automatycznie wygeneruje układ UV dla modelu. Automatycznie wygenerowane współrzędne UV są zoptymalizowane pod kątem pokrycia, ale nie będziesz mieć kontroli nad tym, gdzie zostaną umieszczone szwy tekstury.

model_insufficient_uv

Ten błąd występuje, gdy model ma współrzędne UV, ale pokrycie UV jest zbyt małe, aby zapewnić wysoką jakość teksturowania. Często dzieje się tak w przypadku modeli eksportowanych z narzędzi 3D, które generują zastępcze lub zapadnięte UV bez prawidłowego rozwinięcia.

Rozwiązanie:

• Jeśli musisz zachować oryginalny układ UV: ponownie rozwiń UV modelu w swoim oprogramowaniu 3D. Upewnij się, że wyspy UV są prawidłowo rozmieszczone w przestrzeni UV, zamiast być zapadnięte do małego obszaru.
• Jeśli nie potrzebujesz konkretnej kontroli nad UV: pomiń enable_original_uv lub ustaw go na false. System automatycznie wygeneruje nowy układ UV. Kompromis polega na tym, że utracisz oryginalne rozmieszczenie szwów, ale automatycznie wygenerowane UV będą mieć odpowiednie pokrycie do teksturowania.

invalid_input

To jest rezerwowy kod błędu używany, gdy dane wejściowe nie przechodzą walidacji, ale nie ma zastosowania żaden bardziej szczegółowy kod. Pole message zawiera konkretną przyczynę niepowodzenia.

Typowe przyczyny obejmują:

• Puste lub uszkodzone pliki modeli
• Nieobsługiwane warianty formatów plików (np. pliki ASCII FBX, GLB skompresowane meshopt)
• Brak prawidłowych obiektów 3D w przesłanym modelu (np. plik zawiera tylko szkielety, kamery lub światła)
• Treść, która nie przechodzi filtrów bezpieczeństwa

Rozwiązanie: Sprawdź pole message, aby uzyskać szczegółowe informacje o tym, co poszło nie tak. Zweryfikuj, czy pliki wejściowe i parametry odpowiadają wymaganiom punktu końcowego.

moderation_blocked

Ten błąd występuje, gdy Twój prompt lub obrazy referencyjne zostaną odrzucone przez filtry bezpieczeństwa AI. Filtr ocenia łącznie zarówno prompt tekstowy, jak i wszelkie obrazy referencyjne.

Rozwiązanie:

• Przeformułuj swój prompt tekstowy, aby usunąć sugestywne lub wrażliwe opisy.
• Dostosuj obrazy referencyjne, jeśli przedstawiają treści, które mogą uruchomić filtry bezpieczeństwa.

timeout

Ten błąd oznacza, że czas przetwarzania Twojego zadania przekroczył dozwolony limit. Może się to zdarzyć z powodu dużego obciążenia systemu lub dlatego, że dane wejściowe są zbyt złożone, aby przetworzyć je w wyznaczonym czasie.

Rozwiązanie:

1. Ponów żądanie. Błędy timeout są często przejściowe i ponowna próba może się powieść.
2. Uprość dane wejściowe. Jeśli ponowne próby nadal kończą się niepowodzeniem, dane wejściowe mogą być zbyt złożone. Spróbuj zmniejszyć poziom szczegółowości obrazu lub prompt. Zobacz image_too_complex, aby uzyskać wskazówki dotyczące typów danych wejściowych, które są trudniejsze do przetworzenia.

format_conversion_failed

Ten błąd występuje, gdy wygenerowany model 3D nie mógł zostać przekonwertowany do żądanego formatu wyjściowego. Model został wygenerowany pomyślnie, ale etap konwersji nie powiódł się.

Rozwiązanie:

1. Ponów żądanie.
2. Wypróbuj inny format wyjściowy. Jeśli określony format nadal kończy się niepowodzeniem, przełącz się na inny format, który odpowiada Twoim potrzebom.

Najlepsze praktyki

1. Zaimplementuj logikę ponawiania. W przypadku błędów timeout i service_unavailable zaimplementuj logikę ponawiania z wykładniczym wydłużaniem czasu oczekiwania.
2. Rejestruj identyfikatory zadań. Zawsze rejestruj identyfikator zadania w celach debugowania. Uwzględnij go podczas kontaktowania się z pomocą techniczną.
3. Waliduj dane wejściowe. Przed przesłaniem upewnij się, że obrazy wejściowe i modele spełniają wymagania dotyczące formatu.