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.

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

Fehler bei Tasks

Ein von Meshy erstellter Task kann während der Ausführung dennoch fehlschlagen. Sein status wird zu FAILED, Meshy erstattet die Credits dafür, und task_error erklärt den Grund.

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

Fehlertypen

type ist die übergeordnete Kategorie des Fehlers. Nutze sie, um zu entscheiden, was als Nächstes zu tun ist.

Error codes

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, Baugerüste oder Drahtgeflechte
• Komplexe Gebäude, etwa mehrstöckige Gebäude mit vielen Fenstern und Balkonen
• Mehrere unterschiedliche Objekte in einem Bild, anstatt eines einzelnen Motivs

Diese Eingaben sind wahrscheinlich zu komplex:

Um das Problem zu beheben, versuchen Sie eines oder mehrere der folgenden Dinge:

• Verwenden Sie ein Objekt pro Bild. 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 beispielsweise eine einfache Vase anstelle einer mit Dutzenden von Blumen gefüllten Vase.
• Vermeiden Sie Szenen. Ganze Gebäude, Häuserblocks, möblierte Räume und Landschaften sind wahrscheinlich zu viel. Konzentrieren Sie sich auf ein einzelnes Objekt.
• Vermeiden Sie dichte, sich wiederholende Strukturen. Baugerüste, Drahtgeflechte, Gitter und Ansammlungen kleiner Gegenstände sind häufige Auslöser.

model_missing_uv

Sie haben ein Modell zur Texturierung mit enable_original_uv auf true 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 anschließend 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_uv weg oder setzen Sie es auf false. 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 Texturnä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 kollabierte UVs ohne ein richtiges Unwrap geschrieben hat.

Um dies zu beheben, führen Sie eine der folgenden Maßnahmen durch:

• Um Ihr eigenes UV-Layout beizubehalten, entpacken Sie die UVs des Modells in Ihrer 3D-Software erneut. Verteilen Sie die Inseln über den gesamten UV-Raum, statt sie in einer kleinen Ecke davon zu belassen.
• Falls Sie Ihr eigenes Layout nicht benötigen, lassen Sie enable_original_uv weg oder setzen Sie es auf false. Meshy erstellt dann ein neues UV-Layout. Sie verlieren dabei Ihre Nahtplatzierung, aber die neuen UVs decken genug 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, sodass ein rein weißes Netz keine Grundlage bietet. Zum Beispiel hat eine Text zu 3D- oder Bild zu 3D-Vorschau, die nie texturiert wurde, keine Farbe. Das Gleiche gilt für die Ausgabe von Druckbarkeit reparieren oder eine Auto Split-Aufgabe, die die Textur nicht beibehalten hat.

Was als Farbe zählt, hängt vom angeforderten style ab:

• realistic tastet die Basisfarbtextur über die UVs des Modells ab. Es benötigt eine einzige Basisfarbtextur und UVs für jedes Netzteil.
• cartoon glättet Farben pro Fläche. Es akzeptiert eine Basisfarbtextur auf einem beliebigen Teil oder Farben pro Scheitelpunkt (COLOR_0).

Meshy lehnt ein Modell ohne Basisfarbtextur und ohne Scheitelpunktfarben für beide Stile ab, anstatt es von cartoon in einen Einfarbendruck umwandeln zu lassen.

Meshy lehnt die meisten dieser Anfragen bereits ab, bevor die Aufgabe erstellt wird, mit einem 400 und derselben Erklärung. Diesen Code erhältst du normalerweise nur dann, wenn Meshy die Eingabe nicht im Voraus prüfen kann. Zum Beispiel prüft Meshy einen .fbx-Upload erst, nachdem die Aufgabe ihn konvertiert hat.

So behebst du das Problem – wähle die Option, die zu deinem Modell passt:

