Errors

在本指南中，我們將討論當您在使用 Meshy API 時出現問題時會發生什麼。

請求錯誤（Request Errors）

當您的 API 請求被拒絕時，會立即返回這些錯誤。請檢查 HTTP 狀態碼和 message 欄位以瞭解出了什麼問題。

{
  "message": "Invalid model file extension: .3dm"
}

任務錯誤

這些錯誤發生在任務已建立並正在處理的過程中。請在任務回應中查看 task_error 物件以獲取錯誤詳情。

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "invalid_input",
    "code": "image_too_complex",
    "message": "The uploaded image is too complex for 3D generation.",
    "doc_url": "https://docs.meshy.ai/en/api/errors#image-too-complex"
  }
}

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "server_error",
    "message": "An internal error occurred. Please retry."
  }
}

錯誤類型

type 欄位告訴你失敗的大致類別。根據它來決定你的重試策略。

錯誤代碼

當 code 欄位存在時，它表示一個具體的、可操作的問題。以下是每個錯誤代碼的完整參考。

image_too_complex

當輸入圖片或 prompt 描述的主體在幾何結構上過於複雜，導致 3D 生成模型無法處理時，會出現此錯誤。

常見範例包括：

• 密集堆疊的小物體（例如裝滿水果的箱子、一疊書）
• 複雜的重複圖案（例如格柵結構、鷹架、金屬網）
• 複雜的建築結構（例如擁有許多窗戶和陽台的多層建築）
• 一張圖片中包含多個不同的物體，而非單一主體

可能過於複雜的輸入範例：

解決方法：

1. 每張圖片使用單一物體。 該模型在只有一個清晰主體時效果最佳。不要在同一張圖片或 prompt 中包含多個獨立的物體。
2. 簡化你的主體。 減少細節層次。例如，使用簡單的花瓶，而不是插滿幾十朵花的花瓶。
3. 避免場景級別的 prompt。 整棟建築、街區、擺滿傢俱的室內空間，或風景，很可能超出模型的處理能力。請專注於單一物體。
4. 避免密集的重複結構。 諸如鷹架、金屬網、格柵圖案，或大量小物件堆疊等主體，是常見的觸發因素。

model_missing_uv

當您上傳模型進行 texture 處理且將 enable_original_uv 設定為 true，但該模型沒有 UV 座標時，就會出現此錯誤。UV 座標定義了 2D texture 如何包裹到模型的 3D 表面上。

解決方法：

正確的修復方式取決於您為何將 enable_original_uv 設定為 true：

• 如果您需要保留模型原始的 UV 布局（例如，為精確的 texture 映射自訂接縫位置）：您的模型必須具有有效的 UV 座標。請在上傳前，在您的 3D 軟體的 UV 編輯器中確認 UV 確實存在。請注意，STL 檔案無法儲存 UV 資料，因此請改用 GLB、FBX 或 OBJ。
• 如果您不需要特定的 UV 控制（或不確定是否需要）：省略 enable_original_uv 或將其設定為 false。系統將自動為您的模型生成 UV 布局。自動生成的 UV 針對覆蓋率進行了最佳化，但您將無法控制 texture 接縫的具體位置。

model_insufficient_uv

此錯誤發生在模型具有 UV 座標，但 UV 覆蓋範圍過小，不足以支援高品質貼圖的情況下。這種情況通常發生在從 3D 工具匯出的模型上，這些工具生成了佔位或折疊的 UV，而沒有進行正確的展開。

解決方法：

• 如果你需要保留原始的 UV 布局： 在你的 3D 軟體中重新展開模型的 UV。確保 UV 島均勻分布在 UV 空間中，而不是折疊在一個很小的區域內。
• 如果你不需要特定的 UV 控制： 省略 enable_original_uv 或將其設定為 false。系統會自動生成一個新的 UV 布局。代價是你會失去原始的接縫位置，但自動生成的 UV 將具有適合貼圖的合理覆蓋範圍。

model_missing_texture

當 Multi-Color Print 任務的輸入模型沒有任何可供轉換器分離為列印顏色的顏色資訊時，會出現此錯誤。多色 3MF 是根據模型的顏色建構的，因此一個純白色的 mesh——例如從未經過 texture 處理的 Text to 3D 或 Image to 3D 預覽，或者經過修復 / 自動拆分後的輸出——沒有任何可用的資訊。

哪些內容可以算作顏色來源，取決於你所請求的 style：

