如何使用 Image to 3D Model API：完整指南 2026

Image to 3D Model API 能將單張照片在數秒內轉換為可立即投入生產的 3D 模型，無需手動建模。手動為每個素材建模既緩慢又昂貴，對遊戲工作室、AR 應用和電商團隊而言，很快就會成為延誤上線的瓶頸。Meshy 的 image-to-3D model API 消除了這個障礙：上傳圖片，數秒內轉換為 3D 模型，並下載 GLB、FBX 和 OBJ 等格式的完整紋理網格。本指南將帶您走過完整流程——從建立 API 金鑰到下載第一個模型——並提供可直接執行的複製貼上程式碼。

什麼是 Image to 3D Model API？

核心上，Image to 3D Model API 是一個由 Meshy 的 image to 3D model AI 驅動的 REST 端點。您上傳單張圖片（JPG、JPEG 或 PNG）作為公開 URL 或 base64 字串，API 就會回傳一個帶紋理的 3D 模型——包含幾何形狀與基礎顏色紋理——格式為標準的 GLB、FBX、OBJ、USDZ、STL 和 3MF。可選附加功能包括 PBR 貼圖、高達 4K 的紋理，以及多角度預覽縮圖。

由我們最新的 Meshy 6 模型驅動，此 API 讓您能設定拓樸與多邊形數量、選擇姿勢模式，並透過文字提示或參考圖片引導紋理生成——非常適合為遊戲、AR/VR、3D 列印和產品視覺化生成素材。

使用 Image to 3D API 需要什麼？

您不需要太多東西就能跟著本指南操作。請確保您有：

• 一個 Meshy 帳戶 — 如果還沒有，請免費註冊。您將在步驟 1 中從控制台產生 API 金鑰。

• 一個 API 金鑰 — 用於驗證每個請求。我們會逐步引導您建立一個，您也可以使用免費的測試模式金鑰來跟著操作，而不消耗點數。

• 一張輸入圖片 — 一張清晰的 .jpg、.jpeg 或 .png 圖片，需託管在可公開存取的 URL（或編碼為 base64）。乾淨的背景和清晰可見的主體能獲得最佳效果。

• 一種發送 HTTP 請求的方式 — curl（用於下方範例）、Postman，或您選擇的程式語言中的任何 HTTP 函式庫。對 REST API 和 JSON 有基本了解會有幫助，但非必要。

就這樣——不需要 3D 建模經驗。讓我們開始吧。

如何使用 API 將圖片轉換為 3D 模型（逐步指南）

步驟 1：設定您的 API 設定

開始建置所需的一切都在 API 設定頁面上。這是您 Meshy API 的控制中心，包含三個關鍵部分：

• API 金鑰 — 產生和管理用於驗證您請求的金鑰。

• Webhook — 當您的任務完成時自動接收通知。

• 使用量 — 即時追蹤您剩餘的點數餘額和 API 消耗。

讓我們逐一介紹。

取得您的 API 金鑰

在發出任何請求之前，您需要一個 API 金鑰來安全地進行驗證。在 API 設定頁面上，點擊產生 API 金鑰。每個金鑰的格式為 msy-<隨機字串>。

提示： 產生後，請將您的 API 金鑰存放在安全的地方（例如密碼管理器或環境變數）。將其視為密碼——切勿提交到原始碼控制或暴露在客戶端程式碼中。

測試模式 API 金鑰

在開發和測試期間，您可以使用測試模式 API 金鑰來探索 API，而不消耗您的點數：

msy_dummy_api_key_for_test_mode_12345678

這個特殊金鑰具有以下特性：

• 可用於向所有 Meshy API 端點發送請求。

• 使用此金鑰時不消耗點數。

• 所有有效請求都會回傳相同的範例任務結果，無論輸入參數為何。

• 回應資料結構與正式環境 API 完全一致。

這使其非常適合在切換到真實 API 金鑰之前測試您的整合。

設定 Webhook（可選）

生成 3D 模型需要時間，因此與其重複輪詢 API 來檢查任務是否完成，不如讓 Meshy 在完成時立即通知您。這就是 webhook 的用途。

在設定頁面的 Webhook 部分，新增一個端點 URL，Meshy 會將事件通知發送到該處。當任務狀態改變時（例如完成或失敗），Meshy 會向您的 URL 發送一個 HTTP POST 請求，並在 payload 中包含任務詳細資訊。

提示： Webhook 是正式環境的推薦方法。它們減少了不必要的 API 呼叫，並讓您的應用程式能即時回應結果。對於快速測試，輪詢仍然可行。若要在本地測試 webhook 程式碼，請將其指向來自 smee.io 等服務的代理 URL。

無需程式碼試試看 — API Playground（可選）

已經有 API 金鑰了嗎？在編寫任何程式碼之前，您可以直接在瀏覽器中執行一個真實的 Image to 3D 任務。

