Fehler
Finden Sie heraus, warum ein Request oder ein Task fehlgeschlagen ist, und was als Nächstes zu tun ist. Ein Request kann sofort mit einem HTTP-Fehler fehlschlagen, und ein Task kann später mit einem task_error fehlschlagen.
Request errors
Meshy gibt diese Fehler sofort zurück, wenn eine Anfrage abgelehnt wird. Um herauszufinden, was schiefgelaufen ist, prüfen Sie den HTTP-Statuscode und das Feld message.
Antwortformat
Die Fehlerantwort enthält ein Feld message, das beschreibt, was schiefgelaufen ist:
- Name
- message
- Type
- string
- Description
Eine kurze Beschreibung des Fehlers.
Statuscodes
- Name
2xx- Description
Erfolg.
- Name
200 - OK- Description
Die Anfrage war erfolgreich.
- Name
202 - Accepted- Description
Meshy hat die Anfrage akzeptiert, und die Verarbeitung ist noch nicht abgeschlossen. Zum Beispiel gibt eine Anfrage, die eine Task erstellt,
202zurück.
- Name
4xx- Description
Mit der Anfrage oder Ihrem Konto stimmt etwas nicht. Jeder Status gibt an, was zu tun ist.
- Name
400 - Bad Request- Description
Die Anfrage ist ungültig, oft weil ein erforderlicher Parameter fehlt oder ein Parameter fehlerhaft formatiert ist.
- Name
401 - Unauthorized- Description
Der API-Schlüssel fehlt, ist ungültig oder kann nicht auf diesen Endpunkt zugreifen. Siehe Authentifizierung.
- Name
402 - Payment Required- Description
Das Konto des API-Schlüssels hat nicht genug Credits für die Anfrage. Im Free-Plan geben die meisten Anfragen, die eine Task erstellen, ebenfalls
402zurück.
- Name
403 - Forbidden- Description
Sie dürfen diese Anfrage nicht stellen, zum Beispiel aus einem dieser Gründe:
- Die Anfrage kam von einer Adresse außerhalb der IP-Zulassungsliste des API-Schlüssels.
- Die IP-Filterung Ihrer Organisation hat beim Lesen einer Task deren Dateien blockiert.
- Der Endpunkt ist in Ihrem Plan nicht verfügbar.
- Die Inhaltsmoderation hat die Eingabe blockiert. Manche Endpunkte geben dafür stattdessen
400zurück; jede Endpunkt-Seite listet ihre Codes auf. - Der API-Schlüssel gehört einem Teammitglied, das im Team nicht mehr aktiv ist.
- Das Konto ist gesperrt.
- Name
404 - Not Found- Description
Die Ressource existiert nicht. Zum Beispiel gibt das Abrufen einer Task mit einer ID, die nicht existiert,
404zurück.
- Name
409 - Conflict- Description
Die Ressource existiert, aber ihr Zustand erlaubt den Vorgang nicht. Zum Beispiel gibt das Löschen einer Task mit dem Status
IN_PROGRESS409zurück, da Meshy eine Task, die ein Worker bereits gestartet hat, nicht zurückerstatten kann. Die Task läuft weiter. Warten Sie auf einen finalen Status (SUCCEEDED,FAILEDoderCANCELED) und löschen Sie die Task dann.
- Name
422 - Unprocessable Entity- Description
Die Anfrage ist gültig, aber Meshy kann ihre Eingabe nicht verarbeiten. Zum Beispiel gibt Rigging
422zurück, wenn es im Modell keinen humanoiden Körper findet.
- Name
429 - Too Many Requests- Description
Sie haben zu viele Anfragen gesendet, oder zu viele Ihrer Tasks sind in der Warteschlange oder werden ausgeführt. Wenn die Antwort einen
Retry-After-Header enthält, warten Sie die angegebene Anzahl Sekunden und versuchen Sie es erneut. Siehe Rate limits.
- Name
5xx- Description
Auf Seiten von Meshy ist etwas schiefgelaufen. Versuchen Sie es mit exponentiellem Backoff erneut. Besteht der Fehler weiterhin, prüfen Sie die Statusseite und kontaktieren Sie uns auf Discord.
Example: 400 Bad Request
{
"message": "Invalid model file extension: .3dm"
}
Task errors
Ein Task, den Meshy erstellt hat, kann während der Ausführung trotzdem fehlschlagen. Sein status wird zu FAILED, Meshy erstattet die Credits, und task_error erklärt, warum.
Der task_error eines fehlgeschlagenen Tasks hat diese Felder:
- Name
- type
- Type
- string
- Description
Die Fehlerkategorie. Sie ist bei einem fehlgeschlagenen Task immer vorhanden. Entscheiden Sie anhand dieses Werts, ob ein erneuter Versuch sinnvoll ist. Siehe Error types.
- Name
- message
- Type
- string
- Description
Eine für Menschen lesbare Beschreibung des Fehlers. Sie ist bei einem fehlgeschlagenen Task immer vorhanden.
- Name
- code
- Type
- string
- Optional
- Description
Ein konkretes, dokumentiertes Problem, auf das Sie reagieren können. Vorhanden, wenn Meshy weitere Details liefert. Siehe Error codes. Meshy kann neue Codes hinzufügen. Behandeln Sie daher einen unbekannten Code anhand seines
type.
- Name
- doc_url
- Type
- string
- Optional
- Description
Ein Link zum entsprechenden Eintrag des Codes auf dieser Seite, der beschreibt, was zu tun ist. Vorhanden, wenn
codevorhanden ist.
Error with details
{
"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"
}
}
Error without details
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"status": "FAILED",
"task_error": {
"type": "server_error",
"message": "An internal error occurred. Please retry."
}
}
Fehlertypen
type ist die übergeordnete Kategorie des Fehlers. Nutze sie, um zu entscheiden, wie weiter vorzugehen ist.
- Name
invalid_input- Description
Mit der von dir gesendeten Eingabe stimmt etwas nicht. Lies
codeundmessage, korrigiere die Eingabe und erstelle eine neue Aufgabe.
- Name
timeout- Description
Die Aufgabe hat ein serverseitiges Zeitlimit überschritten, entweder bei der Verarbeitung oder beim Warten in der Warteschlange, und ist fehlgeschlagen. Meshy erstattet die dafür verwendeten Credits zurück. Dies ist oft nur vorübergehend. Erstelle die Aufgabe erneut, und falls sie weiterhin fehlschlägt, versuche es mit einer einfacheren Eingabe.
- Name
service_unavailable- Description
Der Dienst war vorübergehend nicht verfügbar. Warte einen Moment und erstelle die Aufgabe dann erneut.
- Name
server_error- Description
Während der Ausführung der Aufgabe ist auf Seiten von Meshy etwas schiefgelaufen. Erstelle die Aufgabe erneut. Falls sie weiterhin fehlschlägt, wende dich mit der Aufgaben-ID an den Support.
Fehlercodes
Wenn code vorhanden ist, bezeichnet es eines der folgenden Probleme.
image_too_complex
Das Eingabebild oder der prompt beschreibt ein Motiv, das geometrisch zu komplex für die 3D-Generierung ist.
Zum Beispiel:
- Dichte Ansammlungen kleiner Objekte, etwa eine Kiste voller Früchte oder ein Bücherstapel
- Komplizierte, sich wiederholende Muster, etwa Gitterstrukturen, Gerüste oder Drahtgeflechte
- Komplexe Gebäude, etwa mehrstöckige Gebäude mit vielen Fenstern und Balkonen
- Mehrere unterschiedliche Objekte in einem Bild, anstelle eines einzelnen Motivs
Diese Eingaben sind wahrscheinlich zu komplex:




