Chyby

Zjistěte, proč požadavek nebo úloha selhaly a co dělat dál. Požadavek může selhat okamžitě s HTTP chybou a úloha může selhat později s task_error.

Request errors

Meshy vrací tyto chyby okamžitě, když odmítne požadavek. Chcete-li zjistit, co se pokazilo, zkontrolujte HTTP stavový kód a pole message.

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

Chyby úlohy

Úloha, kterou Meshy vytvořilo, může během běhu přesto selhat. Její status se změní na FAILED, Meshy vrátí její kredity a task_error vysvětlí důvod.

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

type je obecná kategorie selhání. Použijte ji k rozhodnutí, co dělat dál.

Chyby kódů

Pokud je přítomen code, označuje jeden z následujících problémů.

image_too_complex

Vstupní obrázek nebo prompt popisuje subjekt, který je geometricky příliš složitý pro 3D generování.

Například:

• Husté hromady malých objektů, například bedna plná ovoce nebo hromada knih
• Složité opakující se vzory, například mřížové struktury, lešení nebo drátěná pletiva
• Složité budovy, například vícepatrové domy s mnoha okny a balkony
• Několik odlišných objektů na jednom obrázku místo jediného subjektu

Tyto vstupy jsou pravděpodobně příliš složité:

Pro nápravu zkuste jedno nebo více z následujícího:

• Použijte jeden objekt na obrázek. Meshy funguje nejlépe s jedním jasným subjektem, proto nedávejte několik samostatných objektů do stejného obrázku nebo promptu.
• Zjednodušte svůj subjekt. Například použijte jednoduchou vázu místo vázy plné desítek květin.
• Vyhněte se scénám. Celé budovy, městské bloky, zařízené místnosti a krajiny jsou pravděpodobně příliš mnoho. Zaměřte se na jediný objekt.
• Vyhněte se hustým opakujícím se strukturám. Lešení, drátěná pletiva, mřížky a hromady malých předmětů jsou časté příčiny problémů.

model_missing_uv

Odeslali jste model k texturování s enable_original_uv nastaveným na true, ale model nemá UV souřadnice. UV souřadnice definují, jak se 2D textura obtáčí kolem 3D povrchu.

Chybu opravíte jedním z následujících způsobů:

• Chcete-li zachovat vlastní UV rozvržení modelu, například kvůli vlastnímu umístění švů, přidejte do modelu UV souřadnice ve svém 3D softwaru. Zkontrolujte je v jeho UV editoru a poté model nahrajte znovu. Soubory STL neumí UV souřadnice ukládat, proto použijte GLB, FBX nebo OBJ.
• Pokud vlastní rozvržení nepotřebujete, nebo si nejste jisti, vynechejte enable_original_uv nebo jej nastavte na false. Meshy pak pro model vytvoří UV rozvržení. Nové UV souřadnice pokrývají model dobře, ale nemůžete ovlivnit, kam budou umístěny švy textury.

model_insufficient_uv

Model má UV souřadnice, ale pokrývají příliš malou část UV prostoru na to, aby šlo kvalitně texturovat. To se často stává u modelů, jejichž exportér zapsal zástupné nebo zhroucené UV souřadnice bez řádného rozbalení.

Opravíte to jedním z následujících způsobů:

• Pokud chcete zachovat vlastní UV rozvržení, znovu rozbalte UV souřadnice modelu ve svém 3D softwaru. Rozprostřete ostrovy po celém UV prostoru místo do malého rohu.
• Pokud vlastní rozvržení nepotřebujete, vynechte enable_original_uv nebo jej nastavte na false. Meshy pak vytvoří nové UV rozvržení. Přijdete o umístění švů, ale nové UV souřadnice pokrývají dostatek prostoru pro texturování.

model_missing_texture

Vstupní model úlohy Multi-Color Print neobsahuje žádnou barvu, kterou by Meshy mohlo rozdělit do tiskových barev. Meshy vytváří vícebarevné 3MF z barev modelu, takže čistě bílá síť nemá s čím pracovat. Například náhled Text na 3D nebo Obrázek na 3D, který nikdy nebyl texturován, nemá žádnou barvu. Stejně tak ji nemá ani výstup z Opravit tisknutelnost, ani úloha Auto Split, která texturu neuchovala.

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

• realistic vzorkuje texturu základní barvy prostřednictvím UV souřadnic modelu. Vyžaduje jedinou texturu základní barvy a UV souřadnice na každé části sítě.
• cartoon zplošťuje barvy po jednotlivých plochách. Přijímá texturu základní barvy na libovolné části, nebo barvy po vrcholech (COLOR_0).

Meshy odmítne model bez textury základní barvy i bez barev vrcholů u obou stylů, místo aby nechalo cartoon převést jej na jednobarevný tisk.

Meshy odmítne většinu těchto požadavků ještě před vytvořením úlohy, s kódem 400 a stejným vysvětlením. Tento kód obvykle dostanete pouze tehdy, když Meshy nemůže zkontrolovat vstup předem. Například nahraný soubor .fbx Meshy zkontroluje až poté, co úloha provede jeho konverzi.

