尺寸調整 API
將 3D 模型調整為以公尺為單位的真實世界尺寸。設定其高度或最長邊的長度，或讓 Meshy 估算該物體的真實世界高度。
建立 Resize 任務
建立一個 Resize 任務。該任務將在背景執行。有關任務通常耗時多久，請參閱處理時間。
Request
# Simple: resize to a specific height
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"resize_height": 1.8
}'
# Advanced: resize longest side with custom origin
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"model_url": "https://example.com/model.glb",
"resize_longest_side": 2.0,
"origin_at": "center"
}'
Response
{
"result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
參數
- Name
- input_task_id
- Type
- string
- 必選
- Description
除非發送
model_url，否則此參數為必填項。生成 3D 模型的任務的 ID，例如 Text to 3D、Image to 3D、Remesh 或 Retexture 任務。該任務必須來自 API，且狀態為SUCCEEDED。Meshy 會以 GLB 檔案形式回傳調整尺寸後的模型。
- Name
- model_url
- Type
- string
- 必選
- Description
除非發送
input_task_id，否則此參數為必填項。要調整尺寸的模型，以公開 URL 或 data URI 形式提供。如果兩者都發送，Meshy 會使用input_task_id。該模型必須是 GLB、glTF、OBJ、FBX 或 STL 檔案，若透過
http或httpsURL 提供，大小最多為 400 MB，若以 data URI 提供，則最多為 100 MB。對於 data URI，請使用 MIME typeapplication/octet-stream。超過 100 MB 的檔案還必須遵循以下規則：
- GLB、glTF、FBX 或 OBJ 檔案最多可包含 10,000,000 個面。Meshy 按三角形計算面數，因此一個四邊形計為 2 個面，重複繪製多次的網格每份副本都會單獨計算一次。
- FBX 檔案必須是 7.1 版或更新版本的二進位 FBX。
- GLB 或 glTF 檔案不得使用 Draco 壓縮。
GLB、OBJ、FBX 或 STL 檔案在結果中會保留其原始格式。
.gltf檔案或 data URI 回傳時將轉換為 GLB。
請在 resize_height、resize_longest_side 或 auto_size 中恰好發送一個。一個都不發送，或發送多個，都會回傳 400。
- Name
- resize_height
- Type
- number
- Description
模型的新高度，以公尺為單位，必須大於 0。負值會回傳
400。
- Name
- resize_longest_side
- Type
- number
- Description
模型最長邊的新長度，以公尺為單位，必須大於 0。負值會回傳
400。Meshy 會保持模型的寬高比。
- Name
- auto_size
- Type
- boolean
- Description
是否使用 AI 視覺估算物體的真實世界高度，並據此調整模型尺寸。除非設定了
origin_at，否則 Meshy 會將原點放在底部。
- Name
- origin_at
- Type
- string
- 預設值 bottom
- Description
調整尺寸後模型原點的位置，
bottom或center。
回傳值
回應的 result 欄位保存了新 Resize 任務的 ID。
失敗模式
- Name
400 - Bad Request- Description
請求無法執行。錯誤訊息會說明發現了哪種問題。例如：
- 缺少參數：既未發送
model_url，也未發送input_task_id。 - 缺少 Resize mode：未發送
resize_height、resize_longest_side和auto_size中的任何一個。 - 參數互斥：請求中包含了
resize_height、resize_longest_side和auto_size中的多個。請只發送一個。 - 尺寸為負數：
resize_height或resize_longest_side為負數。 - 輸入任務無效：
input_task_id不是帶有模型檔案的成功 API 任務。 - 模型格式無效：
model_url檔案的副檔名不受支援。 - URL 無法存取：Meshy 無法下載
model_url檔案。 - 模型檔案過大：透過
http或httpsURL 提供的model_url檔案超過 400 MB，或以 data URI 提供的檔案超過 100 MB。 - 面數過多：
model_url檔案超過 100 MB，且面數超過 10,000,000。請減少面數後重新發送檔案。 - ASCII FBX 超過 100 MB：
model_url檔案是超過 100 MB 的 ASCII FBX。請將其發送為二進位 FBX 或 GLB。 - 模型檔案無法讀取：
model_url檔案超過 100 MB，且 Meshy 無法讀取其檔案標頭。例如，它是經過 Draco 壓縮的 GLB 或 glTF 檔案，或是早於 7.1 版本的二進位 FBX。 - 模型檔案標頭過於複雜：
model_url檔案超過 100 MB，且其檔案標頭包含過多需要檢查的網格、節點或記錄。請減少檔案中的物件數量後重新發送。
請修正請求後重新發送。參見錯誤。
- 缺少參數：既未發送
- Name
401 - Unauthorized- Description
API 金鑰缺失或無效。請檢查
Authorization請求標頭。
- Name
402 - Payment Required- Description
例如：
- 積分不足：帳戶沒有足夠的積分來執行此任務，或帳戶已達到積分限額。請檢查你的積分餘額，然後重試。
- 免費方案：建立任務需要付費方案。請在訂閱設定中升級你的方案，然後重試。
- Name
403 - Forbidden- Description
input_task_id是浮雕模型，該端點無法對其調整尺寸。錯誤訊息為This model type does not support this operation。請發送其他模型。
- Name
404 - Not Found- Description
input_task_id與你的任何任務都不匹配。請檢查任務 ID，然後重新發送請求。
- Name
429 - Too Many Requests- Description
你已超出速率限制。請稍候後重試。參見速率限制。
取得尺寸調整任務
根據 ID 返回一個尺寸調整任務。
Request
curl https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "resize",
"model_urls": {
"glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
},
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000001000,
"task_error": null,
"consumed_credits": 1
}
刪除一個尺寸調整任務
永久刪除一個尺寸調整任務，包括其模型和資料。刪除操作無法復原。
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-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 或 CANCELED 狀態後再刪除。
刪除處於最終狀態（SUCCEEDED、FAILED 或 CANCELED）的任務
不會退還其積分。
回傳
任務刪除成功時回傳 200 OK，當任務處於
IN_PROGRESS 狀態時回傳 409 Conflict。
取得 尺寸調整 任務列表
回傳你的 尺寸調整 任務列表。
Request
curl https://api.meshy.ai/openapi/v1/resize?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "resize",
"model_urls": {
"glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
},
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000001000,
"task_error": null,
"consumed_credits": 1
}
]
參數
- Name
- page_num
- Type
- integer
- 預設值 1
- Description
要回傳的頁碼，最大為
255。更大的值將回傳400。
- Name
- page_size
- Type
- integer
- 預設值 10
- Description
每頁的任務數量，最大為
100。
- Name
- sort_by
- Type
- string
- Description
排序方式。
可用值：
+created_at：最早優先-created_at：最新優先
回傳值
一個分頁的尺寸調整任務物件列表。
流式取得尺寸調整任務
以伺服器發送事件（SSE）的形式串流傳輸尺寸調整任務的更新。
Request
curl -N https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response Stream
// Message event examples illustrate task progress.
event: message
data: {
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
"type": "resize",
"model_urls": {
"glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
},
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1699999999000,
"started_at": 1700000000000,
"finished_at": 1700000001000,
"task_error": null,
"consumed_credits": 1
}
參數
- Name
- id
- Type
- path
- Description
建立回應中回傳的任務 ID。
回傳
以伺服器發送事件形式回傳的 Resize 任務物件 串流。
每個事件都包含完整的任務物件，其結構與 Get endpoint 回傳的內容相同。當任務處於 PENDING 或 IN_PROGRESS 狀態時，其結果欄位尚無數值。
調整尺寸任務物件
一個調整尺寸任務物件描述了一次 3D 模型的尺寸調整。它保存著任務的狀態、progress，以及任務成功後的模型檔案。
屬性
- Name
- id
- Type
- string
- Description
任務 ID。請將其視為不透明字串，不要依賴其格式。
- Name
- type
- Type
- string
- Description
任務類型，始終為
resize。
- Name
- model_urls
- Type
- object
- Description
調整尺寸後的模型檔案的下載 URL。對於
input_task_id，該檔案始終為 GLB。對於model_url，GLB、OBJ、FBX 或 STL 檔案會保留其原有格式，而.gltf檔案或 Data URI 會以 GLB 格式返回。
- Name
- progress
- Type
- integer
- Description
任務完成的程度，以百分比表示。任務開始前為
0，成功後為100。
- Name
- status
- Type
- string
- Description
任務狀態，為
PENDING、IN_PROGRESS、SUCCEEDED、FAILED或CANCELED之一。
- Name
- preceding_tasks
- Type
- integer
- Description
佇列中排在此任務之前的任務數量。該值僅在任務處於
PENDING狀態時有意義。
- 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
任務下載 URL 過期的時間，以 Unix 毫秒數表示。任務完成前為
0。
- Name
- texture_urls
- Type
- array
- Description
任務成功後模型紋理貼圖的下載 URL：一個物件陣列，每個 texture 集合對應一個物件。每個物件都有一個
base_colorURL，還可以包含metallic、roughness、normal、emission和metallic_roughness的 URL。任務成功前該值為null，若模型沒有紋理貼圖，則為空陣列。
- Name
- task_error
- Type
- object
- Description
任務失敗時的錯誤詳情。參見 Errors。
- Name
- consumed_credits
- Type
- integer
- Description
任務消耗的積分數量，調整尺寸任務為
1。對於FAILED任務，該值為0。