• realistic 透過模型的 UV 對基礎顏色 texture 進行取樣，因此它要求每個 mesh 部件上都有帶 UV 座標的單一基礎顏色 texture。
• cartoon 按面將顏色扁平化，接受任意部件上的基礎顏色 texture 或 逐頂點顏色（COLOR_0）。

既沒有基礎顏色 texture 也沒有頂點顏色的模型，在兩種 style 下都會被拒絕；對於 cartoon，否則它會被當作單色列印「成功」處理。

大多數請求在任務建立之前就會被拒絕（返回 400 Bad Request 及相同的說明），因此通常只有在輸入無法提前檢查的情況下才會看到此錯誤碼——例如，.fbx 上傳檔案會在任務對其進行正規化處理後才被檢查。

解決方法：

• 先為模型加入 texture。 對其運行 Retexture 任務，或在生成時啟用 texture 處理（例如 Text to 3D 的 refine 任務，或設定了 should_texture: true 的 Image to 3D 任務），然後將該任務作為 input_task_id 傳入。
• 帶頂點顏色的模型（攝影測量掃描、手繪 mesh）：請求 style: "cartoon"，它會讀取 COLOR_0。
• 在 realistic 下部分加入了 texture 或包含多個 texture 的模型：每個 mesh 部件都需要 UV，並使用相同的單一基礎顏色 texture。請為剩餘部件加入 texture，或將這些 texture 合併為一個圖集，或改用 style: "cartoon"。

invalid_input

當輸入未通過驗證但沒有更具體的錯誤代碼適用時，會使用此回退錯誤代碼。message 欄位包含失敗的具體原因。

常見原因包括：

• 模型檔案為空或已損壞
• 不受支援的檔案格式變體（例如，ASCII 格式的 FBX 檔案、經過 meshopt 壓縮的 GLB）
• 上傳的模型中未找到有效的 3D 物件（例如，檔案僅包含骨架、相機或燈光）
• 內容未通過安全過濾器

解決方法： 查看 message 欄位以瞭解具體出錯原因。請確認你的輸入檔案和參數符合該端點的要求。

moderation_blocked

當您的 prompt 或參考圖像被 AI 安全過濾器拒絕時，會出現此錯誤。過濾器會同時評估文字 prompt 和任何參考圖像。

解決方法：

• 修改您的文字 prompt，移除帶有暗示性或敏感性的描述。
• 如果參考圖像描繪的內容可能觸發安全過濾器，請對其進行調整。

moderation_unavailable

當內容 moderation 暫時不可用時，會出現此錯誤，此時任務會被判定為失敗，而不是跳過檢查繼續運行。您的內容本身並沒有問題。其 type 為 server_error。

解決方法： 重新建立任務。

timeout

此錯誤表示任務超過了伺服器端的時間限制（處理時間或排隊等待時間），因此任務失敗，其 credits 已退還。這可能是由於系統負載過高，或者輸入過於複雜而無法在時間限制內處理完成。

這與您自己程式碼中的 timeout 不同。如果您的用戶端停止了等待，任務實際上仍在運行；請參閱任務生命週期。

解決方法：

1. 重新建立任務。 timeout 通常是暫時性的，新任務可能會成功。
2. 簡化您的輸入。 如果重試仍然持續失敗，您的輸入可能過於複雜。請嘗試降低圖片或 prompt 的細節程度。有關哪些類型的輸入更難處理的指導，請參閱 image_too_complex。

queue_timeout

此錯誤表示任務在佇列中等待時間過長而未能啟動，因此任務失敗，為其扣除的任何 credits 均已退回。這不是由您的輸入導致的。其 type 為 timeout。

解決方法： 重新建立任務。

format_conversion_failed

當生成的 3D 模型無法轉換為您請求的輸出格式時，會出現此錯誤。模型已成功生成，但轉換步驟失敗。

解決方法：

1. 重試該請求。
2. 嘗試其他輸出格式。 如果某個特定格式持續失敗，請切換到另一種適合您需求的格式。

最佳實踐

1. 實作重試邏輯。 當任務因 timeout、service_unavailable 或 server_error 錯誤而失敗時，請使用指數退避演算法重新建立任務。如果是您自己的請求超時，則不要建立新任務：請先檢查現有任務（參見任務生命週期）。
2. 記錄任務 ID。 始終記錄任務 ID 以便除錯。聯絡支援團隊時請附上該 ID。
3. 驗證輸入內容。 在提交之前，請確保您的輸入圖像和模型符合格式要求。
4. 從您的伺服器呼叫 API。 在瀏覽器中運行的程式碼會將您的 API 金鑰暴露給任何打開該頁面的人。