Um das Problem zu beheben, versuchen Sie eine oder mehrere der folgenden Maßnahmen:
- Verwenden Sie pro Bild ein Objekt. Meshy funktioniert am besten mit einem klaren Motiv, platzieren Sie daher nicht mehrere separate Objekte im selben Bild oder prompt.
- Vereinfachen Sie Ihr Motiv. Verwenden Sie zum Beispiel eine einfache Vase anstelle einer mit Dutzenden von Blumen gefüllten Vase.
- Vermeiden Sie Szenen. Ganze Gebäude, Straßenzüge, eingerichtete Räume und Landschaften sind wahrscheinlich zu viel. Konzentrieren Sie sich auf ein einzelnes Objekt.
- Vermeiden Sie dichte, sich wiederholende Strukturen. Gerüste, Drahtgeflechte, Gitterstrukturen und Ansammlungen kleiner Gegenstände sind häufige Auslöser.
model_missing_uv
Sie haben ein Modell mit auf true gesetztem enable_original_uv zur Texturierung gesendet, aber das Modell hat keine UV-Koordinaten. UV-Koordinaten definieren, wie eine 2D-Textur auf die 3D-Oberfläche abgebildet wird.

Um das Problem zu beheben, führen Sie eine der folgenden Maßnahmen durch:
- Um das eigene UV-Layout Ihres Modells beizubehalten, zum Beispiel für eine benutzerdefinierte Nahtplatzierung, fügen Sie dem Modell in Ihrer 3D-Software UVs hinzu. Überprüfen Sie diese im UV-Editor der Software und laden Sie das Modell dann erneut hoch. STL-Dateien können keine UVs speichern, verwenden Sie daher GLB, FBX oder OBJ.
- Wenn Sie kein eigenes Layout benötigen oder sich nicht sicher sind, lassen Sie
enable_original_uvweg oder setzen Sie es auffalse. Meshy erstellt dann ein UV-Layout für das Modell. Die neuen UVs decken das Modell gut ab, allerdings können Sie nicht steuern, wo die Textur-Nähte verlaufen.
model_insufficient_uv
Das Modell verfügt über UV-Koordinaten, diese decken jedoch zu wenig vom UV-Raum ab, um gut texturiert werden zu können. Dies kommt häufig bei Modellen vor, deren Exporter Platzhalter- oder zusammengefallene UVs ohne ein richtiges Unwrap geschrieben hat.

