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.

Tumatakbo ang task sa background. Para sa karaniwang tagal nito, tingnan ang Processing Times.

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

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

Mga Parameter

Name
prompt
Type
string
Kinakailangan
Description
Isang paglalarawan sa natural na wika ng motion na bubuuin. Maximum na 400 characters.
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).

Mga Ibinabalik

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

Mga Paraan ng Pagkabigo

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

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.

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
}

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.

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).

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
}

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.

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

Delete a Text to Motion Task

Ang endpoint na ito ay permanenteng nagtatanggal ng isang Text to Motion task, kasama na ang na-generate na motion clip. Ang aksyon na ito ay hindi na maaaring bawiin.

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 is left 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."
}

Path Parameters

Name
id
Type
path
Description
Ang ID ng Text to Motion task na tatanggalin.

Katayuan ng Task

Ang task na PENDING pa ay tinatanggal at ang credits na nagamit noong oras ng paggawa ay ibinabalik.

Ang task na IN_PROGRESS na ay hindi maaaring tanggalin: ang request ay tinatanggihan gamit ang 409 Conflict at patuloy pa ring tumatakbo ang task. Ang credits para sa isang task na nasimulan na ng worker ay hindi na maaaring ibalik, kaya kung tatanggalin ito habang tumatakbo pa ito, mawawala sa iyo ang credits at ang resulta. Hintayin munang umabot ito sa SUCCEEDED, FAILED o CANCELED, saka lamang ito tanggalin.

Ang task na nasa terminal state (SUCCEEDED, FAILED o CANCELED) ay tinatanggal nang walang refund.

Ibinabalik

Nagbabalik ng 200 OK kapag matagumpay, o 409 Conflict kapag ang task ay IN_PROGRESS.

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

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
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.