Meshy API Webhooks 與輪詢：結果何時就緒

Meshy API 生成任務(Text to 3D、Image to 3D、Rigging 等)是以非同步方式執行的——你提交任務後,需要先確認任務何時完成,才能取得結果。本文將說明任務的生命週期,以及確認任務是否完成的兩種支援方式:輪詢(polling)與 webhooks,並說明如何避免最常見的「模型擷取錯誤」問題。

每個生成任務都會經歷一組狀態,並透過任務物件中的 status 欄位回傳:

• PENDING — 任務已進入佇列,但尚未開始處理。

• IN_PROGRESS — 任務正在處理中。progress 欄位(0-100)會隨工作完成而增加。

• SUCCEEDED — 任務已成功完成,且 progress 為 100。結果網址(模型檔案、紋理、預覽)現已可在回應中取得。

• FAILED — 任務無法完成。失敗任務的點數會自動退還。

• CANCELED — 任務在完成前被取消。

整合 API 時最重要的原則:在任務的 status 變為 SUCCEEDED 之前,絕對不要嘗試擷取或使用結果網址。在任務仍處於 PENDING 或 IN_PROGRESS 時讀取結果,是「模型擷取錯誤」回報最常見的原因。

輪詢是指重複呼叫對應你任務 ID 的「取得任務」端點,直到任務達到終端狀態(SUCCEEDED、FAILED 或 CANCELED)。一個簡單的輪詢迴圈如下:

• 提交生成請求,並儲存回傳的任務 id。

• 以固定間隔(通常為數秒)呼叫對應的「擷取任務」端點(例如 Text to 3D 或 Image to 3D 的 task-by-id 端點)。

• 檢查每次回應中的 status 欄位。若仍為 PENDING 或 IN_PROGRESS,則繼續輪詢。

• 一旦 status 為 SUCCEEDED(讀取結果網址)、FAILED 或 CANCELED,立即停止輪詢。

• 在你的用戶端加入合理的逾時/最大嘗試次數保護機制,避免卡住的任務無限輪詢。

輪詢簡單易用,適合腳本、批次作業與低流量整合。對於高流量或對延遲敏感的整合,webhook 通常是更好的選擇。

與其反覆詢問「完成了嗎?」,你可以讓 Meshy 在任務完成的那一刻通知你的伺服器。若要使用 webhook:

• 設定一個 Meshy 可存取的 webhook(回呼)網址——視端點而定,通常是在帳戶/API 設定層級設定,或作為生成請求的參數傳入。

• 確保你的端點可透過 HTTPS 公開存取,並能快速回應(立即回傳 2xx 狀態,然後以非同步方式處理酬載)。

• 當任務達到終端狀態時,Meshy 會向你的端點發送一個包含任務 id 與最終 status 的酬載。

• 收到後,請透過 API 以 id 查詢完整的任務詳情,而不要僅信任 webhook 的內容,以確保你取得的是權威且最新的結果。

Webhook 可減少不必要的 API 呼叫,並提供近乎即時的通知,但你仍應保留定期輪詢作為備援機制,以應對 webhook 可能遺失或延遲送達的情況(例如你端發生暫時性網路問題)。

無論使用輪詢還是 webhook,你的結果處理程式碼都應具備冪等性——對同一任務重複執行也不會產生副作用。這一點很重要,因為:

• 同一任務的 webhook 可能被送達多次(發送端重試、網路重複傳輸等)。

• 輪詢迴圈與 webhook 處理器可能同時在執行,並都嘗試處理同一個已完成的任務。

為保持冪等性,請以任務 id 作為處理邏輯的依據——例如,在再次處理前先檢查你是否已儲存/下載過該 id 的結果,並將「標記為已處理」作為你自己資料庫中的單一原子步驟。

只有在回應中出現 "status": "SUCCEEDED" 且 "progress": 100 時,才能保證結果酬載(模型網址、紋理、縮圖)完整且可安全使用。具體而言,在你的程式碼中:

• 在從 result/模型網址欄位讀取任何內容之前,先驗證 status === "SUCCEEDED"。

• 不要只依賴 progress——務必同時檢查 status,因為在任務完全定案之前,progress 可能短暫顯示偏高的數值。

• 一旦 SUCCEEDED,請立即下載結果檔案——生成的資產只會在 Meshy 的伺服器上保留有限時間,之後網址將無法解析。

大多數「無法擷取我的模型」的回報,都可追溯到以下原因之一:

• 過早擷取。 在 status 為 SUCCEEDED 之前就呼叫結果網址或讀取模型欄位。這是目前為止最常見的原因。

• 資產過期。 在 SUCCEEDED 之後等待太久才下載——結果網址會在該任務類型的保留期限過後失效。

• 使用過期或錯誤的任務 ID——例如重複使用先前不相關請求的 ID。

• 將 FAILED 視為暫時狀態,持續輪詢一個已失敗的任務,而不是重新提交。

• 你的伺服器與 Meshy 之間的網路/逾時問題,被誤判為生成問題。

如果生成結果不如預期,或請求直接失敗,請注意以下幾點:

• Meshy API 目前不支援就地重試現有任務——若要再次嘗試,請提交新的生成請求,這將正常消耗點數。

• 若呼叫 API 時遇到暫時性網路故障(逾時、5xx 回應),在重新提交請求前進行短暫的指數退避是合理的做法。

• 對於輪詢本身,遇到暫時性網路錯誤時可重試「取得任務」呼叫,但不要將單次輪詢失敗視為生成失敗——只有在收到成功回應時,才可信任 status 欄位。

• 如果你需要生成任務的內建重試功能,請聯絡 Meshy 的銷售團隊了解企業版方案選項。

這幾乎總是因為程式碼在任務完成前就嘗試讀取結果。請務必在擷取模型網址前,確認 status 為 SUCCEEDED(且 progress 為 100)。

輪詢設定較簡單,適合低流量或一次性腳本。Webhook 更適合有大量並行任務的正式環境整合,因為它們可避免不必要的重複請求,並在任務完成時立即通知你。

以冪等方式處理——根據任務 id 對照你已處理過的內容,若已處理過則跳過重新處理。

改為直接以 id 輪詢該任務。同時確認你的端點可透過 HTTPS 公開存取,並能快速回傳 2xx 回應,因為緩慢或無法存取的端點可能導致送達問題。

目前不行——你需要提交新的生成請求,這將正常消耗點數。如果你需要內建重試支援,請聯絡銷售團隊了解企業版選項。

結果檔案在任務完成後只會在 Meshy 的伺服器上保留有限時間,因此請在任務成功後盡快將輸出下載到自己的儲存空間,而不要等待。

• 為什麼我透過 API 從生成結果擷取模型時,總是遇到錯誤?