Chyby

V tomto průvodci si povíme, co se stane, když se něco pokazí při práci s Meshy API.

Chyby požadavků

Tyto chyby se vrátí okamžitě, pokud je váš API požadavek odmítnut. Zkontrolujte HTTP stavový kód a pole message, abyste zjistili, co se pokazilo.

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

Chyby úkolu

Tyto chyby se vyskytují po vytvoření úkolu a během jeho zpracování. Zkontrolujte objekt task_error v odpovědi úkolu pro podrobnosti o chybě.

{
  "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 chyb

Pole type vám sdělí širokou kategorii selhání. Použijte ji k rozhodnutí o vaší strategii opakování.

Chybové kódy

Když je přítomno pole code, identifikuje konkrétní, řešitelný problém. Níže je úplný přehled pro každý chybový kód.

image_too_complex

Tato chyba nastane, když vstupní obrázek nebo prompt popisuje objekt, který je příliš geometricky složitý pro zpracování modelem generování 3D.

Běžné příklady zahrnují:

• Husté hromady malých objektů (např. bedna plná ovoce, hromada knih)
• Složité opakující se vzory (např. mřížkové struktury, lešení, drátěné pletivo)
• Složité stavební struktury (např. vícepodlažní budovy s mnoha okny a balkony)
• Více odlišných objektů na jednom obrázku místo jednoho subjektu

Příklady vstupů, které jsou pravděpodobně příliš složité:

Řešení:

1. Použijte jeden objekt na obrázek. Model funguje nejlépe s jedním jasným subjektem. Nezahrnujte více samostatných objektů na stejném obrázku nebo v promptu.
2. Zjednodušte svůj subjekt. Snižte úroveň detailů. Například jednoduchá váza místo vázy plné desítek květin.
3. Vyhněte se promptům na úrovni scény. Celé budovy, městské bloky, interiéry plné nábytku nebo krajiny pravděpodobně překročí kapacitu modelu. Zaměřte se místo toho na jeden objekt.
4. Vyhněte se hustým opakujícím se strukturám. Subjekty jako lešení, drátěné pletivo, mřížkové vzory nebo hromady mnoha malých předmětů jsou běžnými spouštěči.

model_missing_uv

Tato chyba nastane, když nahrajete model pro texturování s nastavením enable_original_uv na true, ale model nemá žádné UV souřadnice. UV souřadnice definují, jak se 2D textura obaluje na 3D povrch vašeho modelu.

Řešení:

Správná oprava závisí na tom, proč jste nastavili enable_original_uv na true:

• Pokud potřebujete zachovat původní UV rozvržení vašeho modelu (např. vlastní umístění švů pro přesné mapování textur): váš model musí mít platné UV souřadnice. Ověřte, že UV souřadnice existují v UV editoru vašeho 3D softwaru před nahráním. Upozorňujeme, že soubory STL nemohou ukládat UV data, takže použijte GLB, FBX nebo OBJ místo toho.
• Pokud nepotřebujete specifickou kontrolu nad UV (nebo si nejste jisti): vynechejte enable_original_uv nebo jej nastavte na false. Systém automaticky vygeneruje UV rozvržení pro váš model. Automaticky generované UV souřadnice jsou optimalizovány pro pokrytí, ale nebudete mít kontrolu nad tím, kde jsou umístěny švy textury.

model_insufficient_uv

Tato chyba nastane, když má model UV souřadnice, ale pokrytí UV je příliš malé pro kvalitní texturování. To se běžně stává u modelů exportovaných z 3D nástrojů, které generují zástupné nebo zkolabované UV bez správného rozbalení.

Řešení:

• Pokud potřebujete zachovat své původní UV rozvržení: znovu rozbalte UV modelu ve svém 3D softwaru. Ujistěte se, že UV ostrovy jsou správně rozprostřeny po UV prostoru, místo aby byly zkolabovány do malé oblasti.
• Pokud nepotřebujete specifickou kontrolu UV: vynechejte enable_original_uv nebo jej nastavte na false. Systém automaticky vygeneruje nové UV rozvržení. Kompromisem je, že ztratíte původní umístění švů, ale automaticky generované UV budou mít správné pokrytí pro texturování.

model_missing_texture

Tato chyba nastane, když vstupní model úlohy Multi-Color Print neobsahuje žádnou barevnou informaci, kterou by konvertor mohl rozdělit do tiskových barev. Vícebarevný 3MF se vytváří z barev modelu, takže obyčejná bílá síť — například náhled Text na 3D nebo Obrázek na 3D, který nebyl nikdy texturován, nebo výstup opravy / automatického rozdělení — nemá s čím pracovat.

Co se počítá jako zdroj barev, závisí na požadovaném style:

• realistic vzorkuje texturu základní barvy pomocí UV souřadnic modelu, takže vyžaduje jedinou texturu základní barvy s UV souřadnicemi na každé části sítě.
• cartoon zplošťuje barvy po jednotlivých plochách a akceptuje texturu základní barvy na kterékoli části nebo barvy podle vrcholů (COLOR_0).

Model, který nemá ani texturu základní barvy, ani barvy vrcholů, je odmítnut pro oba styly; u cartoon by jinak „uspěl“ jako jednobarevný tisk.

Většina požadavků je odmítnuta ještě před vytvořením úlohy (400 Bad Request se stejným vysvětlením), takže tento kód uvidíte obvykle jen tehdy, když nebylo možné vstup zkontrolovat předem — například nahrání .fbx se kontroluje až po normalizaci úlohy.

Řešení:

• Nejprve model otexturujte. Spusťte na něm úlohu Retexturování, nebo jej vygenerujte s povoleným texturováním (refine úloha Text na 3D, nebo úloha Obrázek na 3D s should_texture: true), a tuto úlohu předejte jako input_task_id.
• Modely s barvami vrcholů (fotogrammetrické skeny, ručně malované sítě): požadujte style: "cartoon", který čte COLOR_0.
• Částečně texturované nebo vícetexturové modely v režimu realistic: každá část sítě potřebuje UV souřadnice a stejnou, jedinou texturu základní barvy. Otexturujte zbývající části nebo sloučte textury do jednoho atlasu, případně přepněte na style: "cartoon".

invalid_input

Toto je výchozí chybový kód, když vstup neprojde validací, ale žádný konkrétnější kód se nepoužije. Pole message obsahuje konkrétní důvod selhání.

Běžné příčiny zahrnují:

• Prázdné nebo poškozené soubory modelů
• Nepodporované varianty formátů souborů (např. ASCII FBX soubory, GLB soubory komprimované pomocí meshopt)
• Nebyly nalezeny žádné platné 3D objekty v nahraném modelu (např. soubor obsahuje pouze armatury, kamery nebo světla)
• Obsah, který neprojde bezpečnostními filtry

Řešení: Zkontrolujte pole message pro podrobnosti o tom, co se pokazilo. Ověřte, že vaše vstupní soubory a parametry odpovídají požadavkům koncového bodu.

moderation_blocked

Tato chyba nastane, když je váš prompt nebo referenční obrázky odmítnuty bezpečnostními filtry AI. Filtr vyhodnocuje jak textový prompt, tak i jakékoliv referenční obrázky společně.

Řešení:

• Přeformulujte svůj textový prompt, abyste odstranili sugestivní nebo citlivé popisy.
• Upravte referenční obrázky, pokud zobrazují obsah, který může spustit bezpečnostní filtry.

timeout

Tato chyba znamená, že doba zpracování vašeho úkolu překročila povolený limit. To se může stát kvůli vysoké zátěži systému nebo proto, že vstup je příliš složitý na zpracování v rámci časového limitu.

Řešení:

1. Zkuste požadavek znovu. Timeouty jsou často přechodné a opakování může být úspěšné.
2. Zjednodušte svůj vstup. Pokud opakování stále selhává, váš vstup může být příliš složitý. Zkuste snížit úroveň detailů ve vašem obrázku nebo promptu. Viz image_too_complex pro pokyny, jaké typy vstupů jsou obtížnější ke zpracování.

format_conversion_failed

Tato chyba nastane, když nelze vygenerovaný 3D model převést do požadovaného výstupního formátu. Model byl úspěšně vygenerován, ale krok převodu selhal.

Řešení:

1. Zkuste požadavek znovu.
2. Vyzkoušejte jiný výstupní formát. Pokud konkrétní formát stále selhává, přepněte na jiný formát, který vyhovuje vašim potřebám.

Osvědčené postupy

1. Implementujte logiku opakování. Pro chyby timeout a service_unavailable implementujte logiku opakování s exponenciálním zpožděním.
2. Zaznamenávejte ID úkolů. Vždy zaznamenávejte ID úkolu pro účely ladění. Uveďte ho při kontaktování podpory.
3. Ověřte vstupy. Ujistěte se, že vaše vstupní obrázky a modely splňují požadavky na formát před odesláním.