Um das Problem zu beheben, führen Sie eine der folgenden Maßnahmen durch:
- Um Ihr eigenes UV-Layout zu behalten, entpacken Sie die UVs des Modells in Ihrer 3D-Software erneut. Verteilen Sie die Inseln über den UV-Raum, statt sie in einer kleinen Ecke davon zu belassen.
- Wenn Sie Ihr eigenes Layout nicht benötigen, lassen Sie
enable_original_uvweg oder setzen Sie es auffalse. Meshy erstellt dann ein neues UV-Layout. Sie verlieren zwar Ihre Nahtplatzierung, aber die neuen UVs decken genügend Raum ab, um texturiert zu werden.
model_missing_texture
Das Eingabemodell einer Multi-Color Print-Aufgabe hat keine Farbe, die Meshy in Druckfarben aufteilen kann. Meshy erstellt ein Mehrfarben-3MF aus den Farben des Modells, daher gibt es bei einem einfarbig weißen Netz nichts, womit gearbeitet werden kann. Eine Text-zu-3D- oder Bild-zu-3D-Vorschau, die nie texturiert wurde, hat beispielsweise keine Farbe. Das Gleiche gilt für die Ausgabe von „Druckbarkeit reparieren“ oder für eine Auto-Split-Aufgabe, bei der die Textur nicht erhalten blieb.
Was als Farbe zählt, hängt vom angeforderten style ab:
realistictastet die Basisfarbtextur anhand der UVs des Modells ab. Dafür wird eine einzelne Basisfarbtextur sowie UVs für jedes Netzteil benötigt.cartoonglättet die Farben pro Fläche. Dabei wird eine Basisfarbtextur auf einem beliebigen Teil oder Farben pro Vertex (COLOR_0) akzeptiert.
Meshy lehnt ein Modell, das weder eine Basisfarbtextur noch Vertex-Farben besitzt, für beide Stile ab, statt es cartoon in einen Einfarbdruck umwandeln zu lassen.
Meshy weist die meisten dieser Anfragen bereits ab, bevor die Aufgabe erstellt wird, und liefert dabei einen 400-Status mit derselben Erklärung. Diesen Code erhält man in der Regel nur dann, wenn Meshy die Eingabe nicht im Voraus prüfen kann. Beispielsweise prüft Meshy einen .fbx-Upload erst, nachdem die Aufgabe ihn konvertiert hat.
Um das Problem zu beheben, verwenden Sie die Option, die zu Ihrem Modell passt:
- Texturieren Sie das Modell zuerst. Führen Sie dazu Retexture darauf aus, oder generieren Sie es mit einer Text-zu-3D-refine-Aufgabe oder einer Bild-zu-3D-Aufgabe mit
should_texture: true. Senden Sie diese Aufgabe anschließend alsinput_task_id. - Verwenden Sie für ein vertex-gefärbtes Modell, etwa einen Photogrammetrie-Scan oder ein handbemaltes Netz,
style: "cartoon", dasCOLOR_0ausliest. - Geben Sie bei einem teilweise texturierten oder Mehrfachtextur-Modell mit
realisticjedem Netzteil UVs und dieselbe einzelne Basisfarbtextur. Texturieren Sie dazu die verbleibenden Teile, oder führen Sie die Texturen in einem einzigen Atlas zusammen. Sie können auch zustyle: "cartoon"wechseln.
textured_split_refused
Eine Auto Split-Aufgabe mit keep_texture: true kann die Textur des Eingabemodells nicht auf den Teilen beibehalten. Zum Beispiel hat das Modell keine UVs, oder seine Textur bietet keinen Platz für die neuen Flächen, die durch die Schnitte entstehen. Meshy erstattet die Credits zurück.
Um dies zu beheben, senden Sie die Anfrage erneut ohne keep_texture oder mit keep_texture: false. Die Teile kommen dann jeweils mit einer einfarbigen Farbe zurück.
invalid_input
Die Eingabe hat eine Prüfung nicht bestanden, und kein spezifischerer Code trifft zu. message gibt den Grund an.
Zum Beispiel:
- Eine leere oder beschädigte Modelldatei
- Eine nicht unterstützte Variante eines Dateiformats, wie etwa eine ASCII-FBX-Datei oder eine meshopt-komprimierte GLB-Datei
- Ein hochgeladenes Modell ohne gültige 3D-Objekte, zum Beispiel eine Datei, die nur Armaturen, Kameras oder Lichter enthält
- Inhalte, die Sicherheitsfilter nicht bestehen
Um dies zu beheben, lesen Sie message für das spezifische Problem. Prüfen Sie, ob Ihre Eingabedateien und Parameter die Anforderungen des Endpunkts erfüllen.
moderation_blocked
Sicherheitsfilter haben deinen prompt oder deine Referenzbilder abgelehnt. Die Filter prüfen Text und Bilder gemeinsam.
Um das Problem zu beheben, führe eine oder beide der folgenden Maßnahmen durch:
- Formuliere den prompt um, um anzügliche oder sensible Beschreibungen zu entfernen.
- Ändere Referenzbilder, die Inhalte zeigen, die von den Filtern blockiert werden könnten.
moderation_unavailable
Typ: server_error. Die moderation von Inhalten war vorübergehend nicht verfügbar, sodass Meshy den Task als fehlgeschlagen markiert hat, anstatt die Prüfung zu überspringen. Mit deinem Inhalt ist nichts falsch.
Um das Problem zu beheben, erstelle den Task erneut.
timeout
Die Aufgabe hat ein serverseitiges Zeitlimit überschritten, entweder bei der Verarbeitung oder beim Warten in der Warteschlange. Deshalb hat Meshy sie als fehlgeschlagen markiert und die Credits erstattet. Hohe Auslastung oder eine Eingabe, die zu komplex ist, um rechtzeitig fertig zu werden, kann dies verursachen.
Dies unterscheidet sich von einem timeout in Ihrem eigenen Code. Wenn Ihr Client das Warten beendet hat, läuft die Aufgabe weiterhin. Siehe Wie lange warten.
Um das Problem zu beheben, befolgen Sie diese Schritte:
- Erstellen Sie die Aufgabe erneut. timeouts sind oft vorübergehend, und eine neue Aufgabe könnte erfolgreich sein.
- Wenn es weiterhin fehlschlägt, vereinfachen Sie Ihre Eingabe, zum Beispiel indem Sie die Detailtiefe Ihres Bildes oder prompt reduzieren. Für Eingaben, die schwerer zu verarbeiten sind, siehe
image_too_complex.
queue_timeout
Typ: timeout. Die Aufgabe wartete zu lange in der Warteschlange, ohne gestartet zu werden. Daher hat Meshy sie als fehlgeschlagen markiert und alle dafür berechneten Credits zurückerstattet. Ihre Eingabe hat diesen Fehler nicht verursacht.
Um das Problem zu beheben, erstellen Sie die Aufgabe erneut.
format_conversion_failed
Meshy hat das Modell generiert, aber die Konvertierung in das von Ihnen angeforderte Format ist fehlgeschlagen.
Gehen Sie zur Behebung wie folgt vor:
- Erstellen Sie die Aufgabe erneut.
- Wenn ein bestimmtes Format wiederholt fehlschlägt, fordern Sie ein anderes Format an, das Ihren Anforderungen entspricht.
Bewährte Praktiken
- Fehlgeschlagene Aufgaben wiederholen. Erstellen Sie bei einer fehlgeschlagenen Aufgabe mit
timeout,service_unavailableoderserver_erroreine neue Aufgabe mit exponentiellem Backoff. - Erstellen Sie keine neue Aufgabe, wenn Ihre eigene Anfrage ein Timeout aufweist. Die erste Aufgabe läuft möglicherweise noch, prüfen Sie daher, ob sie bereits existiert, bevor Sie eine weitere erstellen. Siehe Wie lange warten.
- Protokollieren Sie Aufgaben-IDs. Geben Sie die ID an, wenn Sie den Support kontaktieren.
- Überprüfen Sie Eingaben, bevor Sie sie senden. Stellen Sie sicher, dass Bilder und Modelle die Formatanforderungen des Endpunkts erfüllen.
- Rufen Sie die API von Ihrem Server aus auf. Code, der im Browser ausgeführt wird, legt Ihren API-Schlüssel gegenüber jedem offen, der die Seite öffnet.