Creative Lab — 冰箱貼 API
將您的照片轉換為客製化冰箱貼——一個帶有平坦磁性背面、尺寸適合冰箱的圓角矩形彩色浮雕——分為兩個
階段:原型(prototype) 階段根據您輸入的照片生成彩色概念圖,然後 構建(build) 階段
將該概念圖轉換為浮雕 3D 模型。這兩個階段透過 input_task_id 關聯。
POST /openapi/creative-lab/fridge-magnet/v1/prototypePOST /openapi/creative-lab/fridge-magnet/v1/build
創建冰箱貼原型任務
根據來源照片生成一張單獨的彩色化概念圖。返回的任務 ID 就是你在呼叫構建
endpoint 時需要傳入的 input_task_id。有關回應格式,請參閱
冰箱貼原型任務物件。
參數
- 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
- remove_background
- Type
- boolean
- 預設值 false
- Description
當設定為
true時,原型圖像將以去除背景的透明 RGBA PNG 格式返回,方便你將主體合成到任意背景上。此參數僅控制此 endpoint 返回的圖像,與構建選項中同名參數(預設值為
true)無關,後者控制的是在浮雕化處理之前去除背景的行為。
返回值
回應中的 result 屬性包含新創建的冰箱貼原型任務的任務 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 字串格式不正確。
- 內容被標記:輸入圖片被 NSFW 或智慧財產權 moderation 標記。
- 缺少參數:
- Name
401 - Unauthorized- Description
身份驗證失敗。請檢查你的 API key。
- Name
402 - Payment Required- Description
credits 不足,無法執行此任務。
- Name
429 - Too Many Requests- Description
你已超出速率限制。
Request
# Stage 1: generate a colorized fridge magnet concept image
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_url": "<your publicly accessible image url or base64-encoded data URI>"
}'
Response
{
"result": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9"
}


建立冰箱貼建構任務
從已成功的原型任務生成可用於 3D 列印的最終冰箱貼。建構過程會在原型的彩色概念圖上執行深度圖浮雕流水線,並依你指定的格式輸出單一 mesh 產物。回應結構請參閱 冰箱貼建構任務物件。
參數
- Name
- input_task_id
- Type
- string
- 必選
- Description
透過同一 OpenAPI endpoint 建立的原型任務的任務 ID。該原型必須是使用相同的 API key 建立的,必須已達到
SUCCEEDED狀態,並且必須只生成了一張候選圖片。透過 webapp 建立的原型任務不被接受——建構 endpoint 只接受由
POST /openapi/creative-lab/fridge-magnet/v1/prototype生成的原型任務,其他來源一律回傳404。
- Name
- name
- Type
- string
- Description
用於顯示的可選任務名稱。最多 100 個字元。
options
浮雕 geometry 的可選調節參數。每個欄位都有合理的預設值——只需傳送你想要覆蓋的欄位即可。
- Name
- badge_shape
- Type
- string
- 預設值 rounded-rect
- Description
冰箱貼的外輪廓形狀。可選值:
circlerounded-rect(預設)hexagonshieldstar
- Name
- size_mm
- Type
- number
- 預設值 60
- Description
冰箱貼外接正方形的邊長,單位為毫米。範圍:
(0, 400]。
- Name
- relief_height_mm
- Type
- number
- 預設值 3.3
- Description
相對於底座的最大浮雕高度,單位為毫米。範圍:
[0, 20]。
- Name
- relief_offset_mm
- Type
- number
- 預設值 0
- Description
在擠出之前套用於浮雕的垂直偏移量,單位為毫米。範圍:
[0, 20]。
- Name
- base_thickness_mm
- Type
- number
- 預設值 2.0
- Description
浮雕背後平面底板的厚度,單位為毫米。冰箱貼的預設值是更厚實的 2 毫米底板——這能讓磁貼有足夠的強度吸附在冰箱上,同時不會使浮雕部分顯得脆弱。範圍:
[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 屬性包含新建立的冰箱貼建構任務的任務 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/fridge-magnet/v1/build \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
"options": {
"badge_shape": "rounded-rect",
"size_mm": 60,
"relief_height_mm": 3.3
},
"output": {
"format": "glb"
}
}'
Response
{
"result": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0"
}

