Błędy

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

Błędy żądań

Te błędy są zwracane natychmiast, gdy Twoje żądanie API zostanie odrzucone. Sprawdź kod statusu HTTP oraz 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 podczas 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.

Kody błędów

Gdy pole code jest obecne, identyfikuje konkretny, możliwy do rozwiązania problem. Poniżej znajduje się pełna referencja dla każdego kodu błędu.

image_too_complex

Ten błąd występuje, gdy obraz wejściowy lub prompt opisuje temat, który jest zbyt geometrycznie skomplikowany, 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 struktury budynków (np. wielopiętrowe budynki z wieloma oknami i balkonami)
• Wiele odrębnych obiektów na jednym obrazie zamiast jednego tematu

Przykłady wejść, które prawdopodobnie są zbyt skomplikowane:

Rozwiązanie:

1. Użyj jednego obiektu na obraz. Model działa najlepiej z jednym wyraźnym tematem. Nie umieszczaj wielu oddzielnych obiektów na tym samym obrazie lub w prompt.
2. Uprość swój temat. 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, bloki miejskie, wnętrza wypełnione meblami lub krajobrazy prawdopodobnie przekroczą możliwości modelu. Skup się na jednym obiekcie.
4. Unikaj gęstych powtarzających się struktur. Tematy takie jak rusztowania, siatki druciane, wzory kratowe lub stosy wielu małych przedmiotów są częstymi wyzwalaczami.

model_missing_uv

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

Rozwiązanie:

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

• Jeśli musisz zachować oryginalny układ UV swojego modelu (np. niestandardowe rozmieszczenie szwów dla precyzyjnego mapowania tekstur): twój model musi mieć prawidłowe współrzędne UV. Zweryfikuj istnienie UV w edytorze UV twojego oprogramowania 3D przed przesłaniem. Pamiętaj, że pliki STL nie mogą przechowywać danych UV, więc użyj GLB, FBX lub OBJ zamiast tego.
• Jeśli nie potrzebujesz specyficznej kontroli UV (lub nie jesteś pewien): pomiń enable_original_uv lub ustaw go na false. System automatycznie wygeneruje układ UV dla twojego modelu. Automatycznie wygenerowane UV są zoptymalizowane pod kątem pokrycia, ale nie będziesz mieć kontroli nad tym, gdzie są 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 dla jakościowego teksturowania. Zwykle dzieje się to z modelami eksportowanymi z narzędzi 3D, które generują tymczasowe lub złożone UV bez odpowiedniego rozwinięcia.

Rozwiązanie:

• Jeśli musisz zachować swój oryginalny układ UV: ponownie rozwiń UV modelu w swoim oprogramowaniu 3D. Upewnij się, że wyspy UV są odpowiednio rozłożone w przestrzeni UV, a nie złożone w małym obszarze.
• Jeśli nie potrzebujesz specyficznej kontroli UV: pomiń enable_original_uv lub ustaw na false. System automatycznie wygeneruje nowy układ UV. Kompromis polega na utracie oryginalnego rozmieszczenia szwów, ale automatycznie wygenerowane UV będą miały odpowiednie pokrycie dla teksturowania.

model_missing_texture

Ten błąd występuje, gdy model wejściowy zadania Multi-Color Print nie zawiera żadnych informacji o kolorze, które konwerter mógłby rozdzielić na kolory druku. Wielokolorowy plik 3MF jest budowany na podstawie kolorów modelu, więc zwykła biała siatka — na przykład podgląd z Tekst na 3D lub Obraz na 3D, który nigdy nie został poddany teksturowaniu, albo wynik naprawy / automatycznego podziału — nie zawiera niczego, na czym można by pracować.

To, co liczy się jako źródło koloru, zależy od żądanego style:

• realistic pobiera próbki tekstury koloru bazowego na podstawie współrzędnych UV modelu, więc wymaga pojedynczej tekstury koloru bazowego ze współrzędnymi UV na każdej części siatki.
• cartoon spłaszcza kolory dla każdej ściany i akceptuje teksturę koloru bazowego na dowolnej części lub kolory na wierzchołkach (COLOR_0).

