Meshy API Webhooks vs. Polling: Wann Ergebnisse bereit sind

Asynchrone Generierungsaufgaben der Meshy API (Text to 3D, Image to 3D, Rigging und mehr) laufen asynchron ab — Sie reichen eine Aufgabe ein und müssen dann herausfinden, wann sie abgeschlossen ist, bevor Sie das Ergebnis abrufen. Dieser Artikel erklärt den Lebenszyklus einer Aufgabe und die beiden unterstützten Möglichkeiten, um zu erfahren, wann eine Aufgabe abgeschlossen ist: Polling und Webhooks — plus wie Sie das häufigste Problem „Fehler beim Abrufen des Modells“ vermeiden.

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 gestellt, aber die Verarbeitung hat noch nicht begonnen.

• IN_PROGRESS — die Aufgabe wird aktiv verarbeitet. Das Feld progress (0-100) steigt, während die Arbeit fortschreitet.

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

• FAILED — die Aufgabe konnte nicht abgeschlossen werden. Credits für fehlgeschlagene Aufgaben werden automatisch zurückerstattet.

• CANCELED — die Aufgabe wurde vor 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 Meldungen über „Fehler beim Abrufen des Modells“.

Polling bedeutet, den „Aufgabe abrufen“-Endpunkt für Ihre Aufgaben-ID wiederholt aufzurufen, bis die Aufgabe einen Endzustand erreicht (SUCCEEDED, FAILED oder CANCELED). Eine einfache Polling-Schleife sieht so aus:

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

• Rufen Sie den entsprechenden „Aufgabe abrufen“-Endpunkt (z. B. den Text to 3D- oder Image to 3D-Endpunkt für Aufgaben nach ID) in einem Intervall auf — einige Sekunden sind üblich.

• Prüfen Sie bei jeder Antwort das Feld status. Pollen Sie weiter, solange es PENDING oder IN_PROGRESS ist.

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

• Fügen Sie in Ihrem Client eine angemessene Timeout-/Max-Attempts-Sicherung hinzu, damit eine hängengebliebene Aufgabe nicht endlos gepollt wird.

Polling ist einfach und funktioniert gut für Skripte, Batch-Jobs und Integrationen mit geringem Volumen. Bei Integrationen mit hohem Volumen oder Latenzanforderungen sind Webhooks meist die bessere Wahl.

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

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

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

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

• Rufen Sie bei Erhalt die vollständigen Aufgabendetails über die API anhand der id ab, statt sich allein auf den Webhook-Body zu verlassen, um sicherzustellen, dass Sie das autoritative, aktuelle Ergebnis haben.

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

Unabhängig davon, ob Sie Polling oder Webhooks verwenden, sollte Ihre Ergebnisverarbeitung idempotent sein — d. h. sie kann mehrfach für dieselbe Aufgabe ausgeführt werden, ohne Nebenwirkungen. Das ist wichtig, weil:

• Ein Webhook für dieselbe Aufgabe mehrmals zugestellt werden kann (Wiederholungen auf Senderseite, Netzwerk-Duplizierung usw.).

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

Um idempotent zu bleiben, should basieren Sie Ihre Verarbeitungslogik auf der Aufgaben-id — prüfen Sie z. B., ob Sie Ergebnisse für diese id bereits gespeichert/heruntergeladen haben, bevor Sie es erneut tun, und machen Sie „als verarbeitet markieren“ zu einem einzelnen atomaren Schritt in Ihrer eigenen Datenbank.

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

• Verifizieren Sie status === "SUCCEEDED", bevor Sie etwas aus den result-/Modell-URL-Feldern lesen.

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

• Laden Sie Ergebnisdateien umgehend nach SUCCEEDED herunter — generierte Assets werden nur für eine begrenzte Zeit auf den Servern von Meshy aufbewahrt, danach lösen die URLs nicht mehr auf.

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

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

• Abgelaufene Assets. Zu langes Warten nach SUCCEEDED mit dem Herunterladen — Ergebnis-URLs funktionieren nicht mehr, nachdem das Aufbewahrungsfenster für diesen Aufgabentyp abgelaufen ist.

• Verwendung einer veralteten oder falschen Aufgaben-ID — z. B. die Wiederverwendung einer ID aus einer früheren, nicht verwandten Anfrage.

• FAILED als vorübergehender Zustand behandeln und eine bereits fehlgeschlagene Aufgabe weiter pollten, statt sie erneut einzureichen.

• Netzwerk-/Timeout-Probleme zwischen Ihrem Server und Meshy, die fälschlich als Generierungsproblem interpretiert werden.

Wenn eine Generierung Ihre Erwartungen nicht erfüllt oder eine Anfrage vollständig fehlschlägt, beachten Sie Folgendes:

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

• Bei vorübergehenden Netzwerkfehlern beim API-Aufruf (Timeouts, 5xx-Antworten) ist ein kurzer exponentieller Backoff vor dem erneuten Senden der Anfrage sinnvoll.

• Beim Polling selbst wiederholen Sie den „Aufgabe abrufen“-Aufruf bei vorübergehenden Netzwerkfehlern, aber betrachten Sie einen einzelnen fehlgeschlagenen Poll nicht als Generierungsfehler — vertrauen Sie dem Feld status erst, wenn Sie eine erfolgreiche Antwort erhalten.

• Wenn Sie eine integrierte Retry-Funktion für Generierungen benötigen, wenden Sie sich an das Vertriebsteam von Meshy zu Optionen für Enterprise-Pläne.

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

Polling ist einfacher einzurichten und für Skripte mit geringem Volumen oder einmalige Aufgaben gut geeignet. 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 ist.

Behandeln Sie ihn idempotent — prüfen Sie die Aufgaben-id gegen bereits Verarbeitetes und überspringen Sie die erneute Verarbeitung, wenn sie bereits behandelt wurde.

Greifen Sie auf Polling der Aufgabe direkt über die id zurück. Bestätigen Sie außerdem, dass Ihr Endpunkt öffentlich über HTTPS erreichbar ist und schnell mit 2xx antwortet, 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 zu Enterprise-Optionen, wenn Sie eine integrierte Retry-Unterstützung benötigen.

Ergebnisdateien werden nach Abschluss einer Aufgabe nur für eine begrenzte Zeit auf den Servern von Meshy aufbewahrt. Laden Sie die Ausgaben daher so bald wie möglich nach erfolgreichem Abschluss in Ihren eigenen Speicher herunter, statt zu warten.

• Warum erhalte ich beim Abrufen der Modelle aus einem Generierungsergebnis über die API ständig Fehler?