Text to Motion API

根据文本描述生成角色动作片段。描述一个动作，例如“角色挥手”或“僵尸蹒跚前行”，即可获得一段原始动作片段。你可以在自己的管线或 DCC 工具中将该片段重定向到已绑定骨骼的角色上。

输出结果是一段独立的动作片段。它不需要角色模型，也不会附加到任何角色上。如需先为角色添加骨骼，请参阅 Rigging API。如需将片段应用到已绑定骨骼的角色上，请将任务的 id 作为 motion_task_id 发送给 Animation API。请在 3 天的资产保留期内完成应用。

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 key 缺失或无效。请检查 Authorization 请求头。
Name
402 - Payment Required
Description
例如：
- 积分不足：账户没有足够的积分来执行此任务，或账户已达到积分限额。请检查你的积分 balance，然后重试。
- 免费套餐：创建任务需要付费套餐。请在subscription 设置中升级你的套餐，然后重试。
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 中，不会出现在 Web App 的我的资源中。如果你丢失了某个任务的 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。请参阅 Errors。
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。