開啟 meshy.ai/api-playground，從左側面板選擇 Image to 3D，然後填入三項資訊：

1. Authorization — 貼上您的 API 金鑰（msy-xxxxxxxxxx）

2. Image — 從您的電腦上傳 .jpg、.jpeg 或 .png 檔案

3. 點擊 Send

Playground 會自動提交任務並輪詢結果。完成後，您會直接在瀏覽器中看到 3D 模型預覽和下載連結——無需編寫任何程式碼。

專業提示： 右側的原始請求/回應面板會準確顯示 API 發送和回傳的內容。您可以直接複製內容——從回應中取得 task_id，並在任務完成後取得 model_urls。您將在接下來的步驟中使用這兩者。

步驟 2：提交一個 Image to 3D 任務

準備好 API 金鑰後，透過一個 POST 請求來啟動任務：

curl -X POST https://api.meshy.ai/openapi/v1/image-to-3d \
  -H "Authorization: Bearer $MESHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/your-image.png"
  }'

您會得到類似這樣的回應：

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

那個 result 值就是您的 task_id——請儲存它。您需要在下一步中使用它來檢查進度並取得模型。

可選： 若要在任務完成時自動收到通知，請在 JSON body 中加入 webhook_url 欄位——例如 "webhook_url": "https://yourapp.com/webhooks/meshy"。請參閱步驟 3，選項 B 了解其運作方式。

步驟 3：取得您的結果

您的任務不會立即完成——Meshy 會在背景處理它。您有兩種方式取得結果：

選項 A：輪詢狀態（最簡單）

每 5 秒發送一個 GET 請求，直到 status 變為 SUCCEEDED：

curl https://api.meshy.ai/openapi/v1/image-to-3d/{task_id} \
  -H "Authorization: Bearer $MESHY_API_KEY"

回應看起來像這樣：

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_url": "https://assets.meshy.ai/.../model.glb",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb",
    "fbx": "https://assets.meshy.ai/.../model.fbx",
    "obj": "https://assets.meshy.ai/.../model.obj",
    "usdz": "https://assets.meshy.ai/.../model.usdz",
    "stl": "https://assets.meshy.ai/.../model.stl",
    "mtl": "https://assets.meshy.ai/.../model.mtl"
  },
  "thumbnail_url": "https://assets.meshy.ai/.../thumbnail.png",
  "consumed_credits": 30
}

一些值得了解的欄位：

• model_urls 包含每種生成格式的下載連結。預設情況下，這包括 glb、fbx、obj、usdz、stl 和 mtl（與 obj 搭配的材質檔案）。

• model_url 是 GLB 連結的捷徑——當您只需要 GLB 時很方便。

• consumed_credits 顯示任務使用了多少點數（失敗任務為 0，因為點數會退還）。

• thumbnail_url 始終存在，指向正面視角的縮圖。

• thumbnail_urls 僅在 multi_view_thumbnails: true 時出現，包含正面、右側、背面和左側視角。

• alpha_thumbnail_url 僅在 alpha_thumbnail: true 時出現，包含透明背景的縮圖。

可能的 status 值：PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

選項 B：Webhook（推薦用於正式環境）

如果您在步驟 2 中設定了 webhook_url，Meshy 會自動將完成的任務物件 POST 到您的 URL——無需輪詢。

{
  "image_url": "https://example.com/your-image.png",
  "webhook_url": "https://yourapp.com/webhooks/meshy"
}

💡 我該使用哪一種？ 輪詢適用於原型開發和一次性任務。在正式環境中使用 webhook——它更可靠且節省 API 呼叫。

步驟 4：下載您的 3D 模型

一旦 status 變為 SUCCEEDED，從 model_urls 中取得下載 URL，並下載您需要的格式：

curl -o model.glb "https://assets.meshy.ai/.../model.glb"

-o model.glb 標誌會將檔案以該名稱儲存到您目前的工作目錄——使用完整路徑（例如 -o /path/to/model.glb）可將其儲存到其他位置。

預設情況下，每個任務都會回傳 GLB、FBX、OBJ、USDZ、STL 和 MTL（OBJ 的材質檔案）。3MF 是選擇加入的——只有當您透過 target_formats 明確請求時才會獲得（請參閱下方的參數表）。

⚠️ 連結在 3 天後過期（企業方案可獲得永久連結）。請及時下載並儲存您的模型——連結過期後將無法使用，您需要重新執行任務。

準備好在您的 DCC 工具中使用這個模型了嗎？請參閱 Bridge to Blender 指南——Meshy 也提供 Unity、Unreal、Maya 以及更多的橋接工具。

如何獲得最佳的 image-to-3D 結果？

• 使用單一、清晰可見的主體。 一個主要物體，居中且完整在畫面中，能為 AI 提供最清晰的參考——避免雜亂的場景、過度裁切和極端角度。

