Rigging API

為人形 3D 模型新增骨骼（armature）並將 mesh 綁定到該骨架上，使角色做好動畫準備。若要將 Animation 套用到已綁定骨架的角色上，請參閱 Animation API。

Rigging 僅適用於具有清晰肢體與身體結構的標準人形（兩足）角色。

POST/openapi/v1/rigging

創建 Rigging 任務

為 3D 模型創建一個 Rigging 任務。任務成功後，會返回標準格式的綁定骨骼角色，並可選返回基礎的走路和跑步動畫。

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

Rigging 不適用於以下模型：

未貼圖的 mesh
非人形 asset
肢體和身體結構不清晰的人形 asset

Request

POST

/openapi/v1/rigging

# Rig a model from a URL
curl https://api.meshy.ai/openapi/v1/rigging \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "YOUR_MODEL_URL_OR_DATA_URI",
    "height_meters": 1.8
  }'

Response

{
  "result": "018b314a-a1b5-716d-c222-2f1776f7f579"
}

參數

Name
input_task_id
Type
string
必選
Description
除非你傳送 model_url，否則此參數為必填項。要綁定骨骼的模型所屬任務的 ID。Meshy 支援帶貼圖的人形模型。
該模型最多可包含 380,000 個三角形（四邊形按 2 個計算），超過此數量會返回 400。要控制在限制範圍內，請先對其執行 Remesh API，將 target_polycount 設為 300000 或更低，或在 topology: quad 時設為 150000 或更低。

Name
model_url
Type
string
必選
Description
除非你傳送 input_task_id，否則此參數為必填項。要綁定骨骼的模型，以公開 URL 或 data URI 的形式提供。如果兩者都傳送，Meshy 會優先使用 input_task_id。
該模型必須是 GLB（.glb）檔案，若透過 http 或 https URL 提供，最大為 400 MB，若以 data URI 提供，最大為 100 MB。Rigging 支援帶貼圖的人形模型。
該模型最多可包含 380,000 個三角形（四邊形按 2 個計算），超過此數量會返回 400。要控制在限制範圍內，請先對其執行 Remesh API，將 target_polycount 設為 300000 或更低，或在 topology: quad 時設為 150000 或更低。
角色的正面必須朝向 +Z 軸，即標準的 glTF 正方向。如果模型朝向其他軸，姿態估計將會失敗。
超過 100 MB 的檔案還必須遵守以下規則：
- 最多可包含 10,000,000 個面。超過此數量的檔案會返回 400。Meshy 將面數計為三角形數，且多次繪製的 mesh 每個副本只計一次。
- 不得使用 Draco 壓縮。

Name
height_meters
Type
number
預設值 1.7
Description
角色的大致身高，單位為公尺。Meshy 使用該值來更準確地縮放和綁定模型骨骼。負值會返回 400。
Name
texture_image_url
Type
string
⚠ 已棄用
Description
當模型本身帶有貼圖時，請省略此參數。若不提供，Meshy 會使用 model_url 檔案中嵌入的貼圖，或輸入任務的貼圖。如果你傳送了此參數，該圖片將成為綁定骨骼後模型的唯一 texture，且模型會失去其 PBR 貼圖。
模型的 UV 展開後的基礎顏色 texture，以公開 URL 或 data URI 的形式提供。圖片必須為 PNG 檔案，且最大為 20 MB。其他圖片格式會返回 400。

返回值

回應的 result 欄位保存新 Rigging 任務的 ID。

失敗模式

Name
400 - Bad Request
Description
請求無法執行。錯誤訊息會說明發現了哪個問題。例如：
- 缺少參數：既未傳送 model_url，也未傳送 input_task_id。
- 模型格式無效：model_url 檔案的副檔名不受支援。僅支援 .glb。
- URL 無法存取：Meshy 無法下載 model_url 檔案。
- 模型檔案過大：model_url 檔案透過 http 或 https URL 提供時超過 400 MB，或以 data URI 提供時超過 100 MB。
- 面數過多：model_url 檔案超過 100 MB，且面數超過 10,000,000。請減少面數，然後重新傳送檔案。
- 模型檔案無法讀取：model_url 檔案超過 100 MB，且 Meshy 無法讀取其檔頭。例如，這是一個經過 Draco 壓縮的 GLB 檔案。
- 模型檔頭過於複雜：model_url 檔案超過 100 MB，且其檔頭中包含過多需要檢查的 mesh、節點或記錄。請減少檔案中的物件數量，然後重新傳送。
- 圖片過大：texture_image_url 圖片超過 20 MB。
- texture 格式無效：texture_image_url 圖片不是 PNG 檔案。
- 身高無效：height_meters 為負值。
- 輸入任務無效：input_task_id 未指向有效的 API 任務。
- 輸入任務尚未就緒：input_task_id 任務尚未達到 SUCCEEDED 狀態。請等待其成功後再重試。
- 面數超限：輸入模型的三角形數超過 380,000 個（四邊形按 2 個計算）。在為模型綁定骨骼之前，請先對其執行 Remesh API，將 target_polycount 設為 300000 或更低，或在 topology: quad 時設為 150000 或更低。
請修正請求後重新傳送。請參閱錯誤。
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
Meshy 找不到 input_task_id 任務的檔案。可能是以下情況之一：
- Meshy 在任務的 expires_at 之後刪除了該任務的檔案。請重新創建該任務，然後傳送新任務的 ID。
- 該任務不具備 rigging 所需的任何檔案，例如預覽圖片，比如一個 Convert 任務。請對其來源任務進行綁定骨骼，或將模型以 model_url 的形式傳送。
Name
422 - Unprocessable Entity
Description
姿態估計失敗。該模型可能不是有效的人形角色。請傳送人形角色的模型。對於 model_url，還請檢查角色是否朝向 +Z 軸。
Name
429 - Too Many Requests
Description
你超出了速率限制。請等待後重試。請參閱速率限制。

