Fehler

In diesem Leitfaden werden wir darüber sprechen, was passiert, wenn etwas schiefgeht, während Sie mit der Meshy API arbeiten.

Anforderungsfehler

Diese Fehler werden sofort zurückgegeben, wenn Ihre API-Anfrage abgelehnt wird. Überprüfen Sie den HTTP-Statuscode und das message-Feld, um zu verstehen, was schiefgelaufen ist.

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

Aufgabenfehler

Diese Fehler treten auf, nachdem eine Aufgabe erstellt wurde und verarbeitet wird. Überprüfen Sie das task_error-Objekt in der Aufgabenantwort für Fehlerdetails.

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

Das type-Feld gibt Ihnen die allgemeine Kategorie des Fehlers an. Verwenden Sie es, um Ihre Wiederholungsstrategie zu entscheiden.

Fehlercodes

Wenn das code-Feld vorhanden ist, identifiziert es ein spezifisches, umsetzbares Problem. Unten ist die vollständige Referenz für jeden Fehlercode.

image_too_complex

Dieser Fehler tritt auf, wenn das Eingabebild oder der prompt ein Thema beschreibt, das für das 3D-Generierungsmodell geometrisch zu komplex ist, um es zu verarbeiten.

Häufige Beispiele sind:

• Dichte Haufen kleiner Objekte (z. B. eine Kiste voller Früchte, ein Stapel Bücher)
• Komplexe sich wiederholende Muster (z. B. Gitterstrukturen, Gerüste, Drahtgitter)
• Komplexe Gebäudestrukturen (z. B. mehrstöckige Gebäude mit vielen Fenstern und Balkonen)
• Mehrere unterschiedliche Objekte in einem Bild anstelle eines einzelnen Motivs

Beispiele für Eingaben, die wahrscheinlich zu komplex sind:

Lösung:

1. Verwenden Sie ein einzelnes Objekt pro Bild. Das Modell funktioniert am besten mit einem klaren Motiv. Fügen Sie nicht mehrere separate Objekte in dasselbe Bild oder prompt ein.
2. Vereinfachen Sie Ihr Motiv. Reduzieren Sie den Detailgrad. Zum Beispiel eine einfache Vase anstelle einer Vase, die mit Dutzenden von Blumen gefüllt ist.
3. Vermeiden Sie Szenen-Ebene prompts. Ganze Gebäude, Stadtblöcke, Innenräume voller Möbel oder Landschaften überschreiten wahrscheinlich die Kapazität des Modells. Konzentrieren Sie sich stattdessen auf ein einzelnes Objekt.
4. Vermeiden Sie dichte sich wiederholende Strukturen. Motive wie Gerüste, Drahtgitter, Gittermuster oder Haufen vieler kleiner Gegenstände sind häufige Auslöser.

model_missing_uv

Dieser Fehler tritt auf, wenn Sie ein Modell zum Texturieren hochladen und enable_original_uv auf true gesetzt ist, aber das Modell keine UV-Koordinaten hat. UV-Koordinaten definieren, wie eine 2D-Textur auf die 3D-Oberfläche Ihres Modells projiziert wird.

Lösung:

Die richtige Lösung hängt davon ab, warum Sie enable_original_uv auf true gesetzt haben:

• Wenn Sie das ursprüngliche UV-Layout Ihres Modells beibehalten müssen (z.B. benutzerdefinierte Nahtplatzierung für präzises Textur-Mapping): Ihr Modell muss gültige UV-Koordinaten haben. Überprüfen Sie, ob UVs in Ihrem 3D-Software-UV-Editor vorhanden sind, bevor Sie hochladen. Beachten Sie, dass STL-Dateien keine UV-Daten speichern können, verwenden Sie stattdessen GLB, FBX oder OBJ.
• Wenn Sie keine spezifische UV-Kontrolle benötigen (oder Sie sind sich nicht sicher): Lassen Sie enable_original_uv weg oder setzen Sie es auf false. Das System generiert automatisch ein UV-Layout für Ihr Modell. Die automatisch generierten UVs sind für die Abdeckung optimiert, aber Sie haben keine Kontrolle darüber, wo Textur-Nähte platziert werden.

model_insufficient_uv

