Meshy API Webhooks vs. Polling: Wann Ergebnisse bereit sind

Generierungsaufgaben der Meshy API (Text to 3D, Image to 3D, Rigging und mehr) laufen asynchron – Sie übermitteln eine Aufgabe und müssen dann herausfinden, wann sie abgeschlossen ist, bevor Sie das Ergebnis abrufen. Dieser Artikel erklärt den Aufgaben-Lebenszyklus und die zwei unterstützten Möglichkeiten, zu erkennen, wann eine Aufgabe abgeschlossen ist: Polling und Webhooks – sowie die Vermeidung des häufigsten Problems „Fehler beim Abrufen des Modells“.

Jede Generierungsaufgabe durchläuft eine kleine Anzahl von Zuständen, die im Feld status des Aufgabenobjekts zurückgegeben werden:

• PENDING — die Aufgabe wurde in die Warteschlange eingereiht, aber die Verarbeitung hat noch nicht begonnen.

• IN_PROGRESS — die Aufgabe wird aktiv verarbeitet. Das Feld progress (0–100) steigt, wenn die Arbeit fortschreitet.

• SUCCEEDED — die Aufgabe wurde erfolgreich abgeschlossen und progress beträgt 100. Ergebnis-URLs (Modelldateien, Texturen, Vorschauen) sind nun in der Antwort verfügbar.

• FAILED — die Aufgabe konnte nicht abgeschlossen werden. Guthaben für fehlgeschlagene Aufgaben werden automatisch erstattet.

• CANCELED — die Aufgabe wurde vor dem Abschluss abgebrochen.

Die wichtigste Regel bei der Integration mit der API: Versuchen Sie niemals, Ergebnis-URLs abzurufen oder zu verwenden, bevor der status der Aufgabe SUCCEEDED ist. Das Lesen von Ergebnissen, während eine Aufgabe noch PENDING oder IN_PROGRESS ist, ist die häufigste Ursache für „Fehler beim Abrufen des Modells".

Beim Polling rufen Sie wiederholt den „Get Task"-Endpunkt für Ihre Aufgaben-ID auf, bis ein Endzustand erreicht ist (SUCCEEDED, FAILED oder CANCELED). Eine einfache Polling-Schleife sieht folgendermaßen aus:

• Senden Sie die Generierungsanfrage und speichern Sie die zurückgegebene Aufgaben-id.

• Rufen Sie in regelmäßigen Abständen den entsprechenden „Retrieve Task"-Endpunkt auf (z. B. den Text to 3D- oder Image to 3D-Aufgaben-nach-ID-Endpunkt) — typischerweise alle paar Sekunden.

• Überprüfen Sie das status-Feld in jeder Antwort. Setzen Sie das Polling fort, solange es PENDING oder IN_PROGRESS ist.

• Stoppen Sie das Polling, sobald der status SUCCEEDED ist (lesen Sie die Ergebnis-URLs), FAILED oder CANCELED.

• Fügen Sie in Ihrem Client einen angemessenen Timeout-/Max-Versuche-Schutz hinzu, damit eine hängengebliebene Aufgabe nicht endlos pollt.

Polling ist einfach und eignet sich gut für Skripte, Batch-Jobs und Integrationen mit niedrigem Volumen. Für Integrationen mit hohem Volumen oder latenzempfindliche Integrationen ist ein Webhook normalerweise die bessere Wahl.

Anstatt wiederholt zu fragen „Ist es schon fertig?“, können Sie Meshy bitten, Ihren Server zu benachrichtigen, sobald eine Aufgabe abgeschlossen ist. So verwenden Sie Webhooks:

• Konfigurieren Sie eine Webhook-(Callback-)URL, die Meshy erreichen kann – je nach Endpoint wird diese in der Regel auf Konto-/API-Einstellungsebene festgelegt oder als Parameter bei der Generierungsanfrage übergeben.

• Stellen Sie sicher, dass Ihr Endpoint öffentlich über HTTPS erreichbar ist und schnell antwortet (geben Sie sofort einen 2xx-Status zurück und verarbeiten Sie die Nutzlast anschließend asynchron).

• Wenn die Aufgabe einen Endzustand erreicht, sendet Meshy eine Nutzlast an Ihren Endpoint, die die Aufgaben-id und ihren endgültigen status enthält.

• Rufen Sie bei Empfang die vollständigen Aufgabendetails über die id per API ab, anstatt sich allein auf den Webhook-Body zu verlassen, um sicherzustellen, dass Sie das maßgebliche, aktuelle Ergebnis erhalten.

Webhooks reduzieren unnötige API-Aufrufe und benachrichtigen Sie nahezu sofort. Dennoch sollten Sie für Aufgaben, bei denen eine Webhook-Zustellung verpasst oder verzögert werden könnte (z. B. aufgrund eines vorübergehenden Netzwerkproblems auf Ihrer Seite), weiterhin einen periodischen Polling-Fallback beibehalten.

Unabhängig davon, ob Sie Polling oder Webhooks verwenden, sollte Ihr Code zur Ergebnisverarbeitung idempotent sein – also ohne Nebenwirkungen mehr als einmal für dieselbe Aufgabe ausgeführt werden können. Das ist wichtig, weil:

• Ein Webhook für dieselbe Aufgabe mehr als einmal zugestellt werden kann (Wiederholungsversuche auf der Senderseite, Netzwerkduplikate usw.).

