Animation API

為已綁定骨骼的角色套用動畫，並列出可套用的動畫。

POST/openapi/v1/animations

建立 Animation 任務

建立一個 Animation 任務，將動畫套用到你之前綁定骨骼的角色上。動畫可以是以下之一：

來自動畫庫的預設動作（action_id）
合併到一個檔案中的多個預設動作（action_ids）
你使用 Text to Motion API 產生的動作片段（motion_task_id）

你也可以對輸出進行後處理。任務在背景執行。有關任務通常耗時多久，請參閱處理時間。

Request

POST

/openapi/v1/animations

# Animate a rigged model with required params only
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92
  }'

# Apply several preset actions and get one file with one clip per action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_ids": [10, 25, 92]
  }'

# Apply a generated Text to Motion clip instead of a preset action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "motion_task_id": "018c425b-b2c6-727e-d333-3c1887i9h791"
  }'

# With post-processing to change FPS
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92,
    "post_process": {
      "operation_type": "change_fps",
      "fps": 24
    }
  }'

Response

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

參數

Name
rig_task_id
Type
string
必選
Description
要為其角色設定動畫的 Rigging 任務 ID，來自 POST /openapi/v1/rigging。該任務的狀態必須為 SUCCEEDED。

請只傳送 action_id、action_ids 和 motion_task_id 其中一個。

Name
action_id
Type
integer
必選
Description
除非你傳送 action_ids 或 motion_task_id，否則此項必填。要套用的預設動畫的 ID。完整的動畫列表請參閱動畫庫參考或列出動畫。

Name
action_ids
Type
array of integers
必選
Description
除非你傳送 action_id 或 motion_task_id，否則此項必填。要一次套用的 1 到 10 個預設動畫的 ID，不能重複。超過 10 個 ID，或存在重複 ID，將回傳 400。有關 ID 列表，請參閱動畫庫參考。
Meshy 會為每個動作回傳一個包含一個動畫片段的檔案，這適用於遊戲引擎中的狀態機。Meshy 會對清單中的每個動作個別計費。請參閱 Pricing。
只包含一個 ID 的清單與將該 ID 作為 action_id 傳送的效果相同。

Name
motion_task_id
Type
string
必選
Description
除非你傳送 action_id 或 action_ids，否則此項必填。要套用其片段以取代預設動作的 Text to Motion 任務的 ID。該任務的狀態必須為 SUCCEEDED，且 rig 必須是雙足的。
Meshy 會將該片段重定向到已綁定骨骼的角色上。建立此任務時會複製該片段，因此即使之後 Text to Motion 任務過期或你刪除了它，也不會影響此任務。Meshy 會將 Text to Motion 任務的檔案保留 3 天，請在此之前套用該片段。

Name
post_process
Type
object
Description
動畫輸出的後處理。不設定此項即可取得標準動畫檔案。
使用 motion_task_id 時，重定向可能只會產生僅包含 GLB 的動畫。如果你傳送了 post_process 但沒有可用的 FBX 檔案，任務將以 task_error 失敗，Meshy 會退還你的積分。不傳送 post_process 時，任務會成功完成，且 animation_fbx_url 為空。

僅當 post_process is set

Name
operation_type
Type
string
Description
要執行的操作。不設定時，Meshy 不會產生額外的檔案。值不在以下清單中將回傳 400。
可用值：
- change_fps：將影格率變更為 fps
- fbx2usdz：將動畫轉換為 USDZ
- extract_armature：將 armature 提取為 FBX 檔案
Name
fps
Type
integer
預設值 30
Description
要變更為的影格率，為 24、25、30 或 60 之一。僅當 operation_type 為 change_fps 時適用。其他任何值都將回傳 400。

使用 action_ids 時，任務會回傳一個合併檔案，而不是每個動作一個檔案。animation_glb_url 和 animation_fbx_url 都指向同一個檔案，該檔案將每個要求的動作儲存為獨立的片段。在該檔案中：

片段順序：按照 action_ids 陣列的順序，而不是 ID 的數字順序。
片段名稱：動畫庫中的名稱。這些名稱與你從 Meshy 網頁應用程式中將角色的所有動畫匯出為一個檔案時得到的名稱一致。如果兩個要求的 ID 具有相同的片段名稱，Meshy 會將 action_id 加到後一個名稱上，以保持名稱唯一。
後處理：Meshy 會將其套用於合併後的檔案，而不是每個片段。

回傳值

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

失敗情況

