API ng Text to Motion

Bumuo ng mga motion clip ng character mula sa mga paglalarawan gamit ang natural na wika. Ilarawan ang isang aksyon — "isang character na kumakaway", "isang zombie na gumagapang pasulong" — at makakatanggap ka ng raw na motion clip na maaari mong i-retarget sa mga naka-rig na character sa sarili mong pipeline o DCC tools.

Ang output ay isang standalone na motion clip: hindi ito nangangailangan, at hindi ito nakakabit, sa isang character model. Upang mag-rig muna ng character, tingnan ang Rigging API. Upang ilapat ang isang nabuong clip sa iyong naka-rig na character, ipasa ang task id bilang motion_task_id sa Animation API — ilapat ito sa loob ng 3-araw na asset retention window.

POST/openapi/v1/text-to-motion

Gumawa ng Text to Motion Task

Ang endpoint na ito ay gumagawa ng bagong task upang bumuo ng motion clip mula sa isang text prompt.

Ang task na may mode na prime ay nagkakahalaga ng 10 credits at bumubuo gamit ang aming pinakamataas na kalidad na motion model. Ang task na may mode na swift ay nagkakahalaga ng 3 credits at mas mabilis bumuo gamit ang aming mas matipid na motion model.

Mga Parameter

Name
prompt
Type
string
Kinakailangan
Description
Isang natural-language na paglalarawan ng motion na gagawin. Maximum na 400 karakter.
Name
mode
Type
string
default prime
Description
Ang mode ng paggawa ng motion. Mga available na value: prime, swift. Ang prime ay gumagawa ng pinakamataas na kalidad at naglalabas ng FBX; ang swift ay mas mabilis at mas mura at naglalabas ng BVH.
Name
duration
Type
number
Kinakailangan
Description
Ang target na tagal ng motion clip sa segundo. Sa pagitan ng 2 at 10, sa hakbang na 0.5 (halimbawa 2, 2.5, 3, … 10).

Ibinabalik

Ang result property ng response ay naglalaman ng task id ng bagong nagawang Text to Motion task.

Mga Mode ng Kabiguan

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Mga karaniwang dahilan:
- Nawawala o walang laman na prompt: nawawala, walang laman, o mas mahaba sa 400 na karakter ang prompt.
- Di-wastong mode: hindi prime o swift ang mode.
- Di-wastong duration: nawawala ang duration, wala sa saklaw na 2–10, o hindi sa hakbang na 0.5 segundo.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Pakisuri ang iyong API key.
Name
402 - Payment Required
Description
Hindi sapat ang credits upang isagawa ang task na ito.
Name
403 - Forbidden
Description
Na-flag ng content moderation ang prompt.
Name
429 - Too Many Requests
Description
Lumampas ka na sa iyong rate limit.

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

Kunin ang Text to Motion Task

Ang endpoint na ito ay nagbibigay-daan sa iyo na kunin ang isang Text to Motion task gamit ang isang wastong task id. Sumangguni sa The Text to Motion Task Object upang makita kung aling mga property ang kasama.

Mga Parameter

Name
id
Type
path
Description
Natatanging identifier para sa Text to Motion task na kukunin.

Ibinabalik

Ang tugon ay naglalaman ng Text to Motion Task object. Tingnan ang seksyong The Text to Motion Task Object para sa mga detalye.

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

Nagbabalik ng pagination na listahan ng mga Text to Motion task ng tumatawag, pinakabago muna. Standard na pagination gamit ang page_num at page_size.

Ang tugon ay isang array ng Text to Motion Task objects.

Tandaan na ang mga task na ginawa sa pamamagitan ng API ay pinamamahalaan sa pamamagitan ng API — hindi ito lumalabas sa My Assets ng web app. Gamitin ang endpoint na ito upang hanapin ang isang task na hindi mo na alam ang ID.

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

I-stream ang Text to Motion Task

Ang endpoint na ito ay nagsasagawa ng stream ng real-time na update para sa isang Text to Motion task gamit ang Server-Sent Events (SSE).

Mga Parameter

Name
id
Type
path
Description
Natatanging identifier para sa Text to Motion task na i-stream.

Ibinabalik

Nagbabalik ng stream ng The Text to Motion Task Objects bilang Server-Sent Events.

Bawat message event ay nagdadala ng buong task object. Habang ang task ay PENDING o IN_PROGRESS, ang mga field ng result ay mananatiling walang laman ("" / 0) at ang finished_at / expires_at ay 0; bantayan ang status at 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

Mag-delete ng Text to Motion Task

Ang endpoint na ito ay permanenteng magde-delete ng isang Text to Motion task, kasama na ang nabuong motion clip. Ang aksyong ito ay hindi na mababawi.

Path Parameters

Name
id
Type
path
Description
Ang ID ng Text to Motion task na ide-delete.

Ibinabalik

Nagbabalik ng 200 OK kapag matagumpay.

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.

Ang Text to Motion Task Object

Ang Text to Motion Task object ay kumakatawan sa yunit ng gawain para sa paggawa ng motion clip mula sa isang text prompt.

Mga Property

Name
id
Type
string
Description
Natatanging identifier para sa task.
Name
type
Type
string
Description
Uri ng task. Ang value ay text-to-motion.
Name
status
Type
string
Description
Status ng task. Posibleng values: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress ng task (0-100).
Name
created_at
Type
timestamp
Description
Timestamp (milliseconds mula epoch) kung kailan nilikha ang task.
Ang isang timestamp ay kumakatawan sa bilang ng milliseconds na nakalipas mula Enero 1, 1970 UTC, batay sa RFC 3339 standard. Halimbawa, ang Biyernes, Setyembre 1, 2023 12:00:00 PM GMT ay kinakatawan bilang 1693569600000. Ito ay naaangkop sa lahat ng timestamps sa Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp (milliseconds mula epoch) kung kailan nagsimulang iproseso ang task. 0 kung hindi pa nagsisimula.
Name
finished_at
Type
timestamp
Description
Timestamp (milliseconds mula epoch) kung kailan natapos ang task. 0 kung hindi pa tapos.
Name
expires_at
Type
timestamp
Description
Timestamp (milliseconds mula epoch) kung kailan mag-e-expire ang mga resultang asset ng task. 0 hanggang matapos ang task. Ang nabuong clip ay itinatago sa loob ng 3 araw pagkatapos matapos ang task; i-download ito bago ito mag-expire.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga nauunang task sa queue. Makabuluhan lamang kung ang status ay PENDING; hindi isinasama kapag zero.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na nagamit ng task na ito. 10 para sa prime mode, 3 para sa swift mode. Nagbabalik ng 0 para sa mga FAILED na task (ang credits ay ire-refund kapag nabigo).
Name
task_error
Type
object
Description
Detalye ng error para sa mga nabigong task; null maliban kung ang task ay FAILED. Tingnan ang Errors para sa buong reference ng task_error object.
Name
result
Type
object
Description
Naglalaman ng nabuong motion clip kapag ang task ay SUCCEEDED; hanggang doon, ang mga field ay naroroon ngunit walang laman ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  Ma-do-download na URL para sa nabuong motion clip. Ang URL ay muling nilalagdaan (re-signed) sa bawat pagbasa at nag-e-expire kasabay ng retention window ng task.
- Name
  motion_format
  Type
  string
  Description
  File format ng clip: fbx para sa prime mode, bvh para sa swift mode.
- Name
  duration_ms
  Type
  integer
  Description
  Tagal ng nabuong clip sa milliseconds.
- Name
  mode
  Type
  string
  Description
  Ang mode kung saan nabuo ang clip: prime o 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
}