• Texturiere das Modell zuerst. Führe Neutexturierung darauf aus, oder generiere es mit einer Text zu 3D-refine-Aufgabe oder einer Bild zu 3D-Aufgabe mit should_texture: true. Sende diese Aufgabe dann als input_task_id.
• Verwende für ein Modell mit Scheitelpunktfarben, etwa einen Photogrammetrie-Scan oder ein handbemaltes Netz, style: "cartoon", das COLOR_0 ausliest.
• Gib bei einem teilweise texturierten oder Multi-Textur-Modell mit realistic jedem Netzteil UVs und dieselbe einzelne Basisfarbtextur. Texturiere dazu die verbleibenden Teile oder führe die Texturen zu einem Atlas zusammen. Du kannst auch zu style: "cartoon" wechseln.

textured_split_refused

Bei einer Auto Split-Aufgabe mit keep_texture: true kann die Textur des Eingabemodells nicht auf den Teilen beibehalten werden. Zum Beispiel besitzt 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 das zu beheben, senden Sie die Anfrage erneut ohne keep_texture oder mit keep_texture: false. Die Teile kommen dann jeweils mit einer einfarbigen Oberfläche 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, 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 die Sicherheitsfilter nicht bestehen

Um das zu beheben, lesen Sie message für das konkrete Problem. Prüfen Sie, ob Ihre Eingabedateien und Parameter den Anforderungen des Endpunkts entsprechen.

moderation_blocked

Sicherheitsfilter haben Ihren prompt oder Ihre Referenzbilder abgelehnt. Die Filter prüfen Text und Bilder gemeinsam.

Um das Problem zu beheben, tun Sie eines oder beides der folgenden:

• Formulieren Sie den prompt um, um anzügliche oder sensible Beschreibungen zu entfernen.
• Ändern Sie Referenzbilder, die Inhalte zeigen, die von den Filtern blockiert werden könnten.

moderation_unavailable

Typ: server_error. Die Inhaltsmoderation war vorübergehend nicht verfügbar, sodass Meshy die Aufgabe fehlschlagen ließ, anstatt die Prüfung zu überspringen. Mit Ihrem Inhalt stimmt nichts nicht.

Um das Problem zu beheben, erstellen Sie die Aufgabe erneut.

timeout

Die Aufgabe hat ein serverseitiges Zeitlimit überschritten, entweder bei der Verarbeitung oder beim Warten in der Warteschlange. Daraufhin 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.

Gehen Sie zur Behebung wie folgt vor:

1. Erstellen Sie die Aufgabe erneut. Timeouts sind oft vorübergehend, und eine neue Aufgabe könnte erfolgreich sein.
2. Falls sie weiterhin fehlschlägt, vereinfachen Sie Ihre Eingabe, zum Beispiel indem Sie den Detailgrad in Ihrem Bild 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. Meshy hat sie daher als fehlgeschlagen markiert und alle dafür berechneten Credits zurückerstattet. Deine Eingabe hat diesen Fehler nicht verursacht.

Um das Problem zu beheben, erstelle die Aufgabe erneut.

format_conversion_failed

Meshy hat das Modell erstellt, aber die Konvertierung in das von dir angeforderte Format ist fehlgeschlagen.

Um das Problem zu beheben, führe folgende Schritte aus:

1. Erstelle die Aufgabe erneut.
2. Wenn ein bestimmtes Format wiederholt fehlschlägt, fordere ein anderes Format an, das deinen Anforderungen entspricht.

Best practices

• Fehlgeschlagene Aufgaben erneut versuchen. Erstellen Sie bei einer fehlgeschlagenen Aufgabe mit timeout, service_unavailable oder server_error eine neue Aufgabe mit exponentiellem Backoff.
• Erstellen Sie keine neue Aufgabe, wenn Ihre eigene Anfrage ein Timeout verursacht. Die erste Aufgabe läuft möglicherweise noch, prüfen Sie daher, ob sie 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 den Formatanforderungen des Endpunkts entsprechen.
• Rufen Sie die API von Ihrem Server aus auf. Code, der in einem Browser ausgeführt wird, legt Ihren API-Schlüssel für jeden offen, der die Seite öffnet.