Name
400 - Bad Request
Description
請求無法執行。錯誤訊息會說明發現了什麼問題。例如：
- 缺少參數：缺少 rig_task_id，或者未傳送 action_id、action_ids 和 motion_task_id 中的任何一個。
- 參數衝突：請求中包含了多個 action_id、action_ids 和 motion_task_id。請只傳送一個。
- 無效的 rig 任務：rig_task_id 不是有效的任務 ID，不是 Rigging 任務，或所指向的任務尚未成功完成。
- 無效的動作 ID：action_id 或 action_ids 中的某一項不是有效的動畫。
- 動作過多：action_ids 包含超過 10 個 ID。
- 重複動作：action_ids 中同一個 ID 出現了多次。
- 動作任務尚未就緒：motion_task_id 對應的任務尚未達到 SUCCEEDED 狀態。
- 不支援的 rig：motion_task_id 需要雙足 rig，Meshy 會拒絕四足 rig。
修正請求後重新傳送。請參閱 Errors。
Name
401 - Unauthorized
Description
API 金鑰缺失或無效。請檢查 Authorization 標頭。
Name
402 - Payment Required
Description
例如：
- 積分不足：帳戶沒有足夠的積分來完成此任務，或帳戶已達到積分限額。請檢查你的積分餘額，然後重試。
- 免費方案：建立任務需要付費方案。請在你的訂閱設定中升級方案，然後重試。
Name
403 - Forbidden
Description
rig_task_id 任務是浮雕模型，此 endpoint 無法為其加上動畫。訊息為 This model type does not support this operation。請為其他模型綁定骨骼。
Name
404 - Not Found
Description
Meshy 找不到請求所需的任務或檔案。以下情況之一適用：
- Meshy 在你的任務中找不到 rig_task_id 對應的任務。請檢查該 ID。
- Meshy 已在 rig_task_id 任務的 expires_at 之後刪除了其檔案。請重新為角色綁定骨骼。
- Meshy 找不到 motion_task_id 對應的任務。請檢查該 ID。
- 該動作片段已過期，因為 Meshy 只會將 Text to Motion 任務的檔案保留 3 天。請建立另一個 Text to Motion 任務。
Name
429 - Too Many Requests
Description
你已超出速率限制。請稍候後重試。請參閱速率限制。

GET/openapi/v1/animations/:id

取得 Animation 任務

根據 ID 回傳一個 Animation 任務。

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791

curl https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": null,
  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.glb?Expires=...",
    "animation_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.fbx?Expires=...",
    "processed_usdz_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed.usdz?Expires=...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_armature.fbx?Expires=...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_60fps.fbx?Expires=..."
  }
}

參數

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

回傳值

Animation 任務物件。

DELETE/openapi/v1/animations/:id

刪除 Animation 任務

永久刪除一個 Animation 任務，包括其模型和資料。刪除操作無法復原。

Request

DELETE

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

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

查詢 Animation 任務列表

回傳你的 Animation 任務的分頁列表，依最新優先排序。如需翻頁瀏覽列表，請使用 page_num 和 page_size。

透過 API 建立的任務不會出現在網頁應用程式的我的資產中，因此你需要透過 API 來管理它們。如果你遺失了某個任務的 ID，可以使用此 endpoint 來查找它。

Request

GET

/openapi/v1/animations

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

GET/openapi/v1/animations/:id/stream

串流傳輸 Animation 任務

以伺服器發送事件（SSE）的形式串流傳輸 Animation 任務的更新。

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/stream

curl -N https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/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": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, with the same structure as the Animation task object
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": null,
  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  }
}

參數

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

回傳

以伺服器發送事件的形式回傳 Animation 任務物件的串流。

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

動畫任務物件

動畫任務物件描述應用於綁定骨骼角色的一個動畫。它包含狀態、進度，以及任務成功時的動畫檔案。

屬性

Example Animation Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": null,
  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  }
}

Name
id
Type
string
Description
任務 ID。將其視為不透明字串，不要依賴其格式。
Name
type
Type
string
Description
任務類型，始終為 animate。
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 毫秒表示。
Name
task_error
Type
object
Description
任務失敗時的錯誤詳情。除非狀態為 FAILED，否則為 null。請參閱錯誤。
Name
consumed_credits
Type
integer
Description
任務使用的積分數量。當狀態為 PENDING、IN_PROGRESS 或 SUCCEEDED 時存在。對於 FAILED 的任務，該值為 0，因為 Meshy 會在任務失敗時退還積分。
Name
result
Type
object
Description
當任務狀態為 SUCCEEDED 時，動畫檔案的下載 URL。
- Name
  animation_glb_url
  Type
  string
  Description
  GLB 格式的動畫檔案。對於使用 action_ids 建立的任務，這一個檔案會將每個請求的動作作為單獨的剪輯儲存其中。
- Name
  animation_fbx_url
  Type
  string
  Description
  FBX 格式的動畫檔案。對於使用 action_ids 建立的任務，這一個檔案會將每個請求的動作作為單獨的剪輯儲存其中。
