Chyby

V této příručce si povíme, 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. Zkontrolujte stavový kód HTTP a pole message, abyste pochopili, co se pokazilo.

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

Chyby úloh

Tyto chyby nastávají poté, co byla úloha vytvořena a zpracovává se. Podrobnosti o chybě najdete v objektu task_error v odpovědi úlohy.

{
  "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ěluje obecnou kategorii selhání. Použijte ho k rozhodnutí o strategii opakování.

Kódy chyb

Když je přítomno pole code, identifikuje konkrétní problém, na který lze reagovat. Níže je kompletní reference pro každý kód chyby.

image_too_complex

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

Mezi běžné příklady patří:

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

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 objektem. Nezahrnujte do stejného obrázku nebo promptu více samostatných objektů.
2. Zjednodušte svůj objekt. Snižte úroveň detailů. Například jednoduchá váza místo vázy naplněné desítkami 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. Místo toho se zaměřte na jeden objekt.
4. Vyhněte se hustým opakujícím se strukturám. Objekty jako lešení, drátěné sítě, mřížové vzory nebo hromady mnoha malých položek jsou běžnými spouštěči.

model_missing_uv

K této chybě dochází, když nahrajete model pro texturování s enable_original_uv nastaveným na true, ale model nemá žádné UV souřadnice. UV souřadnice určují, jak se 2D textura obalí kolem 3D povrchu 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í svého modelu (např. vlastní umístění švů pro přesné mapování textury): váš model musí mít platné UV souřadnice. Před nahráním ověřte, že UV existují v UV editoru vašeho 3D softwaru. Upozorňujeme, že soubory STL nemohou ukládat UV data, proto místo toho použijte GLB, FBX nebo OBJ.
• Pokud nepotřebujete konkrétní kontrolu nad UV (nebo si nejste jisti): vynechte enable_original_uv nebo jej nastavte na false. Systém pro váš model automaticky vygeneruje UV rozvržení. Automaticky vygenerované UV 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í. Běžně k tomu dochází u modelů exportovaných z 3D nástrojů, které generují zástupné nebo zhroucené 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. Zajistěte, aby byly UV ostrovy správně rozprostřeny po UV prostoru, místo aby byly zhrouceny do malé oblasti.
• Pokud nepotřebujete specifické ovládání UV: vynechte enable_original_uv nebo jej nastavte na false. Systém automaticky vygeneruje nové UV rozvržení. Nevýhodou je, že přijdete o původní umístění švů, ale automaticky vygenerované UV bude mít správné pokrytí pro texturování.

invalid_input

Toto je záložní chybový kód, když vstup neprojde validací, ale nelze použít žádný konkrétnější kód. Pole message obsahuje konkrétní důvod selhání.

Mezi běžné příčiny patří:

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

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

moderation_blocked

K této chybě dochází, když je váš prompt nebo referenční obrázky odmítnuty bezpečnostními filtry AI. Filtr vyhodnocuje textový prompt i všechny referenční obrázky společně.

Řešení:

• Přeformulujte svůj textový prompt tak, 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ší úlohy překročila povolený limit. K tomu může dojít kvůli vysokému zatížení systému nebo proto, že vstup je příliš složitý na zpracování v časovém limitu.

Řešení:

1. Zkuste požadavek zopakovat. Timeouty jsou často přechodné a opakování 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ů ve svém obrázku nebo prompt. Pokyny k tomu, jaké typy vstupů se zpracovávají obtížněji, najdete v části image_too_complex.

format_conversion_failed

K této chybě dochází, když vygenerovaný 3D model nebylo možné 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. Zkuste jiný výstupní formát. Pokud konkrétní formát opakovaně 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 backoffem.
2. Zaznamenávejte ID úloh do logu. Vždy zaznamenávejte ID úlohy do logu pro účely ladění. 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.