lowpoly wird am 30.10.2026 abgeschaltet. meshy-7 wird als 3D-Generierungsmodell am 31.12.2026 abgeschaltet; als Texturmodell bleibt es verfügbar. Wechseln Sie vor diesen Terminen das Modell, um Fehler bei Anfragen zu vermeiden. Alle Abkündigungen ansehen

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.

Antwortformat

Die Fehlerantwort enthält ein Feld message, das beschreibt, was schiefgelaufen ist:

  • Name
    message
    Type
    string
    Description

    Eine kurze Beschreibung des Fehlers.

Statuscodes

  • Name
    2xx
    Description

    Erfolg.

    • Name
      200 - OK
      Description

      Die Anfrage war erfolgreich.

    • Name
      202 - Accepted
      Description

      Meshy hat die Anfrage akzeptiert, und die Verarbeitung ist noch nicht abgeschlossen. Zum Beispiel gibt eine Anfrage, die eine Task erstellt, 202 zurück.

  • Name
    4xx
    Description

    Mit der Anfrage oder Ihrem Konto stimmt etwas nicht. Jeder Status gibt an, was zu tun ist.

    • Name
      400 - Bad Request
      Description

      Die Anfrage ist ungültig, oft weil ein erforderlicher Parameter fehlt oder ein Parameter fehlerhaft formatiert ist.

    • Name
      401 - Unauthorized
      Description

      Der API-Schlüssel fehlt, ist ungültig oder kann nicht auf diesen Endpunkt zugreifen. Siehe Authentifizierung.

    • Name
      402 - Payment Required
      Description

      Das Konto des API-Schlüssels hat nicht genug Credits für die Anfrage. Im Free-Plan geben die meisten Anfragen, die eine Task erstellen, ebenfalls 402 zurück.

    • Name
      403 - Forbidden
      Description

      Sie dürfen diese Anfrage nicht stellen, zum Beispiel aus einem dieser Gründe:

      • Die Anfrage kam von einer Adresse außerhalb der IP-Zulassungsliste des API-Schlüssels.
      • Die IP-Filterung Ihrer Organisation hat beim Lesen einer Task deren Dateien blockiert.
      • Der Endpunkt ist in Ihrem Plan nicht verfügbar.
      • Die Inhaltsmoderation hat die Eingabe blockiert. Manche Endpunkte geben dafür stattdessen 400 zurück; jede Endpunkt-Seite listet ihre Codes auf.
      • Der API-Schlüssel gehört einem Teammitglied, das im Team nicht mehr aktiv ist.
      • Das Konto ist gesperrt.
    • Name
      404 - Not Found
      Description

      Die Ressource existiert nicht. Zum Beispiel gibt das Abrufen einer Task mit einer ID, die nicht existiert, 404 zurück.

    • Name
      409 - Conflict
      Description

      Die Ressource existiert, aber ihr Zustand erlaubt den Vorgang nicht. Zum Beispiel gibt das Löschen einer Task mit dem Status IN_PROGRESS 409 zurück, da Meshy eine Task, die ein Worker bereits gestartet hat, nicht zurückerstatten kann. Die Task läuft weiter. Warten Sie auf einen finalen Status (SUCCEEDED, FAILED oder CANCELED) und löschen Sie die Task dann.

    • Name
      422 - Unprocessable Entity
      Description

      Die Anfrage ist gültig, aber Meshy kann ihre Eingabe nicht verarbeiten. Zum Beispiel gibt Rigging 422 zurück, wenn es im Modell keinen humanoiden Körper findet.

    • Name
      429 - Too Many Requests
      Description

      Sie haben zu viele Anfragen gesendet, oder zu viele Ihrer Tasks sind in der Warteschlange oder werden ausgeführt. Wenn die Antwort einen Retry-After-Header enthält, warten Sie die angegebene Anzahl Sekunden und versuchen Sie es erneut. Siehe Rate limits.

  • Name
    5xx
    Description

    Auf Seiten von Meshy ist etwas schiefgelaufen. Versuchen Sie es mit exponentiellem Backoff erneut. Besteht der Fehler weiterhin, prüfen Sie die Statusseite und kontaktieren Sie uns auf Discord.

Example: 400 Bad Request

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

Task errors

Ein Task, den Meshy erstellt hat, kann während der Ausführung trotzdem fehlschlagen. Sein status wird zu FAILED, Meshy erstattet die Credits, und task_error erklärt, warum.