取得冰箱貼任務
根據有效的任務 id 取得原型或建構任務。URL 路徑必須與任務所處的階段相符——透過
/prototype/:id 取得建構任務會回傳 404,反之亦然。
有關回應結構,請參閱冰箱貼原型任務物件 和冰箱貼建構任務物件。
參數
- Name
- id
- Type
- path
- Description
要取得的冰箱貼任務的唯一識別碼。
回傳值
回應包含冰箱貼任務物件。其結構取決於所請求的階段。
Request
# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# Build
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Prototype Response
{
"id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
"type": "creative-lab-fridge-magnet-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729543210000,
"started_at": 1729543215000,
"finished_at": 1729543242000,
"expires_at": 1729802442000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
Build Response
{
"id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
"type": "creative-lab-fridge-magnet-build",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729543250000,
"started_at": 1729543258000,
"finished_at": 1729543285000,
"expires_at": 1729802485000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
}
}
刪除冰箱貼任務
取消一個冰箱貼任務。如果任務仍處於 PENDING 狀態,建立時消耗的
credits 將被退還。已處於 IN_PROGRESS 狀態的任務將被取消,但不予退款(此時
worker 可能已經在消耗資源)。已經到達終止狀態
(SUCCEEDED、FAILED、CANCELED)的任務無法被取消。
URL 路徑必須與任務所處的階段相符 —— 對
/prototype/:buildId 執行 DELETE 操作會回傳 404。
路徑參數
- Name
- id
- Type
- path
- Description
要取消的冰箱貼任務的唯一識別碼。
回傳值
成功時回傳 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/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// Returns 204 No Content on success (empty body).
流式取得冰箱貼任務
透過 Server-Sent Events (SSE) 以串流方式取得冰箱貼任務的即時更新。
URL 路徑必須與任務所處階段相符 —— 在
/prototype/:buildId/stream 開啟串流會發出一則 status_code: 404 的
event: error 負載,並隨後關閉該串流。
參數
- Name
- id
- Type
- path
- Description
要串流取得的冰箱貼任務的唯一識別碼。
回傳
以 Server-Sent Events 的形式回傳一個由
冰箱貼原型
或 冰箱貼構建任務物件組成的串流。
每一幀都攜帶該階段完整的任務物件 —— 與 Get endpoint 回傳的結構相同 —— 因此當任務處於
PENDING 或 IN_PROGRESS 狀態時,輸出欄位只是尚未被填入(為 null、[] 或 {}),
且 finished_at 為 null。
Request
curl -N https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/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": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
"type": "creative-lab-fridge-magnet-build",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729543250000,
"started_at": 1729543258000,
"finished_at": 1729543285000,
"expires_at": 1729802485000,
"task_error": null,
"consumed_credits": 20,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
}
}
列出冰箱貼任務
取得單一階段之冰箱貼任務的分頁列表。URL 路徑決定所選階段——/prototype 回傳原型任務;/build
回傳成品任務。兩種回應都不會包含另一階段的任務。
路徑參數
- Name
- stage
- Type
- path
- 必選
- Description
prototype或build二者之一。該集合僅回傳階段與 URL 相符的任務——請求/prototype永遠不會回傳 成品任務,反之亦然。
查詢參數
- 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 時回傳
冰箱貼原型任務物件,
列出 /build 時回傳
冰箱貼成品任務物件。
Request
# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response (List Prototype Tasks)
[
{
"id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
"type": "creative-lab-fridge-magnet-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729543210000,
"started_at": 1729543215000,
"finished_at": 1729543242000,
"expires_at": 1729802442000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 6,
"image_urls": [
"https://assets.meshy.ai/***/concept.png?Expires=***"
]
}
]
Fridge Magnet 原型任務物件
Fridge Magnet 原型任務物件是 Meshy 追蹤的一個工作單元,用於從來源照片產生一張彩色概念圖(concept image)。此階段的輸出會透過 input_task_id 連結到構建階段。
屬性
- Name
- id
- Type
- string
- Description
任務的唯一識別碼。雖然我們在實作細節上使用 k-可排序的 UUID 作為任務 id,但你不應對 id 的格式做任何假設。
- Name
- type
- Type
- string
- Description
任務的類型。取值為
creative-lab-fridge-magnet-prototype。
- 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
任務建立時的時間戳,單位為毫秒。
時間戳表示自 1970 年 1 月 1 日 UTC 起經過的毫秒數,遵循 RFC 3339
標準。 例如,2023 年 9 月 1 日星期五 GMT 時間 12:00:00 PM 表示為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 Fridge Magnet Prototype Task Object
{
"id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
"type": "creative-lab-fridge-magnet-prototype",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729543210000,
"started_at": 1729543215000,
"finished_at": 1729543242000,
"expires_at": 1729802442000,
"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-fridge-magnet-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物件的完整參考,請參閱錯誤。
- 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 Fridge Magnet Build Task Object
{
"id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
"type": "creative-lab-fridge-magnet-build",
"name": "",
"status": "SUCCEEDED",
"progress": 100,
"created_at": 1729543250000,
"started_at": 1729543258000,
"finished_at": 1729543285000,
"expires_at": 1729802485000,
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
}
}