• Eine Polling-Schleife und ein Webhook-Handler möglicherweise beide versuchen, dieselbe abgeschlossene Aufgabe zu verarbeiten, wenn beide laufen.

Um idempotent zu bleiben, richten Sie Ihre Verarbeitungslogik an der Aufgaben-id aus – prüfen Sie beispielsweise, ob Sie bereits Ergebnisse für diese id gespeichert/heruntergeladen haben, bevor Sie es erneut tun, und machen Sie „als verarbeitet markieren" zu einem einzigen atomaren Schritt in Ihrer eigenen Datenbank.

Eine Antwort mit "status": "SUCCEEDED" und "progress": 100 ist das einzige Signal, das garantiert, dass die Ergebnisladung (Modell-URLs, Texturen, Miniaturansichten) vollständig und sicher zu verwenden ist. Konkret in Ihrem Code:

• Überprüfen Sie status === "SUCCEEDED", bevor Sie etwas aus den result/Modell-URL-Feldern auslesen.

• Verlassen Sie sich nicht allein auf progress – überprüfen Sie immer auch status, da der Fortschritt kurzzeitig hohe Werte anzeigen kann, bevor die Aufgabe vollständig abgeschlossen ist.

• Laden Sie Ergebnisdateien umgehend herunter, sobald der Status SUCCEEDED ist – generierte Assets werden nur für begrenzte Zeit auf den Servern von Meshy gespeichert, danach sind die URLs nicht mehr gültig.

Die meisten Meldungen der Art „Ich kann mein Modell nicht abrufen“ lassen sich auf eine der folgenden Ursachen zurückführen:

• Zu frühes Abrufen. Aufrufen der Ergebnis-URL oder Auslesen der Modellfelder, bevor status SUCCEEDED ist. Dies ist mit Abstand die häufigste Ursache.

• Abgelaufene Assets. Zu langes Warten mit dem Herunterladen nach SUCCEEDED – Ergebnis-URLs funktionieren nach Ablauf des Aufbewahrungszeitraums für diesen Aufgabentyp nicht mehr.

• Verwendung einer veralteten oder falschen Aufgaben-ID – zum Beispiel die Wiederverwendung einer ID aus einer früheren, nicht zugehörigen Anfrage.

• FAILED als vorübergehenden Zustand behandeln und eine bereits fehlgeschlagene Aufgabe weiter pollen, anstatt sie erneut einzureichen.

• Netzwerk-/Timeout-Probleme zwischen Ihrem Server und Meshy, die fälschlicherweise als Problem bei der Generierung gedeutet werden.

Wenn eine Generierung nicht Ihren Erwartungen entspricht oder eine Anfrage vollständig fehlschlägt, beachten Sie Folgendes:

• Die Meshy API unterstützt derzeit nicht das Wiederholen einer vorhandenen Aufgabe an Ort und Stelle — um es erneut zu versuchen, übermitteln Sie eine neue Generierungsanfrage, die normalerweise Guthaben verbraucht.

• Bei vorübergehenden Netzwerkfehlern beim Aufrufen der API (Timeouts, 5xx-Antworten) ist ein kurzes exponentielles Backoff vor erneuter Übermittlung der Anfrage sinnvoll.

• Beim Polling selbst wiederholen Sie den Aufruf „Get Task" bei vorübergehenden Netzwerkfehlern, behandeln Sie jedoch einen einzelnen fehlgeschlagenen Poll nicht als Generierungsfehler — vertrauen Sie dem status-Feld erst, wenn Sie eine erfolgreiche Antwort erhalten.

• Wenn Sie eine integrierte Wiederholungsfunktion für Generierungen benötigen, wenden Sie sich an das Vertriebsteam von Meshy bezüglich der Optionen des Enterprise-Plans.

Dies geschieht fast immer, weil der Code versucht, das Ergebnis zu lesen, bevor die Aufgabe abgeschlossen wurde. Bestätigen Sie immer, dass der status SUCCEEDED ist (und progress 100), bevor Sie Modell-URLs abrufen.

Polling ist einfacher einzurichten und geeignet für Anwendungen mit geringem Volumen oder einmalige Skripte. Webhooks sind besser für Produktionsintegrationen mit vielen gleichzeitigen Aufgaben, da sie unnötige wiederholte Anfragen vermeiden und Sie sofort benachrichtigen, wenn eine Aufgabe abgeschlossen wird.

Behandeln Sie es idempotent – prüfen Sie die Aufgaben-id gegen das, was Sie bereits verarbeitet haben, und überspringen Sie die erneute Verarbeitung, falls sie bereits bearbeitet wurde.

Weichen Sie auf Polling der Aufgabe nach id aus. Bestätigen Sie außerdem, dass Ihr Endpunkt öffentlich über HTTPS erreichbar ist und eine schnelle 2xx-Antwort zurückgibt, da langsame oder unerreichbare Endpunkte Zustellungsprobleme verursachen können.

Derzeit nicht – Sie müssen eine neue Generierungsanfrage einreichen, die normalerweise Credits verbraucht. Kontaktieren Sie den Vertrieb bezüglich Enterprise-Optionen, wenn Sie integrierte Wiederholungsunterstützung benötigen.

Ergebnisdateien werden nur für begrenzte Zeit auf den Servern von Meshy aufbewahrt, nachdem eine Aufgabe abgeschlossen wurde. Laden Sie daher Ihre Ausgaben so bald wie möglich in Ihren eigenen Speicher herunter, anstatt zu warten.