Creative Lab Keychain API

要轉換為鑰匙扣概念圖的照片，可以是公開 URL 或 data URI（data:image/jpeg;base64,<your base64-encoded image data>）。

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

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

它用於在你的 dashboard 和任務清單中標記該任務，不會出現在鑰匙扣上。如果要在鑰匙扣上顯示名稱，請使用 name_text。

要加到鑰匙扣上的名稱，例如寵物或人的名字，最多 10 個字元。Meshy 按字元計數，而非按位元組，因此一個 10 字元的中文、日文或韓文名字也能放得下。超長的名稱會回傳 400。留空則生成不帶名稱的鑰匙扣。

該名稱會以扁平的彩色細節形式出現在鑰匙扣正面，而不是凸起或鏤空的文字。

Meshy 會修剪前後空白並移除不可見的格式字元。prototype 任務物件會以 name_text 回傳結果，因此你可以在為建構付費之前檢查該文字。

Meshy 在 prototype 階段加入名稱。建構會保留它，並忽略傳送給建構 endpoint 的 name_text。

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

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

請求無法執行。例如：

• 缺少 image_url。
• 圖片不是 JPG、JPEG、PNG 或 WebP 檔案。
• 圖片過小、超過 20 MB，或超過最大像素數。
• Meshy 無法下載該圖片，例如 URL 回傳 404 或逾時。
• data URI 不是有效的 base64。
• name_text 超過 10 個字元。Meshy 會拒絕該請求而非自動截短，也不會為此請求計費。
• 圖片或 name_text 被標記為 NSFW。

錯誤訊息會說明發現了哪個問題。修正請求後重新傳送。

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

符合以下情形之一：

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

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

你的團隊開啟了 IP Filtering，且 Meshy 將該圖片標記為涉及第三方知識產權。請傳送你擁有使用權的圖片。Meshy 只檢查圖片的知識產權問題，不檢查 name_text。

達到以下某個限制：

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

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

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

如果 ID 不是你透過 API 創建的 Keychain prototype 任務之一（包括在 web app 中創建的 prototype），將回傳 404。

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

當 Meshy 沒有從主體描繪出輪廓時，keychain 使用的外形輪廓。當 remove_background 為 false，或者 Meshy 無法找到主體的輪廓時，會使用該欄位。

可用值：

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

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

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

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

浮雕背後平整底板的厚度，單位為毫米，範圍從 0 到 20。

是否封閉 keychain 的背面。false 會讓背面保持開放，呈殼狀。

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

可用值：

• linear
• gamma
• s-curve

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

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

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

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

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

是否從主體描繪出 keychain 的輪廓，使 keychain 貼合主體的形狀。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 key 缺失或無效。請檢查 Authorization 請求標頭。

以下情形之一適用：

• 帳戶的積分不足。
• API key、workspace 或成員已達到其積分限額。
• 帳戶處於免費方案。

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

input_task_id 不符合你的帳戶透過 API 創建的任何 Keychain prototype 任務。在 web app 中創建的 prototype 也會回傳 404。請傳送來自 prototype 創建回應中的 result ID。

達到了以下限制之一：

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

建立回應中的任務 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 的 Keychain 任務，或者任務所處的階段與路徑不符。請檢查該 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-keychain-prototype。

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

Meshy 為鑰匙扣新增的名稱，已去除首尾空白並移除不可見的格式字元。如果你沒有傳送 name_text，則不會包含此欄位。要檢查你的 HTTP 用戶端是否正確編碼了文字，可將其與你傳送的內容進行比對。

任務的狀態。

可用取值：

• 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。任務成功後，該陣列包含一個 URL；在此之前為空陣列。

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

任務類型，始終為 creative-lab-keychain-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。參見 Errors。

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

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