Remesh API

使用新的 topology 和面數重建 3D 模型的網格，並將其匯出為你所選擇的格式。模型可以來自另一個 Meshy 任務（例如影象生成 3D 或文字生成 3D），也可以來自模型檔案。

POST/openapi/v1/remesh

創建 Remesh 任務

創建一個 Remesh 任務。該任務在後台執行。關於任務通常需要多長時間，請參閱處理時間。

如需轉換模型格式或調整其尺寸，請使用 Convert API 或 Resize API。本頁中已 deprecated 的參數仍可使用，但新的整合應使用這些 endpoint。

Request

POST

/openapi/v1/remesh

# Basic remesh with custom formats and resize
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "resize_height": 1.0,
    "origin_at": "bottom"
  }'

# Quad remesh with auto-size
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "auto_size": true
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

參數

Name
input_task_id
Type
string
必選
Description
除非你傳送 model_url，否則為必填項。要進行 remesh 的模型所屬任務的 ID，例如 Text to 3D、Image to 3D、Retexture 或 Remesh 任務。該任務必須是你透過 API 創建的，且狀態為 SUCCEEDED。

Name
model_url
Type
string
必選
Description
除非你傳送 input_task_id，否則為必填項。要進行 remesh 的模型，可以是公開 URL 或 data URI。如果兩者都傳送，Meshy 會使用 input_task_id。
模型檔案必須是 GLB、glTF、OBJ、FBX 或 STL 格式，透過 http 或 https URL 提供時最大為 400 MB，作為 data URI 提供時最大為 100 MB。對於 data URI，請使用 MIME type application/octet-stream。
超過 100 MB 的檔案還必須遵循以下規則：
- GLB、glTF、FBX 或 OBJ 檔案最多可包含 10,000,000 個面。Meshy 以三角形計數面數，因此一個四邊形計為 2，而被繪製多次的 mesh 每份副本計一次。
- FBX 檔案必須是 7.1 或更高版本的二進位 FBX。
- GLB 或 glTF 檔案不得使用 Draco 壓縮。

Name
target_formats
Type
string[]
預設值 ["glb"]
Description
要生成的檔案格式。
可用值：
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf
Name
topology
Type
string
預設值 triangle
Description
重新生成後的模型的面類型。
可用值：
- quad：以四邊形為主的 mesh
- triangle：經過精簡的三角形 mesh
Name
target_polycount
Type
integer
預設值 30000
Description
目標面數，範圍從 100 到 300000。根據模型的 geometry 不同，實際結果可能與目標值有所差異。超出該範圍的值會回傳 400。
Name
decimation_mode
Type
integer
Description
按級別設定的自適應面數。設定該參數後，Meshy 會忽略 target_polycount。
可用值：
- 1：超高
- 2：高
- 3：中
- 4：低
Name
resize_height
Type
number
⚠ 已棄用
預設值 0
Description
請改用 Resize API。將模型調整到的高度，單位為公尺。resize_height、resize_longest_side 和 auto_size 最多只能傳送其中一個。
Name
resize_longest_side
Type
number
⚠ 已棄用
預設值 0
Description
請改用 Resize API。將模型包圍盒最長邊調整到的長度，單位為公尺。resize_height、resize_longest_side 和 auto_size 最多只能傳送其中一個。
Name
auto_size
Type
boolean
⚠ 已棄用
預設值 false
Description
請改用 Resize API。是否使用 AI 視覺估算物體的真實世界高度，並將模型調整到該高度。resize_height、resize_longest_side 和 auto_size 最多只能傳送其中一個。
Name
origin_at
Type
string
⚠ 已棄用
預設值 bottom
Description
請改用 Resize API。模型 origin 的放置位置，bottom 或 center。當你傳送 resize_height、resize_longest_side 或 auto_size 時，適用預設值。如果未傳送其中任何一個，Meshy 只有在你傳送了 origin_at 時才會移動 origin。

Name
convert_format_only
Type
boolean
⚠ 已棄用
Description
請改用 Convert API。是否僅將模型轉換為 target_formats。為 true 時，Meshy 會忽略 topology、target_polycount、decimation_mode、resize_height、resize_longest_side 和 auto_size，但仍會驗證這些值，因此無效的值會回傳 400。當 convert_format_only: true 時，如果 target_formats 為空或 null，會回傳 400。

Name
alpha_thumbnail
Type
boolean
預設值 false
Description
是否同時渲染一張帶透明背景（RGBA）的預覽圖，在取得任務時透過 alpha_thumbnail_url 回傳。thumbnail_url 不會改變。

回傳值

回應中的 result 欄位保存了新 Remesh 任務的 ID。

失敗模式

