錯誤

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

請求錯誤

當您的 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. 避免 scene 層級的 prompt。 整棟建築、城市街區、擺滿家具的室內空間或風景，很可能超出模型的處理能力。請將重點放在單一物件上。
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

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

解決方法：

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

timeout

此錯誤表示您的任務處理時間超出了允許的限制。這可能是由於系統負載過高，或輸入內容過於複雜而無法在時限內處理完成所致。

解決方法：

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

format_conversion_failed

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

解決方法：

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

最佳實務

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