Creative Lab 冰箱貼 API

要轉換為冰箱貼概念圖的照片，可以是公開可存取的 URL 或 Data URI（data:image/jpeg;base64,<your base64-encoded image data>）。

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

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

是否移除 prototype 圖像的背景。true 會回傳一張保留整個磁貼的透明 RGBA PNG，方便你將其放置在任意背景上。建構階段也會從去除背景後的圖像開始處理。如果 Meshy 無法移除背景，則會回傳帶有背景的圖像，任務仍然算作成功。

建構階段的 remove_background 選項是獨立的。

請求無法執行。例如：

• 缺少 image_url。
• 圖片不是 JPG、JPEG、PNG 或 WebP 檔案。
• 圖片過小、超過 20 MB，或超過最大像素數。
• Meshy 無法下載該圖片，例如 URL 回傳 404 或逾時。
• Data URI 不是有效的 base64 編碼。
• 圖片被標記為 NSFW 內容。

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

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

以下情形之一適用：

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

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

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

達到以下其中一個限制：

• 你傳送的請求超出了速率限制允許的數量。請等待幾秒後重試。參見速率限制。
• 你有過多任務正在排隊或執行中。請等待部分任務完成後再重試。
• 在無限量方案下且積分已用盡時，你已達到可在無積分情況下執行的任務數量上限。請等待某個任務完成，或增加積分。

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

要構建的 prototype 任務的 ID。它必須是你的帳號使用 POST /openapi/creative-lab/fridge-magnet/v1/prototype 創建的任務，且狀態為 SUCCEEDED。

如果該 ID 不是你透過 API 創建的冰箱貼 prototype 任務（包括在網頁應用程式中創建的 prototype），將回傳 404。

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

當 Meshy 未從主體中描摹輪廓時，磁貼的外輪廓。當 remove_background 為 false，或者 Meshy 找不到主體的輪廓時，會使用此設定。

可用取值：

• circle
• rounded-rect
• hexagon
• shield
• star

磁貼外接正方形的邊長，單位為毫米，最大為 400。0 表示使用預設值。

浮雕高出底座的最大高度，單位為毫米，範圍從 0 到 20。

浮雕整體下壓的程度，單位為毫米，範圍從 0 到 20。Meshy 會在浮雕各處的高度上減去該值，直至底座。

浮雕背後平整底板的厚度，單位為毫米，範圍從 0 到 20。預設的 2 毫米底板能讓磁貼有足夠的厚度貼附在冰箱上，使浮雕不會顯得脆弱。

是否封閉磁貼的背面，即黏貼磁鐵的那一面。設為 false 會使背面保持中空，呈殼狀。

將深度圖數值映射為浮雕高度所用的曲線。

可用取值：

• linear
• gamma
• s-curve

曲線強度，最大為 10。gamma 和 s-curve 曲線會用到該值，linear 會忽略它。0 表示使用預設值。

是否反轉深度圖，使較暗的區域浮雕更高。

在 Meshy 構建浮雕之前對深度圖進行平滑處理的程度，範圍從 0 到 10。

在輪廓內以中心為基準縮放浮雕及其 texture 的程度，最大為 10。大於 1 的值會放大主體，小於 1 的值會縮小主體。它不會改變浮雕的高度。0 表示使用預設值。

低於此深度圖數值時，Meshy 會將深度設為零，範圍從 0 到 1。

是否從主體中描摹磁貼的輪廓，使磁貼形狀貼合主體。設為 false 則改用 badge_shape 輪廓。當 Meshy 找不到主體的輪廓時，也會使用 badge_shape。

這與 prototype 的 remove_background 參數是分開的，後者用於設定 prototype 圖像是否具有透明背景。

匯出模型的 mesh 解析度，範圍從 64 到 512。Meshy 基於 512 像素的深度圖構建 geometry，因此更精細的 mesh 只會增加面數而不會增加細節。0 表示使用預設值。

構建回傳的檔案格式。

可用取值：

• glb：一個 model.glb 檔案，位於 model_urls.glb
• obj：一個包含 model.obj、model.mtl 和 texture.png 的 zip 檔案，位於 model_urls.obj
• zip：一個包含 Meshy 生成的所有檔案的 zip 檔案，位於 model_urls.bundle_zip

請求無法運行。例如：

• input_task_id 缺失或不是有效的任務 ID。
• prototype 任務的狀態不是 SUCCEEDED。如果仍在運行，請等待後重試。如果已失敗或被取消，請創建一個新的 prototype 任務。
• prototype 任務已成功，但沒有圖像。請創建一個新的 prototype 任務。
• 某個 options 欄位超出其取值範圍，或不是可用取值。

錯誤資訊會說明發現了哪個問題。

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

以下情況之一適用：

• 帳號沒有足夠的積分。
• API 金鑰、工作區或成員達到了其積分限額。
• 帳號處於免費方案。

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

input_task_id 不匹配你的帳號透過 API 創建的任何冰箱貼 prototype 任務。在網頁應用程式中創建的 prototype 也會回傳 404。請傳送 prototype 創建回應中的 result ID。

達到以下限制之一：

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

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

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

你的團隊已啟用 IP Filtering，且 Meshy 將該 prototype 任務的圖片標記為涉及第三方智慧財產權。Build 任務以及 Enterprise 方案下的團隊不會出現此錯誤。請使用你擁有使用權的圖片建立 prototype 任務。

你的帳戶下沒有與該 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-fridge-magnet-prototype。

建立任務時發送的 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。請參閱 Errors。

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

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

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

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

您在建立任務時發送的 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。參閱 Errors。

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

模型檔案的下載連結，針對您所請求的 output.format 提供一個條目。在任務成功之前為 {}。