Name
400 - Bad Request
Description
請求無法執行。錯誤訊息會說明發現了什麼問題。例如：
- 缺少參數：既沒有傳送 model_url，也沒有傳送 input_task_id。
- 輸入任務無效：input_task_id 不是一個成功的 API 任務，或者其 AI 模型不支援 remesh。
- 模型格式無效：model_url 檔案的副檔名不受支援。
- URL 無法存取：Meshy 無法下載 model_url 檔案。
- 模型檔案過大：model_url 檔案透過 http 或 https 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，其檔頭中包含的 mesh、節點或記錄數量過多，無法完成檢查。請減少檔案中的物件數量後重新傳送。
- topology 無效：topology 既不是 quad 也不是 triangle。
- 參數互斥：請求中同時包含了 auto_size、resize_height 和 resize_longest_side 中的多個。請僅傳送其中一個。
請修正請求後重新傳送。參見錯誤。
Name
401 - Unauthorized
Description
API 金鑰缺失或無效。請檢查 Authorization 請求標頭。
Name
402 - Payment Required
Description
例如：
- 積分不足：帳戶沒有足夠的積分來執行此任務，或帳戶已達到積分限額。請檢查你的積分餘額，然後重試。
- 免費方案：創建任務需要付費方案。請在訂閱設定中升級你的方案，然後重試。
Name
403 - Forbidden
Description
input_task_id 是一個浮雕模型，此 endpoint 無法對其進行 remesh。錯誤訊息為 This model type does not support this operation。請傳送其他模型。
Name
404 - Not Found
Description
input_task_id 與你的任何任務都不符合。請檢查任務 ID 後重新傳送請求。
Name
429 - Too Many Requests
Description
你已超出速率限制。請稍候後重試。參見速率限制。

GET/openapi/v1/remesh/:id

取得重構網格任務

根據 ID 回傳一個重構網格任務。

Request

GET

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null
}

參數

Name
id
Type
path
Description
建立回應中回傳的任務 ID。

回傳值

重構網格任務物件。

DELETE/openapi/v1/remesh/:id

刪除一個重構網格任務

永久刪除一個重構網格任務，包括它的模型和資料。刪除操作無法復原。

Request

DELETE

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/remesh/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。

GET/openapi/v1/remesh

取得 Remesh 任務列表

回傳你的 Remesh 任務列表。

Request

GET

/openapi/v1/remesh

curl https://api.meshy.ai/openapi/v1/remesh?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "remesh",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null
  }
]

參數

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：最新優先

回傳值

一個分頁的 Remesh 任務物件列表。

GET/openapi/v1/remesh/:id/stream

流式取得重構網格任務

以伺服器發送事件（SSE）的形式，流式取得重構網格任務的更新。

Request

GET

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/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.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
    "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

參數

Name
id
Type
path
Description
建立回應中回傳的任務 ID。

回傳值

以伺服器發送事件形式回傳的重構網格任務物件串流。

每個事件都包含完整的任務物件，其結構與 Get endpoint 回傳的結構相同。當任務處於 PENDING 或 IN_PROGRESS 狀態時，其結果欄位還沒有值。

重構網格任務物件

一個重構網格任務物件描述了對某個3D模型的一次remesh操作。它保存了任務的狀態、progress，以及任務成功時的模型檔案。

屬性

Example Remesh Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5
}

Name
id
Type
string
Description
任務ID。請將其視為不透明字串，不要依賴其格式。
Name
type
Type
string
Description
任務類型，始終為remesh。
Name
model_urls
Type
object
Description
remesh後模型的下載URL，每種檔案格式對應一個。任務未生成的格式沒有對應的鍵，而不是空字串。
- Name
  glb
  Type
  string
  Description
  GLB檔案。
- Name
  fbx
  Type
  string
  Description
  FBX檔案。
- Name
  obj
  Type
  string
  Description
  OBJ檔案。
- Name
  usdz
  Type
  string
  Description
  USDZ檔案。
- Name
  blend
  Type
  string
  Description
  Blender檔案。
- Name
  stl
  Type
  string
  Description
  STL檔案。
- Name
  3mf
  Type
  string
  Description
  3MF檔案。僅當target_formats包含3mf時才會出現。
Name
thumbnail_url
Type
string
Description
remesh後模型預覽圖的下載URL。
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url的透明背景（RGBA）版本的下載URL。僅當你在建立任務時設定了alpha_thumbnail: true，且Meshy渲染了透明預覽圖時才會出現。
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
任務成功時，模型texture貼圖的下載URL：一個物件陣列，每個紋理集對應一個物件。每個物件都有一個base_colorURL，還可以有metallic、roughness、normal、emission和metallic_roughnessURL。任務成功前為null，如果模型沒有texture貼圖則為空陣列。
Name
task_error
Type
object
Description
任務失敗時的錯誤詳情。參見錯誤。
Name
consumed_credits
Type
integer
Description
任務消耗的積分數量。當狀態為PENDING、IN_PROGRESS或SUCCEEDED時出現。對於FAILED任務，該值為0，因為Meshy會在任務失敗時退還積分。