Creative Lab — 鑰匙扣 API
將一張來源照片轉換為可 3D 列印的鑰匙扣掛飾——一種徽章造型的彩色浮雕——分為兩個階段完成：prototype（原型） 階段會根據你輸入的照片產生一張彩色概念圖，接著 build（構建） 階段會將該概念圖轉換為浮雕 3D 模型。這兩個階段透過 input_task_id 相互關聯。
POST /openapi/creative-lab/keychain/v1/prototypePOST /openapi/creative-lab/keychain/v1/build
建立 Keychain 原型任務
根據來源照片產生單張彩色概念圖像。回傳的任務 ID 即是你在呼叫構建 endpoint 時需要傳入的 input_task_id。回應結構請參見
Keychain 原型任務物件。
參數
- Name
- image_url
- Type
- string
- 必選
- Description
供 Meshy 上色以產生可用於鑰匙扣的概念圖像的來源照片。目前支援
.jpg、.jpeg、.png和.webp格式。提供圖像的方式有兩種：
- 公開可存取的 URL：可從公共網際網路存取的 URL。
- Data URI：圖像的 base64 編碼 data URI。data URI 範例：
data:image/jpeg;base64,<your base64-encoded image data>。
- Name
- name
- Type
- string
- Description
可選的任務名稱，用於展示。最多 100 個字元。
該名稱用於在你的控制台和任務列表中標記該任務，不會被刻印到鑰匙扣上——如需刻印文字，請使用
name_text。
- Name
- name_text
- Type
- string
- Description
要刻印在鑰匙扣上的文字，例如寵物或人的名字。最多 10 個字元，按 Unicode 字元而非位元組計數，因此可以接受一個 10 個字元的中文、日文或韓文名字。若省略該欄位，則產生的鑰匙扣不帶任何刻印。
使用前會去除首尾空白字元，並移除不可見的格式字元。處理後的值會作為
name_text回傳在原型任務物件中，因此你可以在為構建階段付費之前，確認最終將被刻印的確切內容。刻印是在此原型階段完成的。構建階段會自動繼承該刻印，且不接受自己的
name_text。當文字不是純 ASCII 字元時，請以 UTF-8 編碼傳送請求體，並設定
Content-Type: application/json; charset=utf-8。部分 HTTP 客戶端——包括 Windows PowerShell 的Invoke-RestMethod——預設會以 ISO-8859-1 編碼請求體，這會在資料到達 Meshy 之前，將所有非拉丁字元悄悄替換為?。API 無法區分這種情況與你確實想要的刻印內容。
- Name
- remove_background
- Type
- boolean
- 預設值 false
- Description
設為
true時，回傳的原型圖像將是去除背景的透明 RGBA PNG，方便你將主體合成到任意背景上。此選項僅控制該 endpoint 回傳的圖像，與同名的構建選項（預設值為
true，用於控制在浮雕處理前是否去除背景）相互獨立。
回傳值
回應中的 result 屬性包含新建立的 keychain 原型任務的 id。請輪詢取得任務 endpoint，或訂閱串流介面，直到任務狀態變為 SUCCEEDED，然後將該 ID 作為 input_task_id 傳遞給構建 endpoint。
失敗模式
- Name
400 - Bad Request- Description
請求無法被接受。常見原因包括：
- 缺少參數：
image_url為必填項。 - 圖像格式無效：提供的
image_url不是受支援的格式（.jpg、.jpeg、.png、.webp）。 - 圖像尺寸超出範圍：圖像過小、超過最大檔案大小限制，或超過最大像素數限制。
- URL 無法存取：無法下載
image_url（404 或 timeout）。 - Data URI 無效：base64 字串格式有誤。
- 刻印文字過長：
name_text超過 10 個字元。此類請求會被直接拒絕而非截斷處理，因此你不會因刻印了被截短名字的鑰匙扣而被扣款。 - 內容被標記：輸入圖像被 NSFW 或智慧財產權 moderation 標記，或
name_text刻印內容被 NSFW moderation 標記。刻印文字僅會進行 NSFW 內容審查——智慧財產權審查僅適用於圖像。
- 缺少參數：
- Name
401 - Unauthorized- Description
Authentication 失敗。請檢查你的 API key。
- Name
402 - Payment Required- Description
credits 不足，無法執行此任務。
- Name
429 - Too Many Requests- Description
你已超出速率限制。
Request
# Stage 1: generate a colorized keychain concept image
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json; charset=utf-8' \
-d '{
"image_url": "<your publicly accessible image url or base64-encoded data URI>",
"name_text": "Luna"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
建立 Keychain 建構任務
從一個已成功的原型任務生成最終可用於 3D 列印的 keychain 徽章。建構過程會對原型的彩色概念圖執行深度圖浮雕（depth-map relief）流水線，並依你所要求的格式輸出單一 mesh 產物。回應結構請參見 Keychain 建構任務物件。
參數
- Name
- input_task_id
- Type
- string
- 必選
- Description
透過同一個 OpenAPI endpoint 建立的原型任務的任務 ID。該原型必須使用相同的 API key 建立，必須已達到
SUCCEEDED狀態，並且必須恰好生成了一張候選圖片。透過 webapp 建立的原型任務不被接受——建構 endpoint 只接受由
POST /openapi/creative-lab/keychain/v1/prototype生成的原型任務，其他來源一律回傳404拒絕。
- Name
- name
- Type
- string
- Description
可選的任務名稱，用於顯示。最多 100 個字元。
options
浮雕 geometry 的可選調整參數。每個欄位都有合理的預設值——只需傳送你想覆寫的欄位。
- Name
- badge_shape
- Type
- string
- 預設值 circle
- Description
keychain 徽章的外輪廓形狀。可選值：
circle（預設）rounded-recthexagonshieldstar
- Name
- size_mm
- Type
- number
- 預設值 40
- Description
keychain 的外接正方形邊長，單位為毫米。範圍：
(0, 400]。
- Name
- relief_height_mm
- Type
- number
- 預設值 2.2
- Description
浮雕相對於底面的最大高度，單位為毫米。範圍：
[0, 20]。
- Name
- relief_offset_mm
- Type
- number
- 預設值 0
- Description
在擠出之前套用於浮雕的垂直偏移量，單位為毫米。範圍：
[0, 20]。
- Name
- base_thickness_mm
- Type
- number
- 預設值 0.1
- Description
浮雕背面平整底板的厚度，單位為毫米。範圍：
[0, 20]。
- Name
- has_closed_back
- Type
- boolean
- 預設值 true
- Description
徽章背面是否封閉為一個密閉表面。設為
false則為開放式外殼。
- Name
- relief_curve
- Type
- string
- 預設值 linear
- Description
將深度圖數值對應到浮雕高度的轉換曲線。可選值：
linear（預設）gammas-curve
- Name
- curve_param
- Type
- number
- 預設值 1.0
- Description
轉換曲線的形狀參數（僅當
relief_curve為gamma時有意義）。範圍：(0, 10]。
- Name
- invert_depth
- Type
- boolean
- 預設值 false
- Description
反轉深度圖的解讀方式，使較暗區域產生更高的浮雕。
- Name
- smoothing
- Type
- number
- 預設值 0.24
- Description
在擷取浮雕之前套用於深度圖的平滑強度。範圍：
[0, 10]。
- Name
- relief_scale
- Type
- number
- 預設值 1.0
- Description
在
relief_height_mm基礎上疊加的垂直縮放倍數。範圍：(0, 10]。
- Name
- depth_threshold
- Type
- number
- 預設值 0.1
- Description
深度圖數值的低通閾值；低於該值的部分將被截斷為零。範圍：
[0, 1]。
- Name
- remove_background
- Type
- boolean
- 預設值 true
- Description
在生成浮雕之前，自動移除原型概念圖的背景。
這與原型任務中同名參數（預設
false）是分開的，後者控制的是原型圖片本身是否以透明背景形式回傳。
- Name
- export_resolution
- Type
- integer
- 預設值 512
- Description
匯出時使用的 mesh 解析度。範圍：
[64, 2048]。
output
可選的輸出格式選擇器。預設值為 glb。
- Name
- format
- Type
- string
- 預設值 glb
- Description
建構回傳的產物包。可選值：
glb（預設）——在model_urls.glb下回傳單一model.glb。obj——將model.obj+model.mtl+texture.png打包為 zip，並在model_urls.obj下回傳該包。zip——將產生器產出的所有產物打包為 zip，並在model_urls.bundle_zip下回傳該包。
回傳值
回應中的 result 屬性包含新建立的 keychain 建構任務的任務 id。輪詢 取得任務 endpoint 或訂閱 串流介面，直到任務達到 SUCCEEDED 狀態，然後從 model_urls 中唯一的項目下載產物。
失敗模式
- Name
400 - Bad Request- Description
請求不可接受。常見原因：
- 缺少參數：
input_task_id是必需的。 - UUID 無效：
input_task_id不是有效的 UUID。 - 父任務未成功：所引用的原型任務尚未達到
SUCCEEDED狀態。 - 無候選圖：原型任務成功了，但未生成候選圖片。
- 選項超出範圍：
options中的某個欄位超出了其允許的範圍或列舉集合。
- 缺少參數：
- Name
401 - Unauthorized- Description
身分驗證失敗。請檢查你的 API key。
- Name
402 - Payment Required- Description
credits 不足，無法執行此任務。
- Name
404 - Not Found- Description
所引用的原型任務不存在、屬於其他使用者，或是透過 webapp 建立的（只有 API 模式下建立的原型任務才能連結到建構任務）。
- Name
429 - Too Many Requests- Description
你已超出速率限制。
Request
# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"options": {
"badge_shape": "circle",
"size_mm": 40,
"relief_height_mm": 2.5
},
"output": {
"format": "glb"
}
}'
Response
{
"result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}
取得 Keychain 任務
根據有效的任務 id 取得原型（prototype）或建構（build）任務。URL 路徑
必須與任務所處的階段一致——透過
/prototype/:id 取得建構任務將回傳 404，反之亦然。
有關回應結構，請參閲 Keychain 原型任務物件 和 Keychain 建構任務物件。
參數
- Name
- id
- Type
- path
- Description
要取得的 keychain 任務的唯一識別碼。
回傳
回應包含 keychain 任務物件。其具體結構取決於所請求的階段。
Request
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# Build
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Prototype Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-keychain-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123456000,
"started_at": 1729123460000,
"finished_at": 1729123486000,
"expires_at": 1729382686000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
Build Response
{
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"type": "creative-lab-keychain-build",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123500000,
"started_at": 1729123510000,
"finished_at": 1729123535000,
"expires_at": 1729382735000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
}
}
刪除 Keychain 任務
取消一個 keychain 任務。如果任務仍處於 PENDING 狀態，建立時消耗的
積分將被退還。已經處於 IN_PROGRESS 狀態的任務會被取消但不會退款
（worker 可能已經在消耗資源）。已經達到終止狀態
（SUCCEEDED、FAILED、CANCELED）的任務無法被取消。
URL 路徑必須與任務所處的階段相匹配 —— 對
/prototype/:buildId 執行 DELETE 將回傳 404。
路徑參數
- Name
- id
- Type
- path
- Description
要取消的 keychain 任務的唯一識別碼。
回傳
成功時回傳 204 No Content，回應內容為空。
失敗模式
- Name
400 - Bad Request- Description
該任務已處於終止狀態，無法被取消。
- Name
404 - Not Found- Description
該任務不存在、屬於其他使用者，或其所處階段與 URL 路徑不匹配。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// Returns 204 No Content on success (empty body).
以串流方式取得 Keychain 任務
透過 Server-Sent Events（SSE）以串流方式取得 keychain 任務的即時更新。
URL 路徑必須與任務所處的階段相符 —— 若在
/prototype/:buildId/stream 上開啟串流，會發出一則 status_code: 404 的
event: error 請求體並關閉該串流。
參數
- Name
- id
- Type
- path
- Description
要進行串流取得的 keychain 任務的唯一識別碼。
回傳
以 Server-Sent Events 的形式回傳一系列
Keychain Prototype 或
Keychain Build 任務物件。每一幀都會攜帶該階段的完整任務物件 —— 與
Get endpoint 回傳的形狀相同 —— 因此當任務處於 PENDING 或 IN_PROGRESS 狀態時，
輸出欄位只是尚未被填入內容（為 null、[] 或 {}），且
finished_at 為 null。
Request
curl -N https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response Stream
// Error event example (wrong stage or task not found)
event: error
data: {
"status_code": 404,
"message": "Task not found"
}
// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"type": "creative-lab-keychain-build",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123500000,
"started_at": 1729123510000,
"finished_at": 1729123535000,
"expires_at": 1729382735000,
"task_error": null,
"consumed_credits": 20,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
}
}
列出 Keychain 任務
取得單一階段的 keychain 任務的分頁清單。URL 路徑決定階段——/prototype 回傳原型（prototype）任務；
/build 回傳構建（build）任務。另一個階段的任務不會包含在任一回應中。
路徑參數
- Name
- stage
- Type
- path
- 必選
- Description
prototype或build二選一。此集合僅回傳階段與 URL 相符的任務—— 請求/prototype永遠不會回傳 build 任務，反之亦然。
查詢參數
- Name
- page_num
- Type
- integer
- 預設值 1
- Description
用於分頁的頁碼。
- Name
- page_size
- Type
- integer
- 預設值 10
- Description
每頁項目數上限。允許的最大值為
100筆。
- Name
- sort_by
- Type
- string
- 預設值 -created_at
- Description
用於排序的欄位。可用值：
+created_at：依建立時間升冪排序。-created_at：依建立時間降冪排序。
回傳值
回傳該階段對應任務物件的分頁清單——列出 /prototype 時回傳
keychain 原型任務物件，
列出 /build 時回傳
keychain 構建任務物件。
Request
# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response (List Prototype Tasks)
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-keychain-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123456000,
"started_at": 1729123460000,
"finished_at": 1729123486000,
"expires_at": 1729382686000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
]
Keychain Prototype 任務物件
Keychain Prototype 任務物件是 Meshy 用於追蹤的一個工作單元，用於從來源照片產生彩色的概念圖像。該階段的輸出會透過 input_task_id 連結到建構階段。
屬性
- Name
- id
- Type
- string
- Description
任務的唯一識別碼。雖然我們在實作細節上使用 k-可排序的 UUID 作為任務 id，但你不應該對 id 的格式做任何假設。
- Name
- type
- Type
- string
- Description
任務的類型。此值為
creative-lab-keychain-prototype。
- Name
- name
- Type
- string
- Description
建立任務時提供的任務名稱。如果未提供名稱，則為空字串。
- Name
- name_text
- Type
- string
- Description
套用於此鑰匙扣的刻字內容，經過修剪並去除不可見格式字元後的結果。如果建立任務時未提供
name_text，則該欄位不存在。你可以將其與你傳送的內容進行比對，以確認文字在你的 HTTP 用戶端編碼過程中未被破壞。
- Name
- status
- Type
- string
- Description
任務的狀態。可能的值為
PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED之一。
- Name
- progress
- Type
- integer
- Description
任務的 progress。如果任務尚未開始，此屬性將為
0。一旦任務成功，此值將變為100。
- Name
- created_at
- Type
- timestamp
- Description
任務建立時的時間戳，單位為毫秒。
時間戳表示自 1970 年 1 月 1 日 UTC 起經過的毫秒數，遵循 RFC 3339 標準。 例如，2023 年 9 月 1 日星期五格林威治標準時間下午 12:00:00 表示為
1693569600000。這適用於 Meshy API 中的所有時間戳。
- Name
- started_at
- Type
- timestamp
- Description
任務開始時的時間戳，單位為毫秒。如果任務尚未開始，此屬性將為
0。
- Name
- finished_at
- Type
- timestamp
- Description
任務完成時的時間戳，單位為毫秒。如果任務尚未完成，此屬性將為
0。
- Name
- expires_at
- Type
- timestamp
- Description
任務結果過期時的時間戳，單位為毫秒。
- Name
- preceding_tasks
- Type
- integer
- Description
排在前面的任務數量。
僅當任務狀態為
PENDING時，此欄位的值才有意義。
- Name
- task_error
- Type
- object
- Description
失敗任務的錯誤詳情。有關完整的
task_error物件參考，請參閱錯誤。
- Name
- consumed_credits
- Type
- integer
- Description
此任務消耗的積分數量。當任務狀態為
PENDING、IN_PROGRESS或SUCCEEDED時會顯示此值。對於FAILED的任務，此值傳回0（失敗時積分會被退還）。
- Name
- image_urls
- Type
- array of strings
- Description
此原型任務產生的概念圖像候選項之可下載 URL。目前 API 始終只傳回一個候選項；該欄位設計為陣列，是為了讓未來版本能夠在不產生破壞性變更的情況下提供多個候選項。
Example Keychain Prototype Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "creative-lab-keychain-prototype",
"name": "",
"name_text": "Luna",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123456000,
"started_at": 1729123460000,
"finished_at": 1729123486000,
"expires_at": 1729382686000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
鑰匙扣構建任務物件
鑰匙扣構建任務物件是 Meshy 追蹤的一個工作單元，用於從已成功的原型任務生成最終的 3D 鑰匙扣網格。構建過程會對原型的概念圖運行深度圖浮雕流水線，並依照呼叫方要求的格式發布單一網格產物。
屬性
- Name
- id
- Type
- string
- Description
任務的唯一識別碼。
- Name
- type
- Type
- string
- Description
任務的類型。值為
creative-lab-keychain-build。
- Name
- name
- Type
- string
- Description
建立任務時提供的任務名稱。如果未提供名稱，則為空字串。
- Name
- status
- Type
- string
- Description
任務的狀態。可能的值為
PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED之一。
- Name
- progress
- Type
- integer
- Description
任務的進度。如果任務尚未開始，此屬性將為
0。任務成功後，此值將變為100。
- Name
- created_at
- Type
- timestamp
- Description
任務建立時的時間戳，單位為毫秒。
- Name
- started_at
- Type
- timestamp
- Description
任務開始時的時間戳，單位為毫秒。
- Name
- finished_at
- Type
- timestamp
- Description
任務完成時的時間戳，單位為毫秒。
- Name
- expires_at
- Type
- timestamp
- Description
任務結果過期時的時間戳，單位為毫秒。
- Name
- preceding_tasks
- Type
- integer
- Description
排在前面的任務數量。僅當狀態為
PENDING時才有意義。
- Name
- task_error
- Type
- object
- Description
失敗任務的錯誤詳情。完整的
task_error物件參考請見 Errors。
- Name
- consumed_credits
- Type
- integer
- Description
此任務消耗的積分數量。對於
FAILED任務，回傳0（失敗時會退還積分）。
- Name
- model_urls
- Type
- object
- Description
生成產物的可下載 URL，以產物名稱作為鍵。始終恰好包含一個項目——即透過構建請求的
output.format所指定的格式。該鍵與所請求的格式相匹配：- Name
glb- Type
- string
- Description
GLB 檔案的可下載 URL。當
output.format為glb（預設值）時存在。
- Name
obj- Type
- string
- Description
指向包含
model.obj、model.mtl和texture.png的 zip 壓縮包的可下載 URL。當output.format為obj時存在。
- Name
bundle_zip- Type
- string
- Description
指向生成器輸出的所有產物的 zip 壓縮包的可下載 URL。當
output.format為zip時存在。
Example Keychain Build Task Object
{
"id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
"type": "creative-lab-keychain-build",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729123500000,
"started_at": 1729123510000,
"finished_at": 1729123535000,
"expires_at": 1729382735000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
}
}