Creative Lab 燈具 API

用於製作燈罩的照片，可以是公開可存取的 URL 或 Data URI（data:image/jpeg;base64,<your base64-encoded image data>）。

圖片必須為 JPG、JPEG、PNG 或 WebP 檔案，且大小不超過 20 MB。

照片中主體的類型，用於決定 Meshy 如何對其進行風格化處理。

可用取值：

• character：單一角色或物體，例如公仔、動物或吉祥物
• landscape：戶外場景或全景，例如山脈、城市景觀或森林

任務的名稱，最多 100 個字元。它會在任務的 name 欄位中返回。名稱過長會返回 400。

是否從 prototype 圖片中移除背景。設為 true 會返回帶透明背景的 RGBA PNG 圖片，方便你將主體放置在任意背景上。Meshy 也會基於去除背景後的圖片構建 3D 模型。如果 Meshy 無法移除背景，則會使用帶背景的原始圖片，任務依然會成功。

請求無法執行。例如：

• 缺少 image_url。
• 圖片不是 JPG、JPEG、PNG 或 WebP 檔案。
• 圖片過小、超過 20 MB，或超過最大像素數。
• Meshy 無法下載該圖片，例如 URL 返回 404 或逾時。
• Data URI 不是有效的 base64 編碼。
• 圖片被標記為 NSFW（不適宜工作場所）內容。
• image_subject 既不是 character 也不是 landscape。

錯誤訊息會說明發現的具體問題。修復請求後重新發送。

API 金鑰缺失或無效。請檢查 Authorization 請求頭。

以下情形之一適用：

• 帳戶積分不足。
• API 金鑰、工作區或成員已達到其積分限額。
• 帳戶處於免費方案。

請檢查你的積分和方案，然後重試。

你的團隊已開啟 IP Filtering（智慧財產權過濾），且 Meshy 將該圖片標記為涉及第三方智慧財產權。請發送你擁有使用權利的圖片。

達到了以下限制之一：

• 你發送的請求超過了速率限制所允許的數量。請等待幾秒鐘後重試。參見速率限制。
• 你排隊或正在執行的任務過多。請等待部分任務完成後重試。
• 在沒有剩餘積分的無限方案下，你達到了無需積分即可執行的任務數量上限。請等待某個任務完成，或增加積分。

Meshy 遇到了伺服器錯誤，例如無法對圖片執行智慧財產權檢查。Meshy 不會創建該任務，並會退還已扣除的任何積分。請重試該請求。

要構建的原型任務的 ID。它必須是您的帳戶透過 POST /openapi/creative-lab/lamp/v1/prototype 創建的任務，且狀態為 SUCCEEDED。

如果該 ID 不是來自 API 的 Lamp 原型任務（包括在 Web App 中創建的原型），將返回 404。

任務的名稱，最多 100 個字元。它會在任務的 name 欄位中返回。名稱過長會返回 400。

燈罩最大尺寸的大小，單位為毫米，範圍為 50 到 400。Meshy 會按比例均勻縮放模型以適配。0 表示使用預設值，超出該範圍的其他值會返回 400。

燈罩的壁厚，單位為毫米，最大為 10。0 表示使用預設值，負值或超過 10 的值會返回 400。

在底部切平的高度所佔模型高度的百分比，範圍為 1 到 100。平整的底部可讓燈罩放置在列印平台上，並為固定裝置留出空間。超出範圍的值會返回 400。

燈光固定裝置預設，用於設定 Meshy 如何構建底部。

可用值：

• bambu_mh001_60mm：底部開口的燈罩，帶有一個具有 60 mm 固定孔的底板（均位於 model_urls.lamp_stl 中），以及位於 model_urls.base_stl 中的固定裝置安裝件
• none：單個密封燈罩，位於 model_urls.lamp_stl 中，沒有 model_urls.base_stl

固定孔相對燈罩中心沿 X 軸移動的距離，單位為毫米，範圍為 -80 到 80。僅在 light_source_preset 不是 none 時適用。

