Fehler

In diesem Leitfaden erfahren Sie, was passiert, wenn bei der Arbeit mit der Meshy API etwas schiefgeht.

Fehler bei Anfragen

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

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

Fehlgeschlagene Aufgaben

Diese Fehler treten auf, nachdem eine Aufgabe erstellt wurde und verarbeitet wird. Überprüfen Sie das task_error-Objekt in der Aufgabenantwort, um Details zum Fehler zu erhalten.

{
  "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, bezeichnet 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)
• Komplexe 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. Nehmen Sie keine mehreren separaten Objekte in dasselbe Bild oder denselben prompt auf.
2. Vereinfachen Sie Ihr Motiv. Reduzieren Sie den Detailgrad. Nehmen Sie zum Beispiel eine einfache Vase anstelle einer Vase voller Dutzender Blumen.
3. Vermeiden Sie Prompts auf Szenen-Ebene. Ganze Gebäude, Häuserblöcke, mit Möbeln gefüllte 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 zur Texturierung mit enable_original_uv auf true gesetzt hochladen, das Modell jedoch keine UV-Koordinaten besitzt. UV-Koordinaten definieren, wie sich eine 2D-Textur auf die 3D-Oberfläche Ihres Modells legt.

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 benutzerdefinierter Nahtplatzierung für präzises Texture-Mapping): Ihr Modell muss über gültige UV-Koordinaten verfügen. Ü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-Kontrolle 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 für eine gute 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 ordnungsgemäß über den UV-Raum verteilt sind, anstatt auf einen kleinen Bereich zusammenzufallen.
• Wenn Sie keine spezielle 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, die automatisch erzeugten UVs jedoch eine angemessene Abdeckung für die Texturierung aufweisen.

model_missing_texture

Dieser Fehler tritt auf, wenn das Eingabemodell einer Multi-Color Print-Aufgabe keine Farbinformationen enthält, die der Konverter in Druckfarben auftrennen kann. Ein Mehrfarbdruck-3MF wird aus den Farben des Modells erstellt. 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 — bietet daher keine Grundlage dafür.

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

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

Ein Modell ohne Basisfarbtextur und ohne Vertexfarben wird für beide Stile abgelehnt; bei cartoon würde es sonst als Einfarbdruck „erfolgreich“ sein.

Die meisten Anfragen werden bereits abgelehnt, bevor die Aufgabe erstellt wird (400 Bad Request mit derselben Erklärung). Daher wird dieser Code meist nur dann angezeigt, 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 dazu eine Neutexturierung-Aufgabe darauf aus, oder generieren 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.
• Modelle mit Vertexfarben (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 Standard-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 Varianten von Dateiformaten (z. B. ASCII-FBX-Dateien, meshopt-komprimierte GLB)
• Keine gültigen 3D-Objekte in dem hochgeladenen Modell gefunden (z. B. enthält die Datei nur Armaturen, Kameras oder Lichter)
• Inhalte, die die Sicherheitsfilter nicht passieren

Lösung: Überprüfen Sie das Feld message auf genauere Angaben zum aufgetretenen Fehler. Stellen Sie sicher, dass Ihre Eingabedateien und Parameter den Anforderungen des Endpunkts entsprechen.

moderation_blocked

Dieser Fehler tritt auf, wenn Ihr prompt oder Ihre Referenzbilder von den 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 sensible Beschreibungen zu entfernen.
• Passen Sie Referenzbilder an, falls sie Inhalte zeigen, die Sicherheitsfilter auslösen könnten.

timeout

Dieser Fehler bedeutet, dass die Aufgabe ein serverseitiges Zeitlimit überschritten hat, sei es bei der Verarbeitung oder beim Warten in der Warteschlange, sodass die Aufgabe fehlgeschlagen ist und die Credits dafür zurückerstattet wurden. Dies kann bei hoher Systemlast auftreten oder weil die Eingabe zu komplex ist, um innerhalb des Zeitlimits verarbeitet zu werden.

Das unterscheidet sich von einem timeout in Ihrem eigenen Code. Wenn Ihr Client das Warten beendet hat, läuft die Aufgabe trotzdem noch weiter; siehe Task Lifecycle.

Lösung:

1. Erstellen Sie die Aufgabe erneut. timeouts sind oft vorübergehend, und eine neue Aufgabe kann erfolgreich sein.
2. Vereinfachen Sie Ihre Eingabe. Wenn wiederholte Versuche weiterhin fehlschlagen, ist Ihre Eingabe möglicherweise zu komplex. Versuchen Sie, den Detailgrad in Ihrem Bild oder prompt 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 das von Ihnen angeforderte Ausgabeformat konvertiert werden konnte. Das Modell wurde erfolgreich generiert, aber der Konvertierungsschritt ist fehlgeschlagen.

Lösung:

1. Fordern Sie die Anfrage erneut an.
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. Wenn eine Aufgabe mit einem timeout-, service_unavailable- oder server_error-Fehler fehlschlägt, erstellen Sie sie mit exponentiellem Backoff erneut. Wenn stattdessen Ihre eigene Anfrage ein Timeout hatte, erstellen Sie keine neue Aufgabe: Überprüfen Sie zuerst die bestehende (siehe Task Lifecycle).
2. Protokollieren Sie Task-IDs. Protokollieren Sie die Task-ID immer zu Debugging-Zwecken. Geben Sie sie an, wenn Sie den Support kontaktieren.
3. Validieren Sie die Eingaben. Stellen Sie sicher, dass Ihre Eingabebilder und -modelle vor der Übermittlung die Formatanforderungen erfüllen.