Model, który nie ma ani tekstury koloru bazowego, ani kolorów wierzchołków, zostanie odrzucony dla obu stylów; w przypadku cartoon w przeciwnym razie „powiódłby się” jako druk jednokolorowy.

Większość żądań jest odrzucana, zanim zadanie zostanie utworzone (400 Bad Request z tym samym wyjaśnieniem), więc zazwyczaj zobaczysz ten kod tylko wtedy, gdy nie można było wcześniej sprawdzić danych wejściowych — na przykład przesłany plik .fbx jest sprawdzany dopiero po tym, jak zadanie go znormalizuje.

Rozwiązanie:

• Najpierw nałóż teksturę na model. Uruchom na nim zadanie Retexture lub wygeneruj model z włączonym teksturowaniem (zadanie refine z Tekst na 3D albo zadanie Obraz na 3D z should_texture: true), a następnie przekaż to zadanie jako input_task_id.
• Modele z kolorami wierzchołków (skany fotogrametryczne, ręcznie malowane siatki): zażądaj style: "cartoon", który odczytuje COLOR_0.
• Częściowo teksturowane modele lub modele z wieloma teksturami w trybie realistic: każda część siatki wymaga współrzędnych UV oraz tej samej, pojedynczej tekstury koloru bazowego. Nałóż teksturę na pozostałe części lub połącz tekstury w jeden atlas, albo przełącz się na style: "cartoon".

invalid_input

To jest domyślny kod błędu, gdy dane wejściowe nie przechodzą walidacji, ale nie ma bardziej szczegółowego kodu, który można zastosować. Pole message zawiera konkretny powód niepowodzenia.

Typowe przyczyny to:

• Puste lub uszkodzone pliki modeli
• Nieobsługiwane warianty formatów plików (np. pliki ASCII FBX, GLB skompresowane za pomocą meshopt)
• Brak prawidłowych obiektów 3D w przesłanym modelu (np. plik zawiera tylko armatury, kamery lub światła)
• Treści, które nie przechodzą przez filtry bezpieczeństwa

Rozwiązanie: Sprawdź pole message, aby uzyskać szczegóły dotyczące tego, co poszło nie tak. Zweryfikuj, czy twoje pliki wejściowe i parametry spełniają wymagania punktu końcowego.

moderation_blocked

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

Rozwiązanie:

• Przekształć swój tekstowy prompt, 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 zbyt skomplikowanego wejścia do przetworzenia w ramach limitu czasu.

Rozwiązanie:

1. Ponów próbę. Timeouty są często przejściowe i ponowienie próby może się powieść.
2. Uprość swoje wejście. Jeśli ponowne próby nadal zawodzą, Twoje wejście może być zbyt skomplikowane. Spróbuj zmniejszyć poziom szczegółowości w swoim obrazie lub prompt. Zobacz image_too_complex w celu uzyskania wskazówek, jakie typy wejść są trudniejsze do przetworzenia.

format_conversion_failed

Ten błąd występuje, gdy wygenerowany model 3D nie mógł zostać przekonwertowany na żądany format wyjściowy. Model został wygenerowany pomyślnie, ale krok konwersji zakończył się niepowodzeniem.

Rozwiązanie:

1. Ponów próbę.
2. Spróbuj innego formatu wyjściowego. Jeśli konkretny format ciągle zawodzi, przełącz się na inny format, który spełnia Twoje potrzeby.

Najlepsze praktyki

1. Zaimplementuj logikę ponawiania. Dla błędów timeout i service_unavailable zaimplementuj logikę ponawiania z wykładniczym opóźnieniem.
2. Rejestruj identyfikatory zadań. Zawsze rejestruj identyfikator zadania do celów debugowania. Dołącz go, kontaktując się z pomocą techniczną.
3. Waliduj dane wejściowe. Upewnij się, że Twoje obrazy wejściowe i modele spełniają wymagania dotyczące formatu przed przesłaniem.