Dieser Fehler tritt auf, wenn ein Modell UV-Koordinaten hat, aber die UV-Abdeckung zu klein für eine qualitativ hochwertige Texturierung ist. Dies passiert häufig bei Modellen, die aus 3D-Tools exportiert werden, die Platzhalter- oder zusammengefallene UVs ohne ein richtiges Unwrapping erzeugen.

Lösung:

• Wenn Sie Ihr ursprüngliches UV-Layout beibehalten müssen: Wickeln Sie die UVs des Modells in Ihrer 3D-Software neu ab. Stellen Sie sicher, dass die UV-Inseln richtig über den UV-Raum verteilt sind, anstatt in einem kleinen Bereich zusammenzufallen.
• Wenn Sie keine spezifische UV-Kontrolle benötigen: lassen Sie enable_original_uv weg oder setzen Sie es auf false. Das System generiert automatisch ein neues UV-Layout. Der Kompromiss besteht darin, dass Sie Ihre ursprüngliche Nahtplatzierung verlieren, aber die automatisch generierten UVs werden eine ordnungsgemäße Abdeckung für die Texturierung haben.

invalid_input

Dies ist der Standard-Fehlercode, wenn die Eingabe die Validierung nicht besteht, aber kein spezifischerer Code zutrifft. Das message-Feld enthält den spezifischen Grund für das Scheitern.

Häufige Ursachen sind:

• Leere oder beschädigte Modelldateien
• Nicht unterstützte Dateiformatvarianten (z.B. ASCII FBX-Dateien, meshopt-komprimierte GLB)
• Keine gültigen 3D-Objekte im hochgeladenen Modell gefunden (z.B. Datei enthält nur Armaturen, Kameras oder Lichter)
• Inhalte, die die Sicherheitsfilter nicht bestehen

Lösung: Überprüfen Sie das message-Feld für Details, was schiefgelaufen ist. Stellen Sie sicher, dass Ihre Eingabedateien und Parameter den Anforderungen des Endpunkts entsprechen.

moderation_blocked

Dieser Fehler tritt auf, wenn Ihr Prompt oder Referenzbilder von den AI-Sicherheitsfiltern abgelehnt werden. Der Filter bewertet sowohl den Text-Prompt als auch alle Referenzbilder zusammen.

Lösung:

• Formulieren Sie Ihren Text-Prompt um, um suggestive oder sensible Beschreibungen zu entfernen.
• Passen Sie Referenzbilder an, wenn sie Inhalte darstellen, die Sicherheitsfilter auslösen könnten.

timeout

Dieser Fehler bedeutet, dass die Bearbeitungszeit Ihrer Aufgabe das erlaubte Limit überschritten hat. Dies kann aufgrund hoher Systemauslastung oder weil die Eingabe zu komplex ist, um innerhalb des Zeitlimits verarbeitet zu werden, passieren.

Lösung:

1. Versuchen Sie es erneut. Timeouts sind oft vorübergehend und ein erneuter Versuch kann erfolgreich sein.
2. Vereinfachen Sie Ihre Eingabe. Wenn wiederholte Versuche fehlschlagen, könnte Ihre Eingabe zu komplex sein. Versuchen Sie, den Detaillierungsgrad in Ihrem Bild oder Prompt zu reduzieren. Siehe image_too_complex für Hinweise, welche Arten von Eingaben schwerer zu verarbeiten sind.

format_conversion_failed

Dieser Fehler tritt auf, wenn das generierte 3D-Modell nicht in das angeforderte Ausgabeformat konvertiert werden konnte. Das Modell wurde erfolgreich generiert, aber der Konvertierungsschritt ist fehlgeschlagen.

Lösung:

1. Versuchen Sie es erneut.
2. Versuchen Sie ein anderes Ausgabeformat. Wenn ein bestimmtes Format immer wieder fehlschlägt, wechseln Sie zu einem anderen Format, das Ihren Anforderungen entspricht.

Beste Praktiken

1. Implementieren Sie eine Wiederholungslogik. Für timeout und service_unavailable Fehler implementieren Sie eine exponentielle Backoff-Wiederholungslogik.
2. Protokollieren Sie die Aufgaben-IDs. Protokollieren Sie immer die Aufgaben-ID zu Debugging-Zwecken. Geben Sie sie an, wenn Sie den Support kontaktieren.
3. Validieren Sie Eingaben. Stellen Sie sicher, dass Ihre Eingabebilder und Modelle die Formatvorgaben erfüllen, bevor Sie sie einreichen.