Der task_error eines fehlgeschlagenen Tasks hat diese Felder:

  • Name
    type
    Type
    string
    Description

    Die Fehlerkategorie. Sie ist bei einem fehlgeschlagenen Task immer vorhanden. Entscheiden Sie anhand dieses Werts, ob ein erneuter Versuch sinnvoll ist. Siehe Error types.

  • Name
    message
    Type
    string
    Description

    Eine für Menschen lesbare Beschreibung des Fehlers. Sie ist bei einem fehlgeschlagenen Task immer vorhanden.

  • Name
    code
    Type
    string
    Optional
    Description

    Ein konkretes, dokumentiertes Problem, auf das Sie reagieren können. Vorhanden, wenn Meshy weitere Details liefert. Siehe Error codes. Meshy kann neue Codes hinzufügen. Behandeln Sie daher einen unbekannten Code anhand seines type.

  • Name
    doc_url
    Type
    string
    Optional
    Description

    Ein Link zum entsprechenden Eintrag des Codes auf dieser Seite, der beschreibt, was zu tun ist. Vorhanden, wenn code vorhanden ist.

Error with details

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

Error without details

{
  "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, wie weiter vorzugehen ist.

  • Name
    invalid_input
    Description

    Mit der von dir gesendeten Eingabe stimmt etwas nicht. Lies code und message, korrigiere die Eingabe und erstelle eine neue Aufgabe.

  • Name
    timeout
    Description

    Die Aufgabe hat ein serverseitiges Zeitlimit überschritten, entweder bei der Verarbeitung oder beim Warten in der Warteschlange, und ist fehlgeschlagen. Meshy erstattet die dafür verwendeten Credits zurück. Dies ist oft nur vorübergehend. Erstelle die Aufgabe erneut, und falls sie weiterhin fehlschlägt, versuche es mit einer einfacheren Eingabe.

  • Name
    service_unavailable
    Description

    Der Dienst war vorübergehend nicht verfügbar. Warte einen Moment und erstelle die Aufgabe dann erneut.

  • Name
    server_error
    Description

    Während der Ausführung der Aufgabe ist auf Seiten von Meshy etwas schiefgelaufen. Erstelle die Aufgabe erneut. Falls sie weiterhin fehlschlägt, wende dich mit der Aufgaben-ID an den Support.


Fehlercodes

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

Diese Eingaben sind wahrscheinlich zu komplex:

A crate of mixed berriesAn intricate cathedral ceilingA building under construction with scaffoldingA honeycomb lattice sphere

Um das Problem zu beheben, versuchen Sie eine oder mehrere der folgenden Maßnahmen:

  • Verwenden Sie pro Bild ein Objekt. 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 zum Beispiel eine einfache Vase anstelle einer mit Dutzenden von Blumen gefüllten Vase.
  • Vermeiden Sie Szenen. Ganze Gebäude, Straßenzüge, eingerichtete Räume und Landschaften sind wahrscheinlich zu viel. Konzentrieren Sie sich auf ein einzelnes Objekt.
  • Vermeiden Sie dichte, sich wiederholende Strukturen. Gerüste, Drahtgeflechte, Gitterstrukturen und Ansammlungen kleiner Gegenstände sind häufige Auslöser.

model_missing_uv

Sie haben ein Modell mit auf true gesetztem enable_original_uv zur Texturierung gesendet, aber das Modell hat keine UV-Koordinaten. UV-Koordinaten definieren, wie eine 2D-Textur auf die 3D-Oberfläche abgebildet wird.

No UVs vs Good UVs

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 dann 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 Textur-Nä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 zusammengefallene UVs ohne ein richtiges Unwrap geschrieben hat.

Insufficient UVs vs Good UVs

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

  • Um Ihr eigenes UV-Layout zu behalten, entpacken Sie die UVs des Modells in Ihrer 3D-Software erneut. Verteilen Sie die Inseln über den UV-Raum, statt sie in einer kleinen Ecke davon zu belassen.
  • Wenn 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 zwar Ihre Nahtplatzierung, aber die neuen UVs decken genügend 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, daher gibt es bei einem einfarbig weißen Netz nichts, womit gearbeitet werden kann. Eine Text-zu-3D- oder Bild-zu-3D-Vorschau, die nie texturiert wurde, hat beispielsweise keine Farbe. Das Gleiche gilt für die Ausgabe von „Druckbarkeit reparieren“ oder für eine Auto-Split-Aufgabe, bei der die Textur nicht erhalten blieb.

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

  • realistic tastet die Basisfarbtextur anhand der UVs des Modells ab. Dafür wird eine einzelne Basisfarbtextur sowie UVs für jedes Netzteil benötigt.
  • cartoon glättet die Farben pro Fläche. Dabei wird eine Basisfarbtextur auf einem beliebigen Teil oder Farben pro Vertex (COLOR_0) akzeptiert.

Meshy lehnt ein Modell, das weder eine Basisfarbtextur noch Vertex-Farben besitzt, für beide Stile ab, statt es cartoon in einen Einfarbdruck umwandeln zu lassen.

Meshy weist die meisten dieser Anfragen bereits ab, bevor die Aufgabe erstellt wird, und liefert dabei einen 400-Status mit derselben Erklärung. Diesen Code erhält man in der Regel nur dann, wenn Meshy die Eingabe nicht im Voraus prüfen kann. Beispielsweise prüft Meshy einen .fbx-Upload erst, nachdem die Aufgabe ihn konvertiert hat.

Um das Problem zu beheben, verwenden Sie die Option, die zu Ihrem Modell passt:

  • Texturieren Sie das Modell zuerst. Führen Sie dazu Retexture darauf aus, oder generieren Sie es mit einer Text-zu-3D-refine-Aufgabe oder einer Bild-zu-3D-Aufgabe mit should_texture: true. Senden Sie diese Aufgabe anschließend als input_task_id.
  • Verwenden Sie für ein vertex-gefärbtes Modell, etwa einen Photogrammetrie-Scan oder ein handbemaltes Netz, style: "cartoon", das COLOR_0 ausliest.
  • Geben Sie bei einem teilweise texturierten oder Mehrfachtextur-Modell mit realistic jedem Netzteil UVs und dieselbe einzelne Basisfarbtextur. Texturieren Sie dazu die verbleibenden Teile, oder führen Sie die Texturen in einem einzigen Atlas zusammen. Sie können auch zu style: "cartoon" wechseln.

textured_split_refused

Eine Auto Split-Aufgabe mit keep_texture: true kann die Textur des Eingabemodells nicht auf den Teilen beibehalten. Zum Beispiel hat 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 dies zu beheben, senden Sie die Anfrage erneut ohne keep_texture oder mit keep_texture: false. Die Teile kommen dann jeweils mit einer einfarbigen Farbe 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, wie 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 Sicherheitsfilter nicht bestehen

Um dies zu beheben, lesen Sie message für das spezifische Problem. Prüfen Sie, ob Ihre Eingabedateien und Parameter die Anforderungen des Endpunkts erfüllen.

moderation_blocked

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

Um das Problem zu beheben, führe eine oder beide der folgenden Maßnahmen durch:

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

moderation_unavailable

Typ: server_error. Die moderation von Inhalten war vorübergehend nicht verfügbar, sodass Meshy den Task als fehlgeschlagen markiert hat, anstatt die Prüfung zu überspringen. Mit deinem Inhalt ist nichts falsch.

Um das Problem zu beheben, erstelle den Task erneut.

timeout

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

Um das Problem zu beheben, befolgen Sie diese Schritte:

  1. Erstellen Sie die Aufgabe erneut. timeouts sind oft vorübergehend, und eine neue Aufgabe könnte erfolgreich sein.
  2. Wenn es weiterhin fehlschlägt, vereinfachen Sie Ihre Eingabe, zum Beispiel indem Sie die Detailtiefe Ihres Bildes 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. Daher hat Meshy sie als fehlgeschlagen markiert und alle dafür berechneten Credits zurückerstattet. Ihre Eingabe hat diesen Fehler nicht verursacht.

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

format_conversion_failed

Meshy hat das Modell generiert, aber die Konvertierung in das von Ihnen angeforderte Format ist fehlgeschlagen.

Gehen Sie zur Behebung wie folgt vor:

  1. Erstellen Sie die Aufgabe erneut.
  2. Wenn ein bestimmtes Format wiederholt fehlschlägt, fordern Sie ein anderes Format an, das Ihren Anforderungen entspricht.

Bewährte Praktiken

  • Fehlgeschlagene Aufgaben wiederholen. 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 aufweist. Die erste Aufgabe läuft möglicherweise noch, prüfen Sie daher, ob sie bereits 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 die Formatanforderungen des Endpunkts erfüllen.
  • Rufen Sie die API von Ihrem Server aus auf. Code, der im Browser ausgeführt wird, legt Ihren API-Schlüssel gegenüber jedem offen, der die Seite öffnet.