浮雕 API
將一張照片轉換為淺浮雕 3D 模型與 16 位元深度圖，適用於 3D 列印、雷射雕刻與 CNC 雕刻。
建立 Relief 任務
建立一個 Relief 任務。該任務會將照片轉換為浮雕模型。任務成功後，會產生 GLB 檔案和 STL 檔案格式的模型、16 位元灰階深度圖以及預覽圖像。如果只想取得深度圖，請將 should_generate_model 設定為 false。
該任務在背景執行。
Relief 任務不能作為其他 endpoint（例如 Remesh、Convert 或 Auto Split）的輸入。此類請求會回傳 403。
Request
# Simple request: a low relief, 60 mm on its longer side
curl https://api.meshy.ai/openapi/v1/relief \
-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>"
}'
# Advanced request: a deep 120 mm relief with a thicker base, curved from side to side
curl https://api.meshy.ai/openapi/v1/relief \
-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>",
"variant": "high",
"size_mm": 120,
"carving_depth_mm": 10,
"base_thickness_mm": 3,
"bend_mode": "convex",
"bend_angle": 90
}'
Response
{
"result": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20"
}
參數
- Name
- image_url
- Type
- string
- 必選
- Description
要轉換為浮雕的照片，可以是公開可存取的 URL，或 data URI（
data:image/png;base64,...）。圖片必須是 JPG、JPEG、PNG 或 WebP 檔案，大小不超過 20 MB，且尺寸至少為 32 × 32 像素。其長邊最多約為短邊的 16 倍。不符合要求的圖片會回傳
400。Meshy 會在產生浮雕前將透明區域填滿為黑色。
- Name
- variant
- Type
- string
- 預設值 low
- Description
浮雕樣式。它決定深度圖的形狀，並設定預設的
carving_depth_mm。可用值：
high：雕刻更深，適用於 3D 列印件。low：雕刻較淺，適用於雷射雕刻、CNC 雕刻和薄匾牌。
傳送
null或""與不傳該參數效果相同。其他任何值都會回傳400。
- Name
- should_generate_model
- Type
- boolean
- 預設值 true
- Description
是否建構浮雕模型。設定為
false可得到僅含深度圖的任務，不產生模型和預覽圖像。Meshy 仍會檢查尺寸、雕刻、底座、彎曲和解析度等參數，但不會使用它們。此設定不會改變積分花費。
- Name
- size_mm
- Type
- number
- 預設值 60
- Description
照片長邊在模型上的長度（在任何彎曲之前以平展狀態測量），範圍為
20到250毫米。啟用remove_base後，模型可以更小。
- Name
- carving_mode
- Type
- string
- 預設值 emboss
- Description
主體是凸出於底板，還是被刻入底板。
可用值：
emboss：照片中距離較近的部分凸出。engrave：深度被反轉，距離較近的部分被刻入。
兩種模式下的深度圖相同。
- Name
- carving_depth_mm
- Type
- number
- 預設值 6 (high), 3 (low)
- Description
浮雕的雕刻深度，範圍為
0到60毫米。當remove_base設定為true時，0會產生一個空模型。任務仍會成功，並花費 20 積分，其 GLB 和 STL 檔案不含任何 geometry。
- Name
- remove_base
- Type
- boolean
- 預設值 false
- Description
是否裁去背景並不產生底板。設定為
true時，removal_threshold決定哪些部分算作背景。無論是否設定，Meshy 都會檢查removal_threshold。
remove_base = true- Name
- removal_threshold
- Type
- number
- 預設值 0.01
- Description
Meshy 據此裁去背景的深度閾值，範圍為
0.01到1，深度圖的取值範圍為0到1。較高的值可能會裁去整個浮雕，留下空模型，但任務仍會成功並照常計費。
- Name
- base_thickness_mm
- Type
- number
- 預設值 1, or 0 with remove_base
- Description
底板的厚度，範圍為
0.1到10毫米。當remove_base為true時，請省略該參數或傳入0。
- Name
- bend_mode
- Type
- string
- 預設值 off
- Description
是否彎曲浮雕，以及朝哪個方向彎曲。當該值不為
off時，bend_axis和bend_angle決定彎曲的形狀。無論取值如何，Meshy 都會檢查它們。可用值：
off：平面浮雕。convex：正面向外凸起。concave：正面向內凹陷。
bend_mode = convex or concave- Name
- bend_axis
- Type
- string
- 預設值 xz
- Description
彎曲捲起的是哪一組邊緣。
可用值：
xz：左右兩側邊緣。yz：上下兩側邊緣。
- Name
- bend_angle
- Type
- number
- 預設值 60
- Description
彎曲所跨越的弧度，範圍為
0到360度。低於1時，浮雕保持平面狀態。
- Name
- mesh_resolution
- Type
- integer
- 預設值 1024
- Description
沿照片長邊方向的網格點數，範圍為
512到2048。較高的值能保留更精細的細節，但會產生更大的檔案。在預設值1024下，GLB 檔案約為 40 到 50 MB，STL 檔案約為 80 到 105 MB。方形照片會產生偏大的檔案體積。在2048時，檔案大小分別約為 150 MB 和 300 MB。彎曲會使檔案更大：在2048下，STL 檔案可能達到約 800 MB。
回傳
202 Accepted，在 result 中回傳新建 Relief 任務的 ID。
失敗情形
- Name
400 - Bad Request- Description
請求無法執行。錯誤訊息會說明具體發現了哪種問題。例如：
- 缺少參數：未傳送
image_url。 - 參數無效：某個參數類型錯誤、超出取值範圍，或不屬於其可用值之一。例如，
variant既不是high也不是low，或者mesh_resolution不是512到2048之間的整數。 - 底座厚度：
remove_base設定為true時base_thickness_mm不為0，或在未設定時低於0.1。 - URL 無法存取：Meshy 無法下載
image_url指向的圖片，例如 URL 回傳404或逾時。 - 圖片無效：圖片不是 JPG、JPEG、PNG 或 WebP 檔案，超過 20 MB，尺寸小於 32 × 32 像素，像素過多，或無法讀取。
- 長寬比極端：圖片長邊超過短邊約 16 倍。
請修正請求後重新傳送。Meshy 不會就此收費。參見Errors。
- 缺少參數：未傳送
- Name
401 - Unauthorized- Description
API 金鑰缺失或無效。請檢查
Authorization請求標頭。
- Name
402 - Payment Required- Description
例如：
- 積分不足：帳戶沒有足夠的積分來執行此任務，或帳戶已達到積分限額。請檢查你的積分餘額，然後重試。
- 免費方案：建立任務需要付費方案。請在你的訂閱設定中升級方案，然後重試。
- Name
403 - Forbidden- Description
內容 moderation 攔截了該圖片。Meshy 不會就此請求收費。請傳送其他圖片。
- Name
429 - Too Many Requests- Description
達到了以下某項限制：
- 你傳送的請求過多。請稍候後重試。參見速率限制。
- 排隊或正在執行的任務過多。請等待部分任務完成後重試。
- 在積分已用盡的無限制方案下，達到了可在無積分情況下執行的任務數量上限。請等待某個任務完成，或增加積分。
如果安全檢查在任務執行期間拒絕了該圖片，任務會失敗，task_error.type 被設定為 invalid_input，task_error.code 被設定為 provider_content_refused。Meshy 會退還該任務的積分。請傳送其他圖片。參見Errors。
取得 Relief 任務
根據 ID 返回一個 Relief 任務。
Request
curl https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
"type": "relief",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
},
"depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
"thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000060000,
"expires_at": 1700259260000,
"task_error": null,
"consumed_credits": 20
}
刪除浮雕任務
永久刪除一個浮雕任務，包括其模型、深度圖和資料。刪除後無法復原。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
"message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}
路徑參數
- Name
- id
- Type
- path
- Description
要刪除的任務的 ID。
任務狀態
刪除一個 PENDING 任務會退還建立該任務時所用的積分。
IN_PROGRESS 任務無法刪除。該請求會回傳 409 Conflict，
任務會繼續執行。Meshy 不會為已經開始的任務退款，
因此刪除它會讓你同時損失積分和結果。請等待任務
變為 SUCCEEDED 或 FAILED 狀態後再刪除。
刪除一個 SUCCEEDED 任務不會退還其積分。FAILED 任務在失敗時已經退過款了。
回傳值
任務刪除成功時回傳 200 OK；當任務處於
IN_PROGRESS 狀態時回傳 409 Conflict。
取得浮雕任務列表
回傳你的浮雕任務列表。
Request
curl https://api.meshy.ai/openapi/v1/relief?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
"type": "relief",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
},
"depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
"thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000060000,
"expires_at": 1700259260000,
"task_error": null,
"consumed_credits": 20
}
]
參數
- Name
- page_num
- Type
- integer
- Description
要回傳的頁碼。起始值與預設值皆為
1。
- Name
- page_size
- Type
- integer
- Description
每頁回傳的任務數量，最多為
100。預設值為10。Meshy 會將101到255之間的值視為100，更大的值則會回傳400。
- Name
- sort_by
- Type
- string
- Description
排序方式。
可用值：
+created_at：最早優先-created_at：最新優先
回傳值
分頁的浮雕任務物件列表。
流式取得浮雕任務
以伺服器發送事件（SSE）的形式串流傳輸浮雕任務的更新。
Request
curl -N https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response Stream
// Error event example
event: error
data: {
"status_code": 404,
"message": "Task not found"
}
// Message event examples illustrate task progress (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
"id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
"type": "relief",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
},
"depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
"thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000060000,
"expires_at": 1700259260000,
"task_error": null,
"consumed_credits": 20
}
參數
- Name
- id
- Type
- path
- Description
建立回應中返回的任務 ID。
返回
以伺服器發送事件的形式返回浮雕任務物件的串流。
每個 message 事件都包含完整的任務物件，與取得浮雕任務返回的物件相同。當任務處於 PENDING 或 IN_PROGRESS 狀態時，事件之間發生變化的欄位是 progress、status、started_at 和 preceding_tasks（僅在該任務前面還有其他任務排隊時才會出現）。model_urls、depth_map_url 和 thumbnail_url 會在任務達到 SUCCEEDED 狀態後被賦值。僅生成深度圖的任務會保持 model_urls 為 {}，且 thumbnail_url 為空。
error 事件僅包含 status_code 和 message，因此在讀取 status 之前請先檢查事件名稱。
Relief 任務物件
Relief 任務物件描述由一張照片生成的一個浮雕。model_urls、depth_map_url 和 thumbnail_url 始終存在，在任務成功之前為空。
The Relief Task Object
{
"id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
"type": "relief",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
},
"depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
"thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000060000,
"expires_at": 1700259260000,
"task_error": null,
"consumed_credits": 20
}
Depth map only
{
"id": "0199c3d2-6b8f-7c25-8f3a-4d9e2b7c5a31",
"type": "relief",
"model_urls": {},
"depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-6b8f-7c25-8f3a-4d9e2b7c5a31/output/depth.png?Expires=***",
"thumbnail_url": "",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000030000,
"expires_at": 1700259230000,
"task_error": null,
"consumed_credits": 20
}
- Name
- id
- Type
- string
- Description
任務 ID。請將其視為不透明字串，不要依賴其格式。
- Name
- type
- Type
- string
- Description
任務類型，始終為
relief。
- Name
- model_urls
- Type
- object
- Description
浮雕模型的下載 URL。檔案可能很大；
mesh_resolution列出了典型大小。- Name
glb- Type
- string
- Description
不帶 texture 的 GLB 檔案。其單位為公尺。僅生成深度圖的任務不會包含此欄位。
- Name
stl- Type
- string
- Description
同一模型的二進位 STL 檔案。其單位為毫米，因此開啟時就是浮雕的實際大小，Z 軸朝上。僅生成深度圖的任務不會包含此欄位。
- Name
- depth_map_url
- Type
- string
- Description
浮雕所基於的 16 位元灰階深度圖的下載 URL。像素越亮，高度越高。這些值是相對高度，並非以毫米計。雷射雕刻和 CNC 軟體可以將其用作高度圖。檔案大小約為 1 到 2 MB。若不存在則為空。
- Name
- thumbnail_url
- Type
- string
- Description
浮雕模型預覽圖的下載 URL。若未渲染預覽圖則為空，包括僅生成深度圖的任務。
- Name
- progress
- Type
- integer
- Description
任務完成的百分比。在任務開始前為
0，成功後為100。
- Name
- status
- Type
- string
- Description
任務狀態，為
PENDING、IN_PROGRESS、SUCCEEDED或FAILED之一。
- Name
- preceding_tasks
- Type
- integer
- Description
佇列中排在此任務之前的任務數量。當值為
0時該欄位會被省略，因此只有在有任務排在此任務之前時才會出現。
- Name
- created_at
- Type
- timestamp
- Description
任務建立時間，以 Unix 毫秒表示。
- Name
- started_at
- Type
- timestamp
- Description
任務開始時間，以 Unix 毫秒表示。在任務開始前為
0。
- Name
- finished_at
- Type
- timestamp
- Description
任務完成時間，以 Unix 毫秒表示。在任務完成前為
0。
- Name
- expires_at
- Type
- timestamp
- Description
任務結果過期時間，以 Unix 毫秒表示。在任務完成前為
0。
- Name
- task_error
- Type
- object
- Description
任務失敗時的錯誤詳情。參見Errors。
- Name
- consumed_credits
- Type
- integer
- Description
任務消耗的積分數：
20，若任務為FAILED則為0，Meshy 會退還積分。