Text to Motion API

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

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

POST/openapi/v1/text-to-motion

创建文本生成动作任务

此 endpoint 用于创建一个新任务，根据文本 prompt 生成动作片段。

mode 为 prime 的任务消耗 10 credits，使用我们质量最高的动作模型进行生成。mode 为 swift 的任务消耗 3 credits，使用我们经济型动作模型更快地生成。

参数

Name
prompt
Type
string
必选
Description
对要生成的动作的自然语言描述。最多 400 个字符。
Name
mode
Type
string
默认值 prime
Description
动作生成 mode。可选值：prime、swift。prime 生成质量最高，输出 FBX；swift 更快更经济，输出 BVH。
Name
duration
Type
number
必选
Description
动作片段的目标时长（秒）。范围在 2 到 10 之间，步长为 0.5（例如 2、2.5、3、……、10）。

响应中的 result 属性包含新创建的文本生成动作任务的任务 id。

失败模式

Name
400 - Bad Request
Description
请求不可接受。常见原因：
- prompt 缺失或为空：prompt 缺失、为空，或超过 400 个字符。
- mode 无效：mode 不是 prime 或 swift。
- duration 无效：duration 缺失、不在 2–10 范围内，或不是 0.5 秒的整数倍步长。
Name
401 - Unauthorized
Description
Authentication 失败。请检查您的 API key。
Name
402 - Payment Required
Description
执行此任务所需的 credits 不足。
Name
403 - Forbidden
Description
该 prompt 被内容 moderation 标记。
Name
429 - Too Many Requests
Description
您已超出速率限制。

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"
}

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

获取文本生成动作任务

此 endpoint 允许您通过有效的任务 id 获取一个文本生成动作任务。请参阅文本生成动作任务对象以了解其中包含哪些属性。

参数

Name
id
Type
path
Description
要获取的文本生成动作任务的唯一标识符。

返回值

响应内容包含文本生成动作任务对象。详情请参阅文本生成动作任务对象部分。

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
}

GET/openapi/v1/text-to-motion

List Text to Motion Tasks

返回调用者的 Text to Motion 任务的分页列表，按最新排序。通过 page_num 和 page_size 进行标准分页。

响应是一个由Text to Motion Task 对象组成的数组。

请注意，通过 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 任务

此 endpoint 使用 Server-Sent Events（SSE）流式传输 Text to Motion 任务的实时更新。

参数

Name
id
Type
path
Description
要进行流式传输的 Text to Motion 任务的唯一标识符。

以 Server-Sent Events 的形式返回 Text to Motion 任务对象的流。

每个 message 事件都携带完整的任务对象。当任务处于 PENDING 或 IN_PROGRESS 状态时，result 字段仍为空（"" / 0），finished_at / expires_at 为 0；请关注 status 和 progress。

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 stream item, mirroring The Text to Motion Task Object structure
  "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
}

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

删除 Text to Motion 任务

此 endpoint 将永久删除一个 Text to Motion 任务，包括生成的动作片段。此操作不可逆。

路径参数

Name
id
Type
path
Description
要删除的 Text to Motion 任务的 ID。

成功时返回 200 OK。

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

// Returns 200 Ok on success.

Text to Motion 任务对象

Text to Motion 任务对象表示根据文本 prompt 生成动作片段的工作单元。

属性

Name
id
Type
string
Description
任务的唯一标识符。
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
任务创建时的时间戳（自纪元起的毫秒数）。
timestamp 表示自 1970 年 1 月 1 日 UTC 起经过的毫秒数，遵循 RFC 3339 标准。例如，格林尼治标准时间 2023 年 9 月 1 日星期五中午 12:00:00 表示为 1693569600000。这适用于 Meshy API 中的所有 timestamp。
Name
started_at
Type
timestamp
Description
任务开始处理时的时间戳（自纪元起的毫秒数）。如果尚未开始，则为 0。
Name
finished_at
Type
timestamp
Description
任务完成时的时间戳（自纪元起的毫秒数）。如果尚未完成，则为 0。
Name
expires_at
Type
timestamp
Description
任务结果资产过期时的时间戳（自纪元起的毫秒数）。在任务完成之前为 0。生成的片段在任务完成后保留 3 天，请在过期前下载。
Name
preceding_tasks
Type
integer
Description
队列中位于前面的任务数量。仅当状态为 PENDING 时才有意义；为零时会省略此字段。
Name
consumed_credits
Type
integer
Description
此任务消耗的 credits 数量。prime mode 为 10，swift mode 为 3。对于 FAILED 的任务返回 0（失败时会退还 credits）。
Name
task_error
Type
object
Description
失败任务的错误详情；除非任务 FAILED，否则为 null。完整的 task_error 对象参考请参阅 Errors。
Name
result
Type
object
Description
任务 SUCCEEDED 后包含生成的动作片段；在此之前，这些字段虽然存在但为空（"" / 0）。
- Name
  motion_url
  Type
  string
  Description
  生成的动作片段的可下载 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
  生成该片段所使用的 mode：prime 或 swift。

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
}