任務生命週期
瞭解任務如何從請求發展到結果、通常需要多長時間，以及你的程式碼應該為此等待多久。
任務如何運行
建立請求會回傳一個任務 ID，而無需等待任務運作完成。該任務隨後在背景運作，你可以透過以下三種方式之一來追蹤它：輪詢其 GET 端點、開啟其串流端點，或接收一個 webhook。
PENDING 狀態啟動一個任務。工作進程接手後，任務會進入 IN_PROGRESS 狀態，大部分時間都處於該狀態。最終任務會以 SUCCEEDED 或 FAILED 結束，最終狀態不會再發生變化。PENDINGIN_PROGRESSSUCCEEDEDFAILED任務會在其 created_at、started_at 和 finished_at 欄位中記錄每個步驟。
下表展示了在每種狀態下你的程式碼應執行的操作。
| 狀態 | 你的程式碼應執行的操作 |
|---|---|
PENDING | 繼續等待。 |
IN_PROGRESS | 追蹤 progress：已完成工作的百分比，範圍從 0 到 100。 |
SUCCEEDED | 下載結果。Meshy 會在有限的時間內保留檔案。參見資產保留期。 |
FAILED | 讀取 task_error，然後修復輸入或建立新任務。參見 Errors。 |
CANCELED | 停止等待。該任務不會產生結果。只有 Creative Lab 任務會使用此狀態。 |
SUCCEEDED、FAILED 和 CANCELED 都是最終狀態。任務一旦達到其中之一，其狀態就不會再發生變化。
從你的程式碼角度來看，流程如下：
請求: POST/image-to-3d
回應: 202{ "result": "<task_id>" }任務已建立
- 每隔幾秒重複一次
請求: GET/image-to-3d/<task_id>
回應: 200{ "status": "IN_PROGRESS","progress": 45 }Retry-After: 5
請求: GET/image-to-3d/<task_id>
回應: 200{ "status": "SUCCEEDED","model_urls": { "glb": "…" } }
GET。處理時間
下表顯示的是 2026 年 9 月生產環境 API 流量中的中位耗時。
時間從任務建立開始計算，直至達到最終狀態。由於任務通常只會在 PENDING 狀態停留幾秒鐘，所以幾乎所有時間都用於處理。當佇列繁忙時，任務在開始前可能需要等待更長時間，而使用更高優先順序方案的任務通常會更快開始。
低於 2 分鐘的時間以秒（s）為單位，更長的時間以分鐘（min）為單位。「不支援」表示該模型下 API 不提供該選項。
3D 生成
| API | 設定 | meshy-7.1（latest） | meshy-6 | meshy-6-lite | meshy-t2 |
|---|---|---|---|---|---|
| Text to 3D (Preview) | 僅 Mesh | 75 秒 | 90 秒 | 45 秒 | 10 秒 |
| Image to 3D | 僅 Mesh | 75 秒 | 90 秒 | 40 秒 | 4 秒 |
| 帶 2K texture 的 Mesh | 2 分鐘 | 3 分鐘 | 75 秒 | 60 秒 | |
| 帶 4K texture 的 Mesh | 2.5 分鐘 | 3.5 分鐘 | 不支援 | 80 秒 | |
| 帶 8K texture 的 Mesh | 3.5 分鐘 | 4 分鐘 | 不支援 | 2.5 分鐘 | |
| Multi-Image to 3D | 僅 Mesh | 65 秒 | 2 分鐘 | 30 秒 | 不支援 |
| 帶 2K texture 的 Mesh | 2.5 分鐘 | 3.5 分鐘 | 85 秒 | 不支援 | |
| 帶 4K texture 的 Mesh | 3 分鐘 | 4 分鐘 | 不支援 | 不支援 | |
| 帶 8K texture 的 Mesh | 3.5 分鐘 | 4.5 分鐘 | 不支援 | 不支援 |
對於 Image to 3D 和 Multi-Image to 3D，「僅 Mesh」表示 should_texture: false。以下選項和輸入會改變耗時：
- PBR 貼圖（
enable_pbr）會增加 30 到 60 秒。 - 超精細 geometry（
geometry_resolution: "2k"或"4k"）最多會增加 1 分鐘。 - 在相同設定下，更複雜的輸入圖片耗時更長。
Texture 生成
| API | Texture 解析度 | 典型耗時 |
|---|---|---|
| Text to 3D (Refine) | 2K 或 4K | 80 秒 |
| 8K | 3.5 分鐘 | |
| Retexture | 2K | 55 秒 |
| 4K | 90 秒 | |
| 8K | 2.5 分鐘 |
影像生成
| API | nano-banana | nano-banana-2 | nano-banana-pro | GPT Image 模型 |
|---|---|---|---|---|
| Text to Image | 20 秒 | 15 秒 | 25 秒 | 20 到 35 秒 |
| Image to Image | 40 秒 | 20 秒 | 30 秒 | 20 到 40 秒 |
Rigging 與 Animation
| API | 設定 | 典型耗時 |
|---|---|---|
| Auto-Rigging | 自動 rigging | 40 秒 |
| Animation | 每次請求 | 15 秒 |
| Text to Motion | prime mode | 15 秒 |
swift mode | 10 秒 |
後處理
3D 列印
| API | 設定 | 典型耗時 |
|---|---|---|
| 可列印性分析 | 僅 Mesh 檢查 | 1 秒 |
| Mesh 與薄壁檢查 | 10 秒 | |
| Multi-Color | 每次請求 | 30 秒 |
| 可列印性修復 | 僅 Mesh 修復 | 10 秒 |
| 薄壁檢查，保留壁厚 | 20 秒 | |
| 薄壁檢查，加厚壁體 | 100 秒 | |
| Auto Split | 純色部件 | 70 秒 |
帶 texture 的部件（keep_texture: true） | 170 秒 |
在 v2 中，可列印性修復 和 可列印性分析 始終會運行薄壁檢查。在 v1 中，只有當你提供印表機類型或列印尺寸時才會運行該檢查。
應等待多久
即使你的程式碼停止等待，任務仍會繼續運行。如果你的請求逾時、連線中斷，或串流連線關閉，任務並不會因此失敗，也不會被取消。
- 從任務的
created_at開始計算，至少等待 60 分鐘後再停止等待。如果你過早停止，可能會錯過之後成功完成的任務。這種情況主要發生在繁忙期間。 - 保留任務 ID。你可以隨時再次取得該任務。如果 60 分鐘後仍未達到最終狀態，請稍後再次檢查。如果情況依舊如此，請聯絡支援團隊。
- 只有
FAILED才表示任務失敗。Meshy 會自動為失敗的任務退還積分。
請在你的程式碼中使用以下值：
| 設定 | 建議值 |
|---|---|
建立請求（POST）timeout | 60 秒 |
檔案大小超過 100 MB 的 model_url 建立請求（POST）timeout | 120 秒。Meshy 會先下載檔案，然後再做出回應。 |
狀態請求（GET）timeout | 30 秒 |
| 輪詢間隔 | Retry-After 回應標頭指定的值，若缺失則為 5 秒。輪詢會計入你的速率限制。 |
失敗的狀態請求（timeout、429 或 5xx） | 在下一次輪詢時重試。這並不意味著任務失敗。 |
| 每個任務的總等待時間 | 從 created_at 起至少 60 分鐘。重新連接串流時不要重新計時。 |
| 串流連線 | 串流可能會在任務完成前關閉。如果關閉時尚未得到最終狀態，請重新連接或改用輪詢。 |
如果需要同時處理大量任務，建議使用 webhooks，而不是逐一輪詢。如果某個任務的最終事件在其典型耗時的大約兩倍之後仍未到達，請透過其 GET 端點取得該任務。