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 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. Wykorzystaj je do podjęcia decyzji o strategii ponawiania próby.

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 zostają odrzucone przez filtry bezpieczeństwa AI. Filtr ocenia zarówno tekstowy prompt, jak i wszystkie obrazy referencyjne razem.

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ą uruchamiać filtry bezpieczeństwa.

moderation_unavailable

Ten błąd występuje, gdy moderation była tymczasowo niedostępna, przez co zadanie zakończyło się niepowodzeniem zamiast zostać uruchomione bez tej kontroli. Z Twoją treścią wszystko jest w porządku. Jego type to server_error.

Rozwiązanie: Utwórz zadanie ponownie.

timeout

Ten błąd oznacza, że zadanie przekroczyło limit czasu po stronie serwera — dotyczący przetwarzania lub oczekiwania w kolejce — w związku z czym zadanie zakończyło się niepowodzeniem, a jego kredyty zostały zwrócone. Może się to zdarzyć z powodu dużego obciążenia systemu lub ponieważ dane wejściowe są zbyt złożone, aby przetworzyć je w ramach limitu czasu.

To coś innego niż timeout w Twoim własnym kodzie. Jeśli Twój klient przestał czekać, zadanie nadal jest wykonywane; zobacz Cykl życia zadania.

Rozwiązanie:

1. Utwórz zadanie ponownie. Błędy timeout są często przejściowe i nowe zadanie może się powieść.
2. Uprość swoje dane wejściowe. Jeśli kolejne próby wciąż się nie udają, Twoje dane wejściowe mogą być zbyt złożone. Spróbuj zmniejszyć poziom szczegółowości obrazu lub prompta. Zobacz image_too_complex, aby dowiedzieć się, jakie rodzaje danych wejściowych są trudniejsze do przetworzenia.

queue_timeout

Ten błąd oznacza, że zadanie zbyt długo czekało w kolejce i nie zostało uruchomione, w związku z czym zakończyło się niepowodzeniem, a wszelkie kredyty pobrane za nie zostały zwrócone. Twoje dane wejściowe nie są tego przyczyną. Jego type to timeout.

Rozwiązanie: Utwórz zadanie ponownie.

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 zakończył się niepowodzeniem.

Rozwiązanie:

1. Ponów żądanie.
2. Wypróbuj inny format wyjściowy. Jeśli konkretny format wciąż powoduje błąd, przełącz się na inny format, który odpowiada Twoim potrzebom.

Najlepsze praktyki

1. Zaimplementuj logikę ponawiania prób. Gdy zadanie zakończy się błędem timeout, service_unavailable lub server_error, utwórz je ponownie, stosując wykładnicze opóźnienie (exponential backoff). Jeśli to Twoje żądanie przekroczyło limit czasu, nie twórz nowego zadania: najpierw sprawdź istniejące (zobacz Cykl życia zadania).
2. Rejestruj identyfikatory zadań. Zawsze loguj identyfikator zadania do celów debugowania. Podawaj go podczas kontaktu z pomocą techniczną.
3. Waliduj dane wejściowe. Upewnij się, że przesyłane obrazy i modele spełniają wymagania dotyczące formatu, zanim je prześlesz.
4. Wywołuj API z poziomu swojego serwera. Kod uruchamiany w przeglądarce ujawniłby Twój klucz API każdemu, kto otworzy tę stronę.