固定孔相對燈罩中心沿 Z 軸（深度方向）移動的距離，單位為毫米，範圍為 -80 到 80。僅在 light_source_preset 不是 none 時適用。

在 Meshy 處理模型之前，圍繞 X 軸施加的旋轉角度，單位為度，範圍為 -360 到 360。Meshy 會以模型中心為基準，按 XYZ 歐拉角的方式依次施加這三個旋轉。

在 Meshy 處理模型之前，圍繞 Y 軸施加的旋轉角度，單位為度，範圍為 -360 到 360。

在 Meshy 處理模型之前，圍繞 Z 軸施加的旋轉角度，單位為度，範圍為 -360 到 360。

是否在 zip 壓縮包中添加一個 result.json 檔案，其中包含所執行流水線的名稱、警告資訊和檔案路徑。需要將 output.format 設定為 zip。若與 stl 一起設為 true 會返回 400。

構建返回的檔案。

可用值：

• stl：model_urls.lamp_stl，即帶底板的燈罩（當存在固定裝置預設時），以及當 light_source_preset 不是 none 時的 model_urls.base_stl
• zip：model_urls.bundle_zip 中的一個 zip 檔案，包含 lamp.stl，以及在適用時的 base.stl 和 result.json

請求無法執行。例如：

• input_task_id 缺失或不是有效的任務 ID。
• 原型任務的狀態不是 SUCCEEDED。如果仍在執行，請等待後重試。如果已失敗或被取消，請創建新的原型任務。
• 原型任務已成功，但沒有 3D 模型。請創建新的原型任務。
• 某個 options 欄位超出範圍或不是可用值。
• output.format 不是 stl 或 zip，或者未設定 zip 卻將 include_result_json 設為 true。

錯誤訊息會說明發現的具體問題。

API key 缺失或無效。請檢查 Authorization 請求標頭。

以下情況之一適用：

• 帳戶沒有足夠的積分。
• 該 API key、workspace 或成員已達到其積分限額。
• 帳戶使用的是免費方案。

請檢查您的積分和方案，然後重試。

input_task_id 與您的帳戶透過 API 創建的任何 Lamp 原型任務都不匹配。在 Web App 中創建的原型也會返回 404。請傳送原型創建回應中的 result ID。

達到以下限制之一：

• 您傳送的請求數超過了速率限制允許的數量。請等待幾秒鐘後重試。請參閱速率限制。
• 您排隊或正在執行的任務過多。請等待部分任務完成後再重試。
• 在無限制方案下且沒有剩餘積分時，您已達到無需積分即可執行的任務數量上限。請等待某個任務完成，或添加積分。

建立回應中回傳的任務 ID。

id 不是有效的任務 ID。請傳送建立回應中的 result ID。

你的團隊已開啟 IP Filtering（智慧財產權過濾）功能，且 Meshy 將該原型任務的圖片標記為涉及第三方智慧財產權。建構任務以及 Enterprise 方案團隊不會出現此錯誤。請使用你擁有使用權的圖片來建立原型任務。

你的帳戶下不存在此 ID 對應的燈具任務，或者該任務所處的階段與路徑不符。請檢查 ID，並使用 /prototype 或 /build 來對應相符的任務。

Meshy 無法執行智慧財產權檢查。請重試該請求。

要取消的任務的 ID。

以下情況之一：

• id 不是有效的任務 ID。請傳送建立回應中的 result ID。
• 任務已處於最終狀態（SUCCEEDED、FAILED 或 CANCELED），因此無法取消。

你的帳戶下沒有該 ID 對應的燈具任務，或任務所處的階段與路徑不匹配。請檢查 ID，並使用 /prototype 或 /build 以匹配對應任務。

建立回應中返回的任務 ID。

要列出的階段，prototype 或 build。

要返回的頁碼，範圍從 1 到 255。0 返回第一頁。超出 0 到 255 範圍的值將返回 400。

