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. 避免 scene 層級的 prompt。 整棟建築、街區、擺滿家具的室內空間或風景，都很可能超出模型的處理能力。請專注於單一物件。
4. 避免密集的重複結構。 鷹架、金屬網、格柵圖案，或堆積的大量小物件等主體，是常見的觸發因素。

model_missing_uv

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

解決方法：

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

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

model_insufficient_uv

此 Errors 發生於模型具有 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）。

對於這兩種 style，既沒有基礎顏色 texture 也沒有頂點顏色的模型都會被拒絕；否則在 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，刪除帶有暗示性或敏感性的描述。
• 如果參考圖片所描繪的內容可能觸發安全過濾器，請對其進行調整。

timeout

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

解決方法：

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

format_conversion_failed

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

解決方法：

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

最佳實踐

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