Chyby

V této příručce si povíme o tom, co se stane, když se při práci s Meshy API něco pokazí.

Chyby požadavku

Tyto chyby jsou vráceny okamžitě, když je váš API požadavek odmítnut. Pro zjištění, co se pokazilo, zkontrolujte HTTP stavový kód a pole message.

{
  "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 udává širokou kategorii selhání. Použijte ho k rozhodnutí o 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 zamítnuty bezpečnostními filtry AI. Filtr vyhodnocuje společně jak textový prompt, tak všechny referenční obrázky.

Řešení:

• Přeformulujte svůj textový prompt tak, aby neobsahoval sugestivní nebo citlivé popisy.
• Upravte referenční obrázky, pokud zobrazují obsah, který by mohl spustit bezpečnostní filtry.

moderation_unavailable

Tato chyba nastane, když byla moderation obsahu dočasně nedostupná, takže úloha skončila jako neúspěšná místo toho, aby proběhla bez kontroly. S vaším obsahem není nic v pořádku. Jeho type je server_error.

Řešení: Vytvořte úlohu znovu.

timeout

Tato chyba znamená, že úloha překročila časový limit na straně serveru, ať už při zpracování, nebo při čekání ve frontě, takže se úloha nezdařila a její kredity byly vráceny. Může k tomu dojít kvůli vysokému zatížení systému nebo proto, že vstup je příliš složitý na zpracování v rámci časového limitu.

To je něco jiného než timeout ve vašem vlastním kódu. Pokud váš klient přestal čekat, úloha stále běží; viz Task Lifecycle.

Řešení:

1. Vytvořte úlohu znovu. Timeouty jsou často dočasné a nová úloha může uspět.
2. Zjednodušte svůj vstup. Pokud opakované pokusy stále selhávají, váš vstup může být příliš složitý. Zkuste snížit úroveň detailů v obrázku nebo promptu. Pokyny k tomu, jaké typy vstupů jsou obtížnější na zpracování, najdete v části image_too_complex.

queue_timeout

Tato chyba znamená, že úloha čekala ve frontě příliš dlouho a nebyla spuštěna, takže selhala a veškeré kredity účtované za ni byly vráceny. Nezpůsobil ji váš vstup. Její type je timeout.

Řešení: Vytvořte úlohu znovu.

format_conversion_failed

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

Řešení:

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

Best Practices

1. Implementujte logiku opakování. Pokud úloha selže s chybou timeout, service_unavailable nebo server_error, vytvořte ji znovu s exponenciálním zpožděním. Pokud místo toho vypršel časový limit vašeho vlastního požadavku, nevytvářejte novou úlohu: nejprve zkontrolujte tu stávající (viz Životní cyklus úlohy).
2. Zaznamenávejte ID úloh. Vždy si pro účely ladění zaznamenejte ID úlohy. Uveďte ho při kontaktování podpory.
3. Ověřujte vstupy. Před odesláním se ujistěte, že vaše vstupní obrázky a modely splňují požadavky na formát.
4. Volejte API ze svého serveru. Kód spuštěný v prohlížeči by váš API klíč vystavil komukoli, kdo stránku otevře.