GET/openapi/v1/rigging/:id

取得一個 Rigging 任務

根據 ID 回傳一個 Rigging 任務。

Request

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": null,
  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  }
}

參數

Name
id
Type
path
Description
來自建立回應的任務 ID。

回傳

Rigging 任務物件。

DELETE/openapi/v1/rigging/:id

刪除一個 Rigging 任務

永久刪除一個 Rigging 任務，包括其模型和資料。刪除操作無法撤銷。

Request

DELETE

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -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/rigging

列出 Rigging 任務

返回分頁的 Rigging 任務列表，依最新建立時間排序。若要翻頁瀏覽清單，請使用 page_num 和 page_size。

你透過 API 建立的任務只會保留在 API 中，不會出現在網頁應用程式的我的資產裡。如果你遺失了某個任務的 ID，可以使用此端點查找該任務。

Request

GET

/openapi/v1/rigging

curl "https://api.meshy.ai/openapi/v1/rigging?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/rigging/:id/stream

串流取得 Rigging 任務

以 Server-Sent Events（SSE）的形式串流傳輸 Rigging 任務的更新。

Request

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/stream

curl -N https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/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": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task event, with the same fields as the Rigging task object
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": null,
  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/.../Character_output.fbx?...",
    "rigged_character_glb_url": "https://assets.meshy.ai/.../Character_output.glb?...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.glb?...",
      "walking_fbx_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.fbx?...",
      "walking_armature_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin_armature.glb?...",
      "running_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.glb?...",
      "running_fbx_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.fbx?...",
      "running_armature_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin_armature.glb?..."
    }
  }
}

參數

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

回傳值

以 Server-Sent Events 形式回傳的 Rigging 任務物件串流。

每個事件都包含完整的任務物件，其結構與 Get 端點回傳的內容相同。當任務處於 PENDING 或 IN_PROGRESS 狀態時，其結果欄位尚無值。

綁定任務物件

綁定任務物件描述了一個角色的綁定過程。它保存了任務的狀態、進度，以及任務成功時的輸出檔案。

屬性

Example Rigging Task Object

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": null,
  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  }
}

Name
id
Type
string
Description
任務 ID。請將其視為不透明字串，不要依賴其格式。
Name
type
Type
string
Description
任務類型，始終為 rig。
Name
status
Type
string
Description
任務狀態，取值為 PENDING、IN_PROGRESS、SUCCEEDED、FAILED 或 CANCELED 之一。
Name
progress
Type
integer
Description
任務完成的百分比。任務開始前為 0，任務成功後為 100。
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 毫秒數表示。超過此時間後，Meshy 可能會刪除這些檔案。
Name
task_error
Type
object
Description
任務失敗時的錯誤詳情。除非狀態為 FAILED，否則該值為 null。請參閱 Errors。
Name
consumed_credits
Type
integer
Description
任務消耗的積分數量。當狀態為 PENDING、IN_PROGRESS 或 SUCCEEDED 時會顯示該欄位。對於 FAILED 的任務，該值為 0，因為 Meshy 會在任務失敗時退還積分。
Name
result
Type
object
Description
輸出檔案的 URL。在任務成功之前，每個 URL 均為空字串，basic_animations 為 null。
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  綁定角色的 FBX 檔案下載連結。
- Name
  rigged_character_glb_url
  Type
  string
  Description
  綁定角色的 GLB 檔案下載連結。
- Name
  basic_animations
  Type
  object (optional)
  Description
  預設行走和跑步動畫的下載連結。
  Name
  walking_glb_url
  Type
  string
  Description
  帶蒙皮的行走動畫，GLB 檔案。
  Name
  walking_fbx_url
  Type
  string
  Description
  帶蒙皮的行走動畫，FBX 檔案。
  Name
  walking_armature_glb_url
  Type
  string
  Description
  行走動畫的骨架，GLB 檔案。
  Name
  running_glb_url
  Type
  string
  Description
  帶蒙皮的跑步動畫，GLB 檔案。
  Name
  running_fbx_url
  Type
  string
  Description
  帶蒙皮的跑步動畫，FBX 檔案。
  Name
  running_armature_glb_url
  Type
  string
  Description
  跑步動畫的骨架，GLB 檔案。
Name
preceding_tasks
Type
integer
Description
排在此任務前面的任務數量。該值僅在任務處於 PENDING 狀態時有意義。當值為 0 時，該欄位會被省略。