錯誤處理

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

請求錯誤

這些錯誤會在 API 請求遭拒時立即傳回。請檢查 HTTP 狀態碼和 message 欄位以了解錯誤原因。

{
  "message": "无效的模型文件扩展名: .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

當輸入圖像或提示所描述的主體幾何複雜度超出 3D 生成模型的處理能力時，會出現此錯誤。

常見範例包括：

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

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

解決方案：

1. 每張圖像使用單一物體。 模型對單一且清楚的主體效果最佳。不要在同一張圖像或提示中包含多個獨立物體。
2. 簡化您的主體。 減少細節層次。例如，使用簡單的花瓶，而不是裝滿數十朵花的花瓶。
3. 避免場景層級的提示。 完整的建築、城市街區、擺滿家具的室內空間或風景，可能超出模型的處理能力。請專注於單一物體。
4. 避免密集的重複結構。 鷹架、金屬絲網、網格圖案或大量小物體堆疊，是常見的觸發因素。

model_missing_uv

當您上傳模型進行貼圖時將 enable_original_uv 設定為 true，但模型沒有 UV 座標時，會出現此錯誤。UV 座標定義了 2D 紋理如何包覆在模型的 3D 表面上。

解決方案：

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

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

model_insufficient_uv

當模型具有 UV 座標，但 UV 覆蓋率不足以進行高品質貼圖時，會出現此錯誤。這通常發生在 3D 工具匯出時產生了佔位或摺疊的 UV，而沒有進行適當展開的情況下。

解決方案：

• 如果您需要保留原始 UV 配置： 在 3D 軟體中重新展開模型的 UV。確保 UV 島在 UV 空間中正確展開，而不是摺疊在小區域內。
• 如果您不需要特定的 UV 控制： 省略 enable_original_uv 或將其設定為 false。系統將自動產生新的 UV 配置。代價是您將失去原始的接縫位置，但自動產生的 UV 將具有適當的貼圖覆蓋率。

invalid_input

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

常見原因包括：

• 空白或損毀的模型檔案
• 不支援的檔案格式變體（例如 ASCII FBX 檔案、meshopt 壓縮的 GLB）
• 上傳的模型中未找到有效的 3D 物件（例如檔案僅包含骨架、攝影機或燈光）
• 內容未通過安全性篩選器

解決方案： 查看 message 欄位以了解具體錯誤原因。驗證您的輸入檔案和參數是否符合端點的要求。

moderation_blocked

當您的提示或參考圖像遭 AI 安全性篩選器拒絕時，會出現此錯誤。篩選器會同時評估文字提示和參考圖像。

解決方案：

• 修改您的文字提示，移除具暗示性或敏感的描述。
• 調整參考圖像，確保其不包含可能觸發安全性篩選器的內容。

timeout

此錯誤表示任務的處理時間超出了允許的限制。這可能是由於系統負載較高，或輸入過於複雜所導致。

解決方案：

1. 重試請求。 timeout 通常是暫時性的，重試可能會成功。
2. 簡化您的輸入。 如果重試持續失敗，您的輸入可能過於複雜。嘗試減少圖像或提示中的細節程度。請參閱 image_too_complex 了解哪些類型的輸入較難處理。

format_conversion_failed

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

解決方案：

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

最佳實務

1. 實作重試邏輯。 對於 timeout 和 service_unavailable 錯誤，實作指數退避重試邏輯。
2. 記錄任務 ID。 一律記錄任務 ID 以便偵錯。聯絡支援團隊時請提供任務 ID。
3. 驗證輸入。 提交前，請確保您的輸入圖像和模型符合格式要求。