- Name
  processed_usdz_url
  Type
  string
  Description
  經過處理的 USDZ 格式動畫檔案。
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  經過處理的 FBX 格式 armature 檔案。
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  按變更後的影格率生成的 FBX 格式動畫檔案，例如使用了 change_fps 操作時。
Name
preceding_tasks
Type
integer
Description
排在此任務之前的佇列中任務數量。該值僅在任務為 PENDING 時才有意義。當值為 0 時將省略該欄位。

GET/openapi/v1/animations/library

取得動畫列表

回傳動畫庫中的所有動畫，依 action_id 排序。回應結果是完整列表，不分頁，因此一次呼叫即可填滿整個動作選擇器。篩選條件可以縮小結果範圍。若要取得全部動畫，則不要傳入任何篩選條件。

如需瀏覽同一列表並查看每個動作的動畫預覽，請參閱動畫庫參考。

此請求不消耗積分。

Request

GET

/openapi/v1/animations/library

curl "https://api.meshy.ai/openapi/v1/animations/library?category=Fighting" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "action_id": 4,
    "name": "Attack",
    "key": "Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Attack.gif"
  },
  {
    "action_id": 92,
    "name": "Double Combo Attack",
    "key": "Double_Combo_Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
  }
]

參數

Name
search
Type
string
Description
要搜尋的文字。Meshy 會回傳 name 或 key 中包含該文字的動畫，不區分大小寫。Meshy 會依字面比對該文字，因此 % 和 _ 不是萬用字元。
Name
category
Type
string
Description
要列出的類別，需精確比對。未知類別會回傳空列表。
可用值：
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
要列出的子類別，需精確比對。你可以在不傳 category 的情況下單獨使用它。子類別名稱在各類別間並非唯一。例如，Transitioning 同時屬於 Fighting 和 DailyActions。因此，若不傳 category，該篩選條件會比對所有類別中的該子類別。
Name
action_ids
Type
string
Description
要回傳的動畫，最多可傳入 200 個以逗號分隔的 action_id 值。可用它來查詢特定 ID，而無需逐一瀏覽。超過 200 個 ID 會回傳 400。
回應結果會省略不存在對應動畫的 ID。因此，你也可以用此篩選條件檢查已儲存的 ID 是否仍然可用。

組合篩選條件

Meshy 會同時套用這些篩選條件。每個條件都會縮小結果範圍，因此只有同時滿足所有條件時，Meshy 才會回傳某個動畫。在同一個篩選條件內，符合其中任意一個值即可。例如，search 會比對 name 或 key，而 action_ids 會比對列表中的任意一個 ID。

因此，若組合條件之間沒有交集，會回傳空陣列，而不是報錯。動作 92 是「Double Combo Attack」，屬於 Fighting 動畫。例如：

?action_ids=92&category=Fighting 回傳動作 92。
?action_ids=92&category=Dancing 回傳 []，因為它不是 Dancing 動畫。
?action_ids=92&search=walk 回傳 []，因為其名稱與 walk 不符。

若要取得任意類別下的特定動畫，可單獨傳入 action_ids。

回傳值

一個動畫物件列表。

建立動畫任務接受此 endpoint 回傳的所有 action_id，而此 endpoint 也會回傳建立任務所接受的所有 ID。兩者都不包含已停用的動畫。如果你快取了動畫庫，請定期重新整理，以免已停用的 ID 仍留在你的選擇器中。

The animation object

一個 animation 物件描述動畫庫中的一個動畫。

Example Animation Object

{
  "action_id": 92,
  "name": "Double Combo Attack",
  "key": "Double_Combo_Attack",
  "category": "Fighting",
  "sub_category": "AttackingwithWeapon",
  "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
}

Name
action_id
Type
integer
Description
建立 Animation 任務時作為 action_id 傳送的值。它是唯一且穩定的，但並不連續。已下架的動畫會在編號中留下空隙，因此請勿假設某個範圍內的每個 ID 都是有效的。
Name
name
Type
string
Description
動畫的顯示名稱。它並不唯一，因為部分動畫會與其他變體共用同一個名稱。要識別某個動畫，請使用 action_id 或 key。
Name
key
Type
string
Description
該動畫唯一且穩定的 slug。當你需要一個非數字 ID 來為自己的儲存空間建立鍵值時可以使用它。
Name
category
Type
string
Description
頂層分組，例如 Fighting。
Name
sub_category
Type
string
Description
分類下的子分組，例如 AttackingwithWeapon。
Name
preview_url
Type
string
Description
該動作的 GIF 預覽動圖網址。你可以在自己的選擇器中直接顯示它。