Errors

了解請求或任務失敗的原因，以及接下來該怎麼做。請求可能會立即出現 HTTP 錯誤而失敗，任務也可能稍後因 task_error 而失敗。

請求錯誤

當 Meshy 拒絕一個請求時，會立即回傳這些錯誤。要找出問題所在，請檢查 HTTP 狀態碼和 message 欄位。

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

任務錯誤

Meshy 建立的任務在執行過程中仍可能失敗。此時其 status 會變為 FAILED，Meshy 會退還相應的積分，並且 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 生成。

例如：

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

以下輸入很可能過於複雜：

要解決這個問題，請嘗試以下一種或多種方法：

• 每張圖像使用一個物體。Meshy 在處理單一、清晰的主體時效果最佳，因此不要在同一張圖像或 prompt 中放入多個獨立的物體。
• 簡化你的主體。例如，使用一個簡單的花瓶，而不是插滿幾十朵花的花瓶。
• 避免使用場景。整棟建築、城市街區、帶家具的房間和風景通常過於複雜。請聚焦於單一物體。
• 避免密集的重複結構。鷹架、金屬網、格柵以及成堆的小物件都是常見的觸發因素。

model_missing_uv

您發送了一個用於 texture 生成的模型，並將 enable_original_uv 設定為 true，但該模型沒有 UV 座標。UV 座標定義了 2D texture 如何包覆到 3D 表面上。

要解決此問題，請執行以下操作之一：

• 若要保留模型自身的 UV 配置，例如為了自訂接縫位置，請在您的 3D 軟體中為模型新增 UV。在其 UV editor 中檢查無誤後，再重新上傳模型。STL 檔案無法儲存 UV，因此請使用 GLB、FBX 或 OBJ。
• 如果您不需要自己的配置，或者不確定是否需要，請不要設定 enable_original_uv，或將其設定為 false。Meshy 隨後會為模型建立一個 UV 配置。新的 UV 能很好地覆蓋模型，但您無法控制 texture 接縫的位置。

model_insufficient_uv

模型擁有 UV 座標，但它們覆蓋的 UV 空間太小，無法很好地進行 texture 處理。模型的匯出工具寫入了預留位置或未經正確展開的折疊 UV 時，經常會發生這種情況。

要解決此問題，請執行以下操作之一：

• 若要保留你自己的 UV 配置，請在你的 3D 軟體中重新展開模型的 UV。將 UV 島分佈到整個 UV 空間，而不是局限在其中一個小角落。
• 如果你不需要自己的配置，請省略 enable_original_uv 或將其設定為 false。Meshy 隨後會建立一個新的 UV 配置。你會失去原有的接縫位置，但新的 UV 會覆蓋足夠的空間以便進行 texture 處理。

model_missing_texture

Multi-Color Print 任務的輸入模型沒有任何 Meshy 可以拆分為列印顏色的顏色。Meshy 會根據模型的顏色建構多色 3MF，因此純白色的 mesh 沒有可用的素材。例如，從未進行過 texture 處理的 Text to 3D 或 Image to 3D 預覽沒有顏色。可列印性修復的輸出，或未保留 texture 的 Auto Split 任務也同樣沒有顏色。

什麼算作顏色取決於你請求的 style：

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

如果模型既沒有基礎顏色 texture 也沒有頂點顏色，Meshy 會拒絕該模型用於這兩種 style，而不是讓 cartoon 將其轉換為單色列印。

Meshy 會在建立任務之前拒絕這類請求中的大多數，回傳 400 及相同的說明。通常只有在 Meshy 無法提前檢查輸入時，你才會得到這個代碼。例如，Meshy 僅在任務完成轉換後才會檢查 .fbx 上傳檔案。

要解決此問題，請使用適合你模型的方案：

• 先為模型新增 texture。對其執行 Retexture，或透過 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"。

textured_split_refused

Auto Split 任務中 keep_texture: true 時無法在拆分後的部件上保留輸入模型的 texture。例如，模型沒有 UV，或者其 texture 沒有足夠的空間容納切割產生的新面。此時 Meshy 會退還積分。

要解決此問題，請在不帶 keep_texture 參數或將其設為 keep_texture: false 的情況下重新發送請求。此後各部件將各自以單一純色回傳。

invalid_input

輸入未通過檢查，且沒有更具體的代碼適用於此情況。message 會給出具體原因。

例如：

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

要解決此問題，請查看 message 以了解具體問題，並檢查你的輸入檔案和參數是否滿足該 endpoint 的要求。

moderation_blocked

安全過濾器拒絕了您的 prompt 或參考圖片。過濾器會同時檢查文字和圖片。

要解決此問題，請執行以下一項或兩項操作：

• 修改 prompt，移除暗示性或敏感的描述內容。
• 更換可能被過濾器攔截的參考圖片內容。

moderation_unavailable

類型：server_error。內容 moderation 暫時不可用，因此 Meshy 使任務失敗，而不是跳過檢查。您的內容本身並無問題。

要解決此問題，請重新建立任務。

timeout

任務超出了伺服器端的時間限制——無論是處理逾時還是排隊等待逾時——因此 Meshy 判定任務失敗並退還了積分。高負載，或輸入過於複雜而無法在規定時間內完成，都可能導致這種情況。

這與你自己程式碼中的 timeout 不同。如果你的客戶端停止等待，任務實際上仍在執行。請參閱需要等待多久。

要解決此問題，請按以下步驟操作：

1. 重新建立任務。timeout 往往是暫時性的，新建的任務可能會成功。
2. 如果仍然持續失敗，請簡化你的輸入，例如降低圖像或 prompt 中的細節程度。對於更難處理的輸入，請參閱 image_too_complex。

queue_timeout

類型：timeout。任務在佇列中等待時間過長而未能開始，因此 Meshy 判定該任務失敗，並退還了為其扣除的所有積分。此錯誤並非由你的輸入引起。

要解決此問題，請重新建立任務。

format_conversion_failed

Meshy 已生成模型，但將其轉換為你所請求的格式時失敗。

要解決此問題，請按以下步驟操作：

1. 重新建立任務。
2. 如果某個格式始終轉換失敗，請改為請求符合你需求的其他格式。

最佳實踐

• 重試失敗的任務。對於狀態為 timeout、service_unavailable 或 server_error 的失敗任務，使用指數退避策略建立新任務。
• 當自己的請求逾時時不要建立新任務。第一個任務可能仍在執行，因此在建立另一個任務之前，請先檢查它是否存在。請參閱應等待多長時間。
• 記錄任務 ID。聯絡支援團隊時請附上該 ID。
• 發送輸入前先進行檢查。確保圖像和模型符合該 endpoint 的格式要求。
• 從伺服器呼叫 API。在瀏覽器中執行的程式碼會將你的 API key 暴露給任何開啟該頁面的人。