文本到动作 API

从自然语言描述生成角色动作剪辑。描述一个动作 — "角色挥手", "僵尸向前蹒跚" — 即可接收到一个原始动作剪辑，您可以在自己的管道或 DCC 工具中将其重新定位到已绑定骨骼的角色上。

输出的是一个独立的动作剪辑：它不需要，也不附加到角色模型上。要先对角色进行骨骼绑定，请参阅骨骼绑定 API。

POST/openapi/v1/text-to-motion

创建文字到动作任务

这个endpoint创建一个新任务，用于从文本prompt生成动作剪辑。

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

参数

Name
prompt
Type
string
必选
Description
要生成的动作的自然语言描述。最多400个字符。
Name
mode
Type
string
默认值 prime
Description
动作生成模式。可用值：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
积分不足以执行此任务。
Name
403 - Forbidden
Description
prompt被内容moderation标记。
Name
429 - Too Many Requests
Description
您已超出速率限制。

请求

POST

/openapi/v1/text-to-motion

# 仅使用必需参数生成动作剪辑
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
  }'

# 使用Swift模式生成快速经济的剪辑
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
  }'

响应

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

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

检索文本到动作任务

这个endpoint允许您检索给定有效任务id的文本到动作任务。请参阅文本到动作任务对象查看包含哪些属性。

参数

Name
id
Type
path
Description
要检索的文本到动作任务的唯一标识符。

返回值

响应包含文本到动作任务对象。查看文本到动作任务对象部分了解详情。

请求

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

响应

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

列出文本到动作任务

返回调用者的文本到动作任务的分页列表，最新的在前。通过 page_num 和 page_size 进行标准分页。

响应是一个文本到动作任务对象的数组。

请注意，通过API创建的任务是通过API进行管理的——它们不会出现在Web App的“我的资产”中。使用此endpoint查找您不再拥有ID的任务。

请求

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

响应

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

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

流式传输文本到动作任务

此endpoint使用服务器发送事件(SSE)流式传输文本到动作任务的实时更新。

参数

Name
id
Type
path
Description
要传输的文本到动作任务的唯一标识符。

作为服务器发送事件返回文本到动作任务对象的流。

每个message事件都携带完整的任务对象。在任务为PENDING或IN_PROGRESS时，result字段仍然为空（"" / 0），finished_at / expires_at为0；监控status和progress。

请求

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

响应流

// 错误事件示例
event: error
data: {
  "status_code": 404,
  "message": "任务未找到"
}

// 消息事件在每个阶段传递完整的任务对象；结果字段在任务成功之前保持空白。
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: { // SUCCEEDED任务流项目的示例，镜像文本到动作任务对象结构
  "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

删除文字转动作任务

此endpoint永久删除一个文字转动作任务，包括生成的动作剪辑。此操作不可逆。

路径参数

Name
id
Type
path
Description
要删除的文字转动作任务的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

// 成功时返回200 Ok。

文本到动作任务对象

文本到动作任务对象表示从文本提示生成动作片段的工作单元。

属性

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
创建任务时的时间戳（自纪元以来的毫秒数）。
时间戳表示自 1970 年 1 月 1 日 UTC 起经过的毫秒数，遵循 RFC 3339 标准。例如，2023 年 9 月 1 日星期五，GMT 时间中午 12:00:00 表示为 1693569600000。这适用于 Meshy API 中的所有时间戳。
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
此任务消耗的积分数量。prime 模式为 10，swift 模式为 3。对于 FAILED 任务返回 0（失败时积分会被退还）。
Name
task_error
Type
object
Description
失败任务的错误详情；除非任务 FAILED，否则为 null。详见完整的 Errors 中的 task_error 对象参考。
Name
result
Type
object
Description
一旦任务 SUCCEEDED，包含生成的动作片段；在此之前字段存在但为空 ("" / 0)。
- Name
  motion_url
  Type
  string
  Description
  下载生成的动作片段的 URL。URL 每次读取都会重新签名，并在任务的保留窗口到期时失效。
- Name
  motion_format
  Type
  string
  Description
  片段的文件格式：fbx 对于 prime 模式，bvh 对于 swift 模式。
- Name
  duration_ms
  Type
  integer
  Description
  生成的片段的持续时间，单位为毫秒。
- Name
  mode
  Type
  string
  Description
  片段生成时使用的模式：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
}