Fehler

In diesem Leitfaden erklären wir, was passiert, wenn bei der Arbeit mit der Meshy API etwas schiefgeht.

Anfragefehler

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

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

Task-Fehler

Diese Fehler treten auf, nachdem eine Task erstellt wurde und verarbeitet wird. Überprüfen Sie das Objekt task_error in der Task-Antwort 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 Ihnen die grobe Kategorie des Fehlers an. Nutzen Sie es, um Ihre Retry-Strategie festzulegen.

Fehlercodes

Wenn das Feld code vorhanden ist, kennzeichnet es ein konkretes, behebbares 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 für das 3D-Generierungsmodell geometrisch zu komplex ist.

Häufige Beispiele sind:

• Dichte Ansammlungen kleiner Objekte (z. B. eine Kiste voller Früchte, ein Bücherstapel)
• Komplizierte, sich wiederholende Muster (z. B. Gitterstrukturen, Gerüste, Drahtgeflechte)
• 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 denselben prompt ein.
2. Vereinfachen Sie Ihr Motiv. Reduzieren Sie den Detailgrad. Verwenden Sie zum Beispiel eine einfache Vase anstelle einer mit Dutzenden Blumen gefüllten Vase.
3. Vermeiden Sie prompts auf Szene-Ebene. Ganze Gebäude, Straßenzüge, mit Möbeln vollgestellte Innenräume oder Landschaften übersteigen 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, Drahtgeflechte, Gittermuster oder Ansammlungen vieler kleiner Gegenstände sind häufige Auslöser.

model_missing_uv

Dieser Fehler tritt auf, wenn Sie ein Modell zum Texturieren hochladen, bei dem enable_original_uv auf true gesetzt ist, das Modell jedoch keine UV-Koordinaten besitzt. 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. bei einer benutzerdefinierten Nahtplatzierung für präzises Texture-Mapping): Ihr Modell muss über gültige UV-Koordinaten verfügen. Prü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 Kontrolle über die UVs benötigen (oder sich nicht sicher sind): Lassen Sie enable_original_uv weg oder setzen Sie es auf false. Das System generiert dann automatisch ein UV-Layout für Ihr Modell. Die automatisch generierten UVs sind auf Abdeckung optimiert, Sie haben jedoch keine Kontrolle darüber, wo die Textur-Nähte platziert werden.

model_insufficient_uv

Dieser Fehler tritt auf, wenn ein Modell UV-Koordinaten besitzt, die UV-Abdeckung jedoch für eine hochwertige Texturierung zu gering ist. Dies kommt häufig bei Modellen vor, die aus 3D-Tools exportiert wurden, die Platzhalter-UVs oder kollabierte UVs ohne ein ordnungsgemäßes Unwrapping erzeugen.

Lösung:

• Wenn Sie Ihr ursprüngliches UV-Layout beibehalten müssen: Entpacken Sie die UVs des Modells in Ihrer 3D-Software erneut. Stellen Sie sicher, dass die UV-Inseln richtig über den UV-Raum verteilt sind, anstatt auf einen kleinen Bereich zusammengefallen zu sein.
• 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 Nachteil ist, dass die ursprüngliche Nahtplatzierung verloren geht, aber die automatisch generierten UVs bieten eine ordnungsgemäße Abdeckung für die Texturierung.

model_missing_texture

Dieser Fehler tritt auf, wenn das Eingabemodell einer Multi-Color Print-Aufgabe keine Farbinformationen enthält, die der Konverter in Druckfarben aufteilen kann. Ein Mehrfarbdruck-3MF wird aus den Farben des Modells erstellt, sodass ein rein weißes Netz — zum Beispiel eine Text-zu-3D- oder Bild-zu-3D-Vorschau, die nie texturiert wurde, oder eine reparierte / automatisch aufgeteilte Ausgabe — keine Grundlage bietet.

Was als Farbquelle zählt, hängt von dem angeforderten style ab:

• realistic tastet die Basisfarbtextur über die UVs des Modells ab und benötigt daher eine einzige Basisfarbtextur mit UV-Koordinaten auf jedem Netzteil.
• cartoon flacht Farben pro Fläche ab und akzeptiert eine Basisfarbtextur auf einem beliebigen Teil oder Vertex-Farben (COLOR_0).

Ein Modell ohne Basisfarbtextur und ohne Vertex-Farben wird für beide Stile abgelehnt; bei cartoon würde es sonst als Einfarbdruck „gelingen“.

Die meisten Anfragen werden bereits abgelehnt, bevor die Aufgabe erstellt wird (400 Bad Request mit derselben Erklärung), sodass Sie diesen Code in der Regel nur sehen, wenn die Eingabe nicht im Voraus geprüft werden konnte — ein .fbx-Upload beispielsweise wird erst geprüft, nachdem die Aufgabe ihn normalisiert hat.

Lösung:

• Texturieren Sie das Modell zuerst. Führen Sie eine Neutexturierung-Aufgabe dafür aus oder erzeugen Sie es mit aktivierter Texturierung (eine Text-zu-3D-refine-Aufgabe oder eine Bild-zu-3D-Aufgabe mit should_texture: true) und übergeben Sie diese Aufgabe als input_task_id.
• Vertex-gefärbte Modelle (Photogrammetrie-Scans, handbemalte Netze): Fordern Sie style: "cartoon" an, wodurch COLOR_0 gelesen wird.
• Teilweise texturierte oder Multi-Textur-Modelle unter realistic: Jeder Netzteil benötigt UVs und dieselbe, einzige Basisfarbtextur. Texturieren Sie die verbleibenden Teile oder führen Sie die Texturen zu einem einzigen Atlas zusammen, oder wechseln Sie zu style: "cartoon".

invalid_input

Dies ist der Fallback-Fehlercode, wenn die Eingabe die Validierung nicht besteht, aber kein spezifischerer Code zutrifft. Das Feld message enthält den genauen 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 in der hochgeladenen Modelldatei gefunden (z. B. die Datei enthält nur Skelette, Kameras oder Lichter)
• Inhalte, die die Sicherheitsfilter nicht bestehen

Lösung: Prüfen Sie das Feld message auf genauere Angaben zur Ursache des Fehlers. Vergewissern Sie sich, dass Ihre Eingabedateien und Parameter den Anforderungen des Endpunkts entsprechen.

moderation_blocked

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

Lösung:

• Formulieren Sie Ihren Text-prompt um, um anzügliche oder heikle Beschreibungen zu entfernen.
• Passen Sie Referenzbilder an, wenn sie Inhalte zeigen, die Sicherheitsfilter auslösen könnten.

timeout

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

Lösung:

1. Wiederholen Sie die Anfrage. timeout-Fehler sind oft vorübergehend, und ein erneuter Versuch kann erfolgreich sein.
2. Vereinfachen Sie Ihre Eingabe. Wenn wiederholte Versuche weiterhin fehlschlagen, ist Ihre Eingabe möglicherweise zu komplex. Versuchen Sie, den Detailgrad Ihres Bildes oder prompts zu reduzieren. Siehe image_too_complex für Hinweise dazu, welche Arten von Eingaben schwieriger zu verarbeiten sind.

format_conversion_failed

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

Lösung:

1. Wiederholen Sie die Anfrage.
2. Versuchen Sie ein anderes Ausgabeformat. Wenn ein bestimmtes Format wiederholt fehlschlägt, wechseln Sie zu einem anderen Format, das Ihren Anforderungen entspricht.

Best Practices

1. Implementieren Sie eine Wiederholungslogik. Implementieren Sie für timeout- und service_unavailable-Fehler eine Retry-Logik mit exponentiellem Backoff.
2. Protokollieren Sie Task-IDs. Protokollieren Sie zu Debugging-Zwecken immer die Task-ID. Geben Sie sie an, wenn Sie sich an den Support wenden.
3. Validieren Sie Eingaben. Stellen Sie sicher, dass Ihre Eingabebilder und -modelle vor der Übermittlung die Formatanforderungen erfüllen.