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

Meshy API 生成任務（Text to 3D、Image to 3D、Rigging 等）以非同步方式執行——您提交任務後，需要先了解任務何時完成，才能取得結果。本文說明任務生命週期，以及兩種支援的方式來得知任務何時完成：輪詢與 Webhook——並說明如何避免最常見的「取得模型時發生錯誤」問題。

Every generation task moves through a small set of states, returned in the status field of the task object:

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

• IN_PROGRESS — 任務正在積極處理中。progress 欄位（0-100）會隨著工作完成而增加。

• SUCCEEDED — 任務成功完成，progress 為 100。Result URLs（模型檔案、紋理、預覽）現在可在回應中取得。

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

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

整合 API 時最重要的規則：在任務的 status 為 SUCCEEDED 之前，切勿嘗試擷取或使用結果 URL。在任務仍為 PENDING 或 IN_PROGRESS 時讀取結果，是「擷取模型時發生錯誤」回報的最常見原因。

輪詢是指反覆呼叫任務 ID 的「取得任務」端點，直到任務達到終止狀態（SUCCEEDED、FAILED 或 CANCELED）。簡單的輪詢循環如下：

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

• 定期呼叫相應的「擷取任務」端點（例如 Text to 3D 或 Image to 3D 的 task-by-id 端點）——通常間隔幾秒。

• 檢查每個回應中的 status 欄位。當狀態為 PENDING 或 IN_PROGRESS 時繼續輪詢。

• 一旦 status 為 SUCCEEDED（讀取結果 URL）、FAILED 或 CANCELED 就停止輪詢。

• 在用戶端中加入合理的逾時/最大嘗試次數限制，避免任務卡住時持續輪詢。

輪詢機制簡單明瞭，適合腳本、批次作業和低流量整合。對於高流量或延遲敏感的整合，Webhook 通常是更好的選擇。

不用反复询问"完成了吗？"，您可以要求 Meshy 在任務完成的那一刻通知您的伺服器。若要使用 Webhook：

• 設定 Meshy 可存取的 Webhook（回呼）URL——根據端點不同，這通常在帳戶/API 設定層級設定，或作為生成請求的參數傳遞。

• 確保您的端點可通過 HTTPS 公開存取，並快速回應（立即返回 2xx 狀態，然後非同步處理承載）。

• 當任務到達最終狀態時，Meshy 會將包含任務 id 及其最終 status 的承載傳送至您的端點。

• 收到後，透過 API 以 id 查詢完整的任務詳情，而非僅信任 Webhook 主體，以確保您獲得權威且最新的結果。

Webhook 可減少不必要的 API 呼叫並提供近即時通知，但您仍應保留定期輪詢備援，以防 Webhook 傳遞因您端的短暫網路問題等因素而遺漏或延遲的任務。

無論您使用輪詢還是 Webhook，您的結果處理程式碼都應該是冪等的——對於同一任務執行多次而不產生副作用，確保安全。這一點很重要，因為：

• 同一任務的 Webhook 可能會傳送多次（傳送端重試、網路複製等）。

• 如果輪詢迴圈和 Webhook 處理器同時執行，兩者都可能嘗試處理同一個已完成的任務。

要保持冪等性，請將處理邏輯建立在任務 id 上——例如，在再次執行之前，檢查您是否已經儲存/下載了該 id 的結果，並將「標記為已處理」作為您自己資料庫中的單一原子步驟。

當回應包含 "status": "SUCCEEDED" 且 "progress": 100 時，這是唯一能保證結果承載（模型 URL、紋理、縮圖）已完整且可安全使用的信號。具體來說，在您的程式碼中：

• 在讀取 result/模型 URL 欄位中的任何內容之前，請先驗證 status === "SUCCEEDED"。

• 不要僅依賴 progress——務必同時檢查 status，因為進度可能會在任務完全完成前短暫顯示高數值。

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

大多數「我無法取得模型」的報告都源自以下其中一個原因：

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

• 資產過期。 在 SUCCEEDED 之後等待太久才下載——結果 URL 會在該任務類型的保留期限過後停止運作。

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

• 將 FAILED 視為暫時狀態，並繼續輪詢已失敗的任務，而不是重新提交。

• 您的伺服器與 Meshy 之間的網路/逾時問題，被錯誤解讀為生成問題。

如果生成結果不符合預期，或請求完全失敗，請牢記以下幾點：

• Meshy API 目前不支援原地重試現有任務——若要重試，請提交新的生成請求，這會正常消耗點數。

• 呼叫 API 時若遇到暫時性網路故障（逾時、5xx 回應），在重新提交請求前稍作指數退避是合理的做法。

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

• 如果需要內建的重試功能，請聯繫 Meshy 的業務團隊以了解企業方案選項。

這幾乎都是因為程式碼在任務完成前就嘗試讀取結果。在取得模型 URL 前，請務必確認 status 為 SUCCEEDED（且 progress 為 100）。

輪詢較容易設定，適合低用量或一次性腳本。Webhook 則更適合需要處理多個並發任務的正式環境整合，因為它們可避免不必要的重複請求，並在任務完成時立即通知您。

以冪等方式處理——檢查任務 id 是否已處理過，若已處理則跳過重複處理。

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

目前尚不支援——您需要提交新的生成請求，這會正常消耗點數。若需要內建的重試支援，請聯繫銷售團隊了解企業方案。

任務完成後，結果檔案只會在 Meshy 的伺服器上保留有限時間，因此請在任務成功後立即將輸出下載至您自己的儲存空間，而非等待。