• 偏好乾淨、不雜亂的背景。 純色或簡單的背景有助於模型將主體與周圍環境分離。

• 使用均勻、漫射的光線。 強烈的陰影和高光可能會在生成的紋理中嵌入誤導性的細節。

• 從高解析度、清晰的圖片開始。 輸入的細節越多，輸出的細節就越多——模糊或低解析度的輸入會產生較柔軟的模型。

我可以使用哪些程式語言搭配 Image to 3D API？

任何能夠發送 HTTP 請求的語言都可以——您發送一個帶有 JSON 的 POST 請求，並使用 GET 進行輪詢。常見選項：

• Python — 使用 requests 或 httpx 函式庫

• JavaScript / TypeScript — 使用 fetch（內建）或 axios

• Go — 使用標準函式庫中的 net/http

• cURL — 非常適合從終端機進行快速測試

您也可以在 API Playground 中找到所有四種語言的現成程式碼範例。

一個 Image to 3D 任務需要多少點數？

費用取決於模型版本以及您是否生成紋理。預設設定（meshy-6 搭配紋理）每個任務花費 30 點數：

失敗的任務會自動退還點數——consumed_credits 會回傳 0。請務必查看定價頁面以了解最新費率。

Image to 3D API 接受哪些參數？

發送 POST 到 /openapi/v1/image-to-3d，使用以下參數： 必要（擇一）：

可選：

Image to 3D API 的下一步

您現在已經掌握了完整的流程：建立 API 金鑰、提交圖片、輪詢或使用 webhook 取得結果，然後下載您的模型。這四個步驟可以從快速原型擴展到自動將數千張圖片轉換為 3D 素材的正式環境管線。立即從 API 設定頁面取得您的金鑰，並交付您的第一個模型。偏好從提示而非照片開始？請使用 Text to 3D Model API。

常見問題

如何透過 API 將圖片轉換為 3D 模型？

向 /openapi/v1/image-to-3d 發送一個帶有 image_url 和 API 金鑰的 POST 請求，然後輪詢任務（或使用 webhook）直到其 status 變為 SUCCEEDED。回應會回傳生成模型的下載連結。完整的四個步驟流程——金鑰、提交、取得、下載——已在上方的逐步指南中說明。

API 支援哪些輸出格式（STL、GLB、OBJ）？

每個任務預設會回傳 GLB、FBX、OBJ、USDZ、STL 和 MTL，3MF 可透過 target_formats 請求取得。GLB 最適合網頁和 AR，FBX 和 OBJ 適用於 DCC 工具和遊戲引擎，USDZ 適用於 iOS AR，STL 適用於 3D 列印。

我可以上傳哪些圖片格式？

Image to 3D API 支援 JPG、JPEG 和 PNG 圖片，最大 100 MB——比 Meshy Workspace UI 的 20 MB 限制更大。為獲得最準確的結果，請使用具有透明或乾淨白色背景的 PNG，這有助於 API 分離主體並生成更高品質的 3D 模型。

我可以從 API 獲得帶紋理的 3D 模型嗎？

可以。紋理生成預設為啟用（"should_texture": true）。若要添加 PBR 貼圖（金屬度、粗糙度、法線），請設定 "enable_pbr": true——在 meshy-6/latest 上，這還會包含發光貼圖。若要獲得 4K 基礎顏色紋理，請設定 "hd_texture": true（僅 meshy-6/latest 支援；PBR 貼圖保持 2K）。您也可以使用 texture_prompt 或 texture_image_url 來引導紋理風格。

我可以生成準備好進行 3D 列印（STL）的 3D 模型嗎？

可以——STL 預設會生成，因此圖片轉 3D STL 不需要額外參數：只需在任務完成時取得 model_urls.stl 即可。這使得圖片轉 3D 列印的工作流程變得簡單，因為 STL 是切片軟體預期的標準格式。如果您只需要 STL，請設定 "target_formats": ["stl"] 以跳過其他格式並縮短生成時間。

哪些方案包含 API 存取權限？

Pro、Studio 和 Enterprise 方案包含 API 存取權限——這是 Pro 及以上版本的功能。免費的 Starter 方案不包含 API 存取權限。詳情請參閱定價頁面。

下載連結的有效期是多久？

下載連結在 Pro 和 Studio 方案上有效期為 3 天。Enterprise 客戶可獲得永久連結。請及時儲存您的檔案——過期的連結無法恢復，您需要重新執行任務。

我可以同時執行多個任務嗎？

可以，支援並發請求。如果您遇到 429 Too Many Requests 錯誤，表示您的帳戶已達到速率限制——請實作指數退避並重試。請參閱速率限制頁面了解您方案的限制。

任務顯示 FAILED——我該怎麼辦？

檢查 task_error.message 以了解原因。常見原因：

如果問題持續存在，請聯絡 Meshy 支援團隊。