Pro opravu použijte možnost, která odpovídá vašemu modelu:

• Nejprve model texturujte. Spusťte na něm Retexturování, nebo jej vygenerujte pomocí refine úlohy Text na 3D nebo úlohy Obrázek na 3D s should_texture: true. Poté tuto úlohu odešlete jako input_task_id.
• U modelu s barvami vrcholů, jako je fotogrammetrický sken nebo ručně malovaná síť, použijte style: "cartoon", který čte COLOR_0.
• U částečně texturovaného modelu nebo modelu s více texturami se stylem realistic přidejte UV souřadnice a stejnou jedinou texturu základní barvy ke každé části sítě. To provedete tak, že texturujete zbývající části, nebo sloučíte textury do jednoho atlasu. Můžete také přepnout na style: "cartoon".

textured_split_refused

Úloha Auto Split s keep_texture: true nemůže na dílech zachovat texturu vstupního modelu. Může to být například proto, že model nemá UV mapování, nebo jeho textura nemá místo pro nové plochy vzniklé řezy. Meshy kredity vrátí.

Chcete-li problém vyřešit, odešlete požadavek znovu bez keep_texture, nebo s keep_texture: false. Díly se pak vrátí každý s jednou plnou barvou.

invalid_input

Vstup neprošel kontrolou a nelze použít žádný konkrétnější kód. Důvod uvádí message.

Například:

• Prázdný nebo poškozený soubor modelu
• Nepodporovaná varianta formátu souboru, například ASCII soubor FBX nebo soubor GLB komprimovaný pomocí meshopt
• Nahraný model bez platných 3D objektů, například soubor obsahující pouze kostry (armatures), kamery nebo světla
• Obsah, který neprojde bezpečnostními filtry

Chcete-li problém vyřešit, přečtěte si v message konkrétní popis problému. Zkontrolujte, zda vaše vstupní soubory a parametry splňují požadavky koncového bodu.

moderation_blocked

Bezpečnostní filtry odmítly váš prompt nebo referenční obrázky. Filtry kontrolují text a obrázky společně.

Chcete-li to opravit, proveďte jedno nebo obojí z následujícího:

• Přeformulujte prompt tak, aby neobsahoval sugestivní nebo citlivé popisy.
• Změňte referenční obrázky, které zobrazují obsah, jenž by filtry mohly blokovat.

moderation_unavailable

Typ: server_error. Moderace obsahu byla dočasně nedostupná, takže Meshy úlohu označil jako neúspěšnou místo toho, aby kontrolu přeskočil. S vaším obsahem není nic v pořádku.

Chcete-li to opravit, vytvořte úlohu znovu.

timeout

Úloha překročila časový limit na straně serveru, ať už při zpracování, nebo při čekání ve frontě, takže ji Meshy vyhodnotil jako neúspěšnou a vrátil za ni kredity. Může to způsobit vysoké zatížení nebo vstup, který je příliš složitý na to, aby se zpracoval včas.

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 Jak dlouho čekat.

Chcete-li problém vyřešit, postupujte podle těchto kroků:

1. Vytvořte úlohu znovu. Timeouty bývají často dočasné a nová úloha může uspět.
2. Pokud úloha selhává opakovaně, zjednodušte svůj vstup, například snížením detailů v obrázku nebo promptu. Pro vstupy, které se obtížněji zpracovávají, viz image_too_complex.

queue_timeout

Typ: timeout. Úloha čekala ve frontě příliš dlouho a nebyla zahájena, takže ji Meshy vyhodnotilo jako neúspěšnou a vrátilo veškeré kredity za ni účtované. Tuto chybu nezpůsobil váš vstup.

Pro nápravu úlohu vytvořte znovu.

format_conversion_failed

Meshy model vygenerovalo, ale jeho převod do požadovaného formátu se nezdařil.

Pro nápravu postupujte takto:

1. Vytvořte úlohu znovu.
2. Pokud se u jednoho formátu chyba opakuje, vyžádejte si jiný formát, který vyhovuje vašim potřebám.

Best practices

• Opakujte neúspěšné úlohy. U neúspěšné úlohy se stavem timeout, service_unavailable nebo server_error vytvořte novou úlohu s exponenciálním zpožděním (exponential backoff).
• Nevytvářejte novou úlohu, když vyprší časový limit vašeho vlastního požadavku. První úloha může stále běžet, proto před vytvořením další úlohy ověřte, zda již existuje. Viz Jak dlouho čekat.
• Zaznamenávejte ID úloh. Při kontaktování podpory toto ID uveďte.
• Před odesláním vstupů je zkontrolujte. Ujistěte se, že obrázky a modely splňují formátové požadavky koncového bodu.
• Volejte API ze svého serveru. Kód běžící v prohlížeči vystavuje váš API klíč komukoli, kdo stránku otevře.