Errors

在本指南中，我們將介紹在使用 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 會有適合貼圖的合理覆蓋率。

model_missing_texture

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

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

• realistic 會透過模型的 UV 對基礎顏色紋理進行採樣，因此它要求每個網格部件上都有 UV 座標，並且只能有單一基礎顏色紋理。
• cartoon 會按面對顏色進行扁平化處理，接受任意部件上的基礎顏色紋理或逐頂點顏色（COLOR_0）。

既沒有基礎顏色紋理也沒有頂點顏色的模型，在兩種 style 下都會被拒絕；因為在 cartoon 下，若不這樣處理，它本會「成功」產生為單色列印。

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

解決方法：

• 先為模型加上紋理。 對其執行一個 Retexture 任務，或在生成時啟用紋理功能（例如 Text to 3D 的 refine 任務，或設定了 should_texture: true 的 Image to 3D 任務），然後將該任務作為 input_task_id 傳入。
• 頂點著色模型（攝影測量掃描、手繪網格）：請求 style: "cartoon"，該模式會讀取 COLOR_0。
• 在 realistic 下部分帶紋理或多紋理的模型：每個網格部件都需要 UV，並且需要使用相同的單一基礎顏色紋理。請為剩餘部件加上紋理，或將多個紋理合併為一張圖集，或者改用 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. 驗證輸入。 提交前請確保您的輸入圖像和模型符合格式要求。