每頁任務數，最多 100。101 到 255 之間的值將返回 100 個任務，0 使用預設值。超出 0 到 255 範圍的值將返回 400。

排序順序。

可用值：

• -created_at：最新的排在最前
• +created_at：最舊的排在最前

任務 ID。請勿依賴其格式。

任務類型，固定為 creative-lab-lamp-prototype。

你在建立任務時傳送的 name，如果未傳送，則為 ""。

任務的狀態。

可用值：

• PENDING：在佇列中等待
• IN_PROGRESS：正在產生結果
• SUCCEEDED：最終狀態，已取得結果
• FAILED：最終狀態，原因見 task_error
• CANCELED：最終狀態，沒有結果

已完成工作的百分比，從 0 到 100。任務開始前為 0，成功後為 100。

任務建立的時間，以 Unix 毫秒表示。

worker 開始執行任務的時間，以 Unix 毫秒表示。在此之前為 null。

任務達到最終狀態的時間，以 Unix 毫秒表示。在此之前為 null。

任務結果過期的時間，以 Unix 毫秒表示。該時間為 finished_at 之後 3 天；在任務完成之前，則為 created_at 之後 3 天。對於會無限期保留 API 結果的企業版帳戶，該時間大約是 100 年後。參見資產保留期。

任務處於 PENDING 狀態時在佇列中的位置。1 表示下一個就輪到它開始。任務離開佇列後為 0，在清單結果中始終為 0。

任務失敗的原因。除非 status 為 FAILED，否則為 null。參見 錯誤。

該任務扣除的積分數量（已扣除任何退款）。回傳錯誤的請求不會被扣費。失敗的任務為 0，因為 Meshy 會退還該費用。取消任務僅在其處於 PENDING 狀態時才會退款。如果 Meshy 無法讀取扣費資訊，get 或 stream 回應會省略該欄位，而 list 請求會回傳 500。在這種情況下，請重試該請求。

從概念圖產生的 3D 模型的下載 URL。在任務成功之前為 {}。

3D 模型預覽圖的下載 URL。在任務成功之前為 ""。

概念圖的下載 URL。任務成功後，陣列中包含一個 URL；在此之前為空陣列。

任務 ID。不要依賴其格式。

任務類型，始終為 creative-lab-lamp-build。

建立任務時你發送的 name，如果沒有發送則為 ""。

任務的狀態。

可用取值：

• PENDING：在佇列中等待
• IN_PROGRESS：正在產生結果
• SUCCEEDED：最終狀態，附帶結果
• FAILED：最終狀態，原因見 task_error
• CANCELED：最終狀態，沒有結果

已完成工作的百分比，範圍從 0 到 100。在任務開始之前為 0，成功後為 100。

任務建立的時間，採用 Unix 毫秒時間戳。

工作程序開始處理任務的時間，採用 Unix 毫秒時間戳。在此之前為 null。

任務達到最終狀態的時間，採用 Unix 毫秒時間戳。在此之前為 null。

任務結果過期的時間，採用 Unix 毫秒時間戳。該時間為 finished_at 之後的 3 天；在任務完成之前，則為 created_at 之後的 3 天。對於會無限期保留 API 結果的企業版帳戶，該時間大約在 100 年之後。請參閱資產保留期。

任務處於 PENDING 狀態時在佇列中的位置。1 表示下一個就會開始處理該任務。任務離開佇列後為 0，在列表結果中始終為 0。

任務失敗的原因。除非 status 為 FAILED，否則為 null。請參閱錯誤。

任務扣除的積分數量（已扣除任何退款）。回傳錯誤的請求不會被扣費。失敗的任務為 0，因為 Meshy 會退還費用。只有在任務處於 PENDING 狀態時取消才會退款。如果 Meshy 無法讀取扣費資訊，獲取或串流回應會省略該欄位，而列表請求會回傳 500。這種情況下，請重試該請求。

可列印檔案的下載連結。出現哪些鍵取決於 output.format 和 options.light_source_preset。