Text to Motion API

根據文字描述產生角色動作片段。描述一個動作，例如「一個角色在揮手」或「一個殭屍蹣跚前行」，即可取得原始動作片段。你可以在自己的流程或 DCC 工具中將該片段重定向到已綁定骨骼的角色上。

輸出結果是一個獨立的動作片段。它不需要角色模型，也不會附加到任何模型上。若要先為角色加上骨骼，請參閱 Rigging API。若要將片段套用到你已綁定骨骼的角色上，請將任務的 id 作為 motion_task_id 傳送給 Animation API。

POST/openapi/v1/text-to-motion

建立 Text to Motion 任務

建立一個 Text to Motion 任務，根據文字 prompt 生成動作片段。

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

prime 任務消耗 10 積分，使用 Meshy 更高品質的動作模型。swift 任務消耗 3 積分，使用速度更快、成本更低的動作模型。

Request

POST

/openapi/v1/text-to-motion

# Generate a motion clip with required params only
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "duration": 3
  }'

# Generate a fast, economical clip with Swift mode
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "mode": "swift",
    "duration": 4.5
  }'

Response

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

參數

Name
prompt
Type
string
必選
Description
描述要生成的動作的文字，最多 400 個字元。超出長度將回傳 400。
Name
mode
Type
string
預設值 prime
Description
動作模型，同時也決定了片段的檔案格式。
可用值：
- prime：品質更高，回傳 FBX 格式的片段
- swift：更快更經濟，回傳 BVH 格式的片段
任何其他值都會回傳 400。
Name
duration
Type
number
必選
Description
目標片段時長（秒），範圍從 2 到 10，步長為 0.5，例如 2、2.5 或 3。任何其他值都會回傳 400。

回傳值

回應的 result 欄位儲存新 Text to Motion 任務的 ID。

失敗情形

Name
400 - Bad Request
Description
請求無法執行。錯誤訊息會說明發現的問題。例如：
- 缺少或為空的 prompt：prompt 缺失、為空，或超過 400 個字元。
- 無效的 mode：mode 不是 prime 或 swift。
- 無效的 duration：duration 缺失、超出 2 到 10 的範圍，或不是 0.5 秒的整數倍。
修正請求後重新傳送。參閱 Errors。
Name
401 - Unauthorized
Description
API 金鑰缺失或無效。請檢查 Authorization 請求標頭。
Name
402 - Payment Required
Description
例如：
- 積分不足：帳戶沒有足夠的積分來執行此任務，或帳戶已達到積分限額。請檢查你的積分餘額，然後重試。
- 免費方案：建立任務需要付費方案。請在訂閱設定中升級你的方案，然後重試。
Name
403 - Forbidden
Description
內容 moderation 標記了該 prompt。請修改 prompt 後重新傳送請求。
Name
429 - Too Many Requests
Description
你已超出速率限制。請稍候後重試。參閱速率限制。

GET/openapi/v1/text-to-motion/:id

取得 Text to Motion 任務

根據 ID 回傳一個 Text to Motion 任務。

Request

GET

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791

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

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

參數

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

回傳值

Text to Motion 任務物件。

GET/openapi/v1/text-to-motion

列出 Text to Motion 任務

返回你的 Text to Motion 任務的分頁列表，按最新的排在前面。要翻頁瀏覽列表，請使用 page_num 和 page_size。

回應是一個 Text to Motion 任務物件陣列。

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

Request

GET

/openapi/v1/text-to-motion

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

Response

[
  {
    "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
    "type": "text-to-motion",
    "status": "SUCCEEDED",
    "...": "..."
  }
]

GET/openapi/v1/text-to-motion/:id/stream

流式取得 Text to Motion 任務

以伺服器發送事件（SSE）的形式，流式取得 Text to Motion 任務的更新。

Request

GET

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791/stream

curl -N https://api.meshy.ai/openapi/v1/text-to-motion/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 events carry the full task object at every stage; the result
// fields stay empty until the task succeeds.
event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "IN_PROGRESS",
  "progress": 50,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 0,
  "expires_at": 0,
  "task_error": null,
  "result": {
    "motion_url": "",
    "motion_format": "",
    "duration_ms": 0,
    "mode": ""
  },
  "consumed_credits": 10
}

event: message
data: { // Example of a SUCCEEDED task event, with the same fields as the Text to Motion task object
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

參數

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

回傳值

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

每個 message 事件都攜帶完整的任務物件。當任務處於 PENDING 或 IN_PROGRESS 狀態時，result 欄位為空（"" 或 0），finished_at 和 expires_at 均為 0。要追蹤任務進度，請關注 status 和 progress。

DELETE/openapi/v1/text-to-motion/:id

刪除 Text to Motion 任務

永久刪除一個 Text to Motion 任務，包括其動作片段。刪除操作無法復原。

Request

DELETE

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -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。

Text to Motion 任務物件

Text to Motion 任務物件描述了一個動作片段的生成過程。它保存了該任務的狀態、progress，以及任務成功後生成的片段。

屬性

Example Text to Motion Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

Name
id
Type
string
Description
該任務的 ID。請將其視為一個不透明字串，不要依賴其格式。
Name
type
Type
string
Description
任務類型，始終為 text-to-motion。
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 毫秒時間戳表示。在任務完成之前，該值為 0。Meshy 會在任務完成後保留該片段 3 天，請在此之前下載。
Name
preceding_tasks
Type
integer
Description
排在該任務前面的任務數量。該值僅在任務處於 PENDING 狀態時才有意義。當該值為 0 時，此欄位會被省略。
Name
consumed_credits
Type
integer
Description
該任務消耗的積分數量，prime mode 為 10，swift mode 為 3。對於 FAILED 的任務，該值為 0，因為 Meshy 會在任務失敗時退還積分。
Name
task_error
Type
object
Description
任務失敗時的錯誤詳情，否則為 null。請參閱錯誤。
Name
result
Type
object
Description
任務成功後生成的動作片段。在此之前，這些欄位雖然存在但為空（"" 或 0）。
- Name
  motion_url
  Type
  string
  Description
  該動作片段的下載 URL。Meshy 會在每次讀取時重新對該 URL 進行簽名，並且該 URL 會隨任務的保留期限到期而失效。
- Name
  motion_format
  Type
  string
  Description
  該片段的檔案格式，prime mode 為 fbx，swift mode 為 bvh。
- Name
  duration_ms
  Type
  integer
  Description
  該片段的時長，以毫秒為單位。
- Name
  mode
  Type
  string
  Description
  Meshy 用於生成該片段的 mode，為 prime 或 swift。