Creative Lab 鍵帽 API

要轉換為鍵帽設計的照片，可以是公開可存取的 URL，或是一個 data URI（data:image/jpeg;base64,<your base64-encoded image data>）。

圖片必須是 JPG、JPEG、PNG 或 WebP 檔案，且不超過 20 MB（20,000,000 位元組）。每條邊至少為 32 像素，圖片總像素數最多為 178,956,970。超出這些限制的圖片會回傳 400。

Meshy 會根據圖像資料來偵測格式，而非依據 URL 中的副檔名。沒有副檔名的 URL 也可以正常運作，且 Meshy 會跟隨 HTTP 重新導向。Meshy 會套用 EXIF 方向資訊，因此旋轉過的手機照片會依照其實際顯示的方向呈現。

data URI 必須使用 base64 編碼，並帶有圖像類型，例如 data:image/png;base64,...，且解碼後的圖像必須是 JPEG、PNG 或 WebP 格式。20 MB 的限制適用於解碼後的圖像，因此 base64 文字本身可能會大約再大三分之一。

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

是否從 prototype 圖像中移除背景。設為 true 會回傳一張透明的 RGBA PNG，這樣你就可以將鍵帽放置在任意背景之上。如果 Meshy 無法移除背景，它會回傳帶有原背景的圖像，任務仍然會成功。

無論如何，build 階段用於生成 3D 效果的頭部設計都會保留其背景。build 階段會根據 image_urls 中的圖像來繪製鍵帽底座，如果你傳送了 true，則不帶其背景。build 階段會將該圖像以 process_image_urls.composite 的形式回傳。

請求無法執行。例如：

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

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

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

以下情況之一適用：

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

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

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

已達到以下限制之一：

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

Meshy 遇到了伺服器錯誤，例如由於內容審核（moderation）或智慧財產權檢查未能執行，或 Meshy 無法儲存該圖像。Meshy 不會建立該任務，並會退還其已扣除的任何積分。請重試該請求。

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

如果 ID 不是你透過 API 創建的 Keycap prototype 任務之一，將返回 404，這也包括在網頁應用程式中創建的 prototype。

要建構的候選項，來自 prototype 任務的 candidate_ids 陣列。如果值不在該陣列中，將返回 400。

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

用於建構的 keycap 底座。目前唯一可用的值是 cherry-mx-1x1-r1，即標準的 Cherry MX profile 1u keycap。不支援自訂尺寸，其他任何值都會返回 400。

頭部沿其最長維度的尺寸，單位為毫米，範圍為 10 到 40。Meshy 會縮放頭部，使其最長維度與該值匹配。超出範圍的值將返回 400。

當值大於約 32.9 時，Meshy 可能會縮小尺寸，以使頭部符合底座的保護性占用面積限制。此時頭部生成的結果可能會比你要求的更小。任務物件不會返回 Meshy 實際套用的尺寸。要檢查該尺寸，請測量模型中 keycap-head mesh 的包圍盒。

在 Meshy 將頭部嵌入底座之前對其施加的垂直偏移量，單位為毫米，範圍為 -5 到 5。超出範圍的值將返回 400。

請求無法執行。例如：

• input_task_id 缺失或不是有效的任務 ID。
• prototype 任務的狀態不是 SUCCEEDED。如果仍在執行，請等待後重試。如果已失敗或被取消，請創建一個新的 prototype 任務。
• prototype 任務成功了，但沒有候選項。請創建一個新的 prototype 任務。
• candidate_id 缺失，或不在 prototype 任務的 candidate_ids 中。請從該陣列中傳送一個值。
• options 中的某個欄位超出範圍，或 base_model 不是可用的值。

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

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

以下情況之一適用：

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

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

input_task_id 與你的帳戶透過 API 創建的任何 Keycap prototype 任務都不匹配。在網頁應用程式中創建的 prototype 同樣會返回 404。請傳送來自 prototype 創建回應中的 result ID。

達到以下限制之一：

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

由於伺服器錯誤，Meshy 無法創建任務。Meshy 會退還其已扣除的所有積分。請重試該請求。

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

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

你的團隊已開啟 IP Filtering，並且 Meshy 偵測到該 prototype 任務的圖片涉及第三方智慧財產權問題。Build 任務以及 Enterprise 方案團隊不會遇到此錯誤。請使用你擁有使用權的圖片來建立 prototype 任務。

你的帳戶下沒有該 ID 對應的 Keycap 任務，或者該任務所處的階段與路徑不符。請檢查 ID，並使用 /prototype 或 /build 來對應正確的任務。

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

要取消的任務的 ID。

以下情況之一適用：

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

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

Meshy 在取消任務時遇到了伺服器錯誤，因此該任務可能已取消，也可能未取消。請先取得任務以檢查其 status，然後再重試。

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

要列出的階段，prototype 或 build。

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

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

排序方式。

可用值：

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

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

任務類型，恆為 creative-lab-keycap-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 結果的 Enterprise 帳戶，該時間約為 100 年之後。另見資產保留期。

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

任務失敗的原因。除非 status 為 FAILED，否則為 null。另見 Errors。

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

成品鍵帽圖像的下載 URL。任務成功後，該陣列包含一個 URL；在此之前為空陣列。image_urls[i] 展示的是 candidate_ids[i] 所對應的候選結果。

這些 URL 僅用於展示。build endpoint 接收的是 candidate_ids 中的某個條目，而不是 URL。這些是簽名 URL，取得時無需攜帶 Authorization 請求標頭。它們在 expires_at 之前始終有效，並且再次取得該任務會回傳相同的 URL。

候選結果的 ID，順序與 image_urls 相同。要建構某個候選結果，請在 build 請求中將其 ID 作為 candidate_id 傳送。請勿依賴這些 ID 的具體格式。

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

任務類型，始終為 creative-lab-keycap-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 無法讀取扣費資訊，get 或 stream 回應會省略該欄位，而 list 請求會回傳 500。遇到這種情況，請重試該請求。

3D 模型的下載 URL。Meshy 匯出的 GLB 檔案和 OBJ 包按真實世界比例（以毫米為單位）、Y 軸朝上，鍵帽正面朝向 +Z 方向。

該模型包含名為 keycap-head 和 keycap-base 的網格。當 Meshy 回退為底座使用圖案填充時，模型還會包含一個用於軸芯凹腔的 keycap-base-interior 網格。請勿假設模型一定只有兩個網格。

這些是簽名 URL，因此擷取時無需攜帶 Authorization 請求標頭。它們在 expires_at 之前保持有效，在此之前再次擷取該任務會回傳相同的 URL。過期的 URL 無法續期，因此請在到期前下載並儲存檔案。

建構過程各步驟產生圖片的下載 URL，按類型進行鍵值索引。與 model_urls 一樣，它們也是簽名 URL，因此擷取時無需攜帶 Authorization 請求標頭。它們在 expires_at 之前保持有效，再次擷取該任務會回傳相同的 URL。

它可能包含以下鍵：

• head_design：所選候選項的設計圖像，建構任務據此產生 3D 內容。始終存在。
• composite：所選候選項完成後的鍵帽圖像，底座正是根據它繪製而成。可能缺失。
• base_canvas：繪製完成的鍵帽底座。可能缺失。

Meshy 可能會新增鍵，因此遇到不認識的鍵請直接忽略。