Fehler

In diesem Leitfaden erläutern wir, was passiert, wenn etwas schiefgeht, während Sie mit der Meshy API arbeiten.

Anfragefehler

Diese Fehler werden sofort zurückgegeben, wenn deine API-Anfrage abgelehnt wird. Prüfe den HTTP-Statuscode und das Feld message, 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. Prüfen Sie das Objekt task_error in der Aufgabenantwort auf 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 Feld type gibt die allgemeine Kategorie des Fehlers an. Verwende es, um deine Wiederholungsstrategie festzulegen.

Fehlercodes

Wenn das Feld code vorhanden ist, kennzeichnet es ein spezifisches, umsetzbares Problem. Nachfolgend finden Sie die vollständige Referenz für jeden Fehlercode.

image_too_complex

Dieser Fehler tritt auf, wenn das Eingabebild oder der Prompt ein Motiv beschreibt, das geometrisch zu komplex ist, als dass das 3D-Generierungsmodell es verarbeiten könnte.

Häufige Beispiele sind:

• Dichte Haufen kleiner Objekte (z. B. eine Kiste voller Obst, ein Stapel Bücher)
• Komplexe, sich wiederholende Muster (z. B. Gitterstrukturen, Gerüste, Drahtnetze)
• Komplexe Gebäudestrukturen (z. B. mehrstöckige Gebäude mit vielen Fenstern und Balkonen)
• Mehrere unterschiedliche Objekte in einem Bild statt 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 denselben Prompt ein.
2. Vereinfachen Sie Ihr Motiv. Reduzieren Sie den Detailgrad. Zum Beispiel eine einfache Vase statt einer Vase, die mit Dutzenden von Blumen gefüllt ist.
3. Vermeiden Sie Prompts auf Szenenebene. Ganze Gebäude, Häuserblocks, mit Möbeln gefüllte Innenräume 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, Drahtnetze, Gittermuster oder Haufen vieler kleiner Gegenstände sind häufige Auslöser.

model_missing_uv

Dieser Fehler tritt auf, wenn Sie ein Modell zur Texturierung hochladen, wobei enable_original_uv auf true gesetzt ist, das Modell jedoch keine UV-Koordinaten hat. UV-Koordinaten definieren, wie eine 2D-Textur auf die 3D-Oberfläche Ihres Modells gelegt 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 vor dem Hochladen im UV-Editor Ihrer 3D-Software, ob UVs vorhanden sind. Beachten Sie, dass STL-Dateien keine UV-Daten speichern können; verwenden Sie stattdessen GLB, FBX oder OBJ.
• Wenn Sie keine spezifische UV-Steuerung benötigen (oder sich nicht sicher sind): 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, die UV-Abdeckung jedoch zu klein für eine hochwertige Texturierung ist. Dies passiert häufig bei Modellen, die aus 3D-Tools exportiert wurden, die Platzhalter-UVs oder kollabierte UVs ohne korrektes Unwrapping erzeugen.

Lösung:

• Wenn du dein ursprüngliches UV-Layout beibehalten musst: Entfalte die UVs des Modells in deiner 3D-Software neu. Stelle sicher, dass UV-Inseln korrekt über den UV-Raum verteilt sind, anstatt in einem kleinen Bereich kollabiert zu sein.
• Wenn du keine spezifische UV-Kontrolle benötigst: lasse enable_original_uv weg oder setze es auf false. Das System generiert automatisch ein neues UV-Layout. Der Nachteil ist, dass du deine ursprüngliche Nahtplatzierung verlierst, aber die automatisch generierten UVs haben eine geeignete Abdeckung für die Texturierung.

invalid_input

Dies ist der Fallback-Fehlercode, wenn die Eingabevalidierung fehlschlägt, aber kein spezifischerer Code zutrifft. Das Feld message enthält den konkreten Grund für den Fehler.

Häufige Ursachen sind:

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

Lösung: Prüfen Sie das Feld message auf Details dazu, was schiefgelaufen ist. Vergewissern Sie sich, dass Ihre Eingabedateien und Parameter den Anforderungen des endpoints entsprechen.

moderation_blocked

Dieser Fehler tritt auf, wenn dein Prompt oder deine Referenzbilder von KI-Sicherheitsfiltern abgelehnt werden. Der Filter bewertet sowohl den Text-Prompt als auch alle Referenzbilder gemeinsam.

Lösung:

• Formuliere deinen Text-Prompt um, um suggestive oder sensible Beschreibungen zu entfernen.
• Passe Referenzbilder an, wenn sie Inhalte zeigen, die Sicherheitsfilter auslösen könnten.

timeout

Dieser Fehler bedeutet, dass die Verarbeitungszeit deiner Aufgabe das zulässige Limit überschritten hat. Dies kann aufgrund hoher Systemauslastung passieren oder weil die Eingabe zu komplex ist, um innerhalb des Zeitlimits verarbeitet zu werden.

Lösung:

1. Wiederhole die Anfrage. Timeouts sind oft vorübergehend, und ein erneuter Versuch kann erfolgreich sein.
2. Vereinfache deine Eingabe. Wenn erneute Versuche weiterhin fehlschlagen, ist deine Eingabe möglicherweise zu komplex. Versuche, den Detailgrad in deinem Bild oder Prompt zu reduzieren. Siehe image_too_complex für Hinweise dazu, welche Eingabetypen schwieriger zu verarbeiten sind.

format_conversion_failed

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

Lösung:

1. Wiederhole die Anfrage.
2. Versuche es mit einem anderen Ausgabeformat. Wenn ein bestimmtes Format weiterhin fehlschlägt, wechsle zu einem anderen Format, das deinen Anforderungen entspricht.

Bewährte Verfahren

1. Implementieren Sie Wiederholungslogik. Für timeout- und service_unavailable-Fehler implementieren Sie eine Wiederholungslogik mit exponentiellem Backoff.
2. Protokollieren Sie Aufgaben-IDs. Protokollieren Sie die Aufgaben-ID immer 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 Formatanforderungen erfüllen, bevor Sie sie einreichen.