Text to Motion API

Gumawa ng mga motion clip ng character mula sa mga paglalarawan sa teksto. Ilarawan ang isang aksyon, tulad ng "isang character na kumakaway" o "isang zombie na gumagapang pasulong", at kumuha ng raw motion clip. Maaari mong i-retarget ang clip sa mga naka-rig na character sa sarili mong pipeline o mga DCC tool.

Ang output ay isang standalone na motion clip. Hindi ito nangangailangan ng character model, at hindi ito naka-attach sa isa. Upang mag-rig muna ng character, tingnan ang Rigging API. Upang ilapat ang isang clip sa iyong naka-rig na character, ipadala ang id ng task bilang motion_task_id sa Animation API.

POST/openapi/v1/text-to-motion

Gumawa ng Text to Motion task

Gumagawa ng Text to Motion task, na bumubuo ng motion clip mula sa isang text prompt.

Tumatakbo ang task sa background. Para sa karaniwang tagal ng pagproseso ng isang task, tingnan ang Processing times.

Ang isang prime task ay nagkakahalaga ng 10 credits at gumagamit ng mas mataas ang kalidad na motion model ng Meshy. Ang isang swift task naman ay nagkakahalaga ng 3 credits at gumagamit ng mas mabilis, mas mababa ang gastos 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
Tekstong naglalarawan sa motion na bubuuin, hanggang 400 characters. Ibabalik ang 400 kapag mas mahaba ang teksto.
Name
mode
Type
string
default prime
Description
Ang motion model, na nagtatakda rin ng file format ng clip.
Mga magagamit na value:
- prime: mas mataas ang kalidad, nagbabalik ng FBX clip
- swift: mas mabilis at mas mura, nagbabalik ng BVH clip
Ibabalik ang 400 para sa anumang ibang value.
Name
duration
Type
number
Kinakailangan
Description
Ang target na haba ng clip sa segundo, mula 2 hanggang 10 sa pagtaas na 0.5, halimbawa 2, 2.5, o 3. Ibabalik ang 400 para sa anumang ibang value.

Mga ibinabalik na halaga

Ang result field ng response ay naglalaman ng ID ng bagong Text to Motion task.

Mga mode ng pagkabigo

Name
400 - Bad Request
Description
Hindi maaaring tumakbo ang request. Sinasabi ng error message kung anong problema ang natagpuan nito. Halimbawa:
- Missing o empty prompt: nawawala, blangko, o mas mahaba sa 400 characters ang prompt.
- Invalid mode: hindi prime o swift ang mode.
- Invalid duration: nawawala ang duration, wala sa saklaw na 2 hanggang 10, o hindi ito sumusunod sa 0.5 segundong pagtaas.
Ayusin ang request, pagkatapos ay ipadala muli. Tingnan ang Errors.
Name
401 - Unauthorized
Description
Nawawala o hindi valid ang API key. Suriin ang Authorization header.
Name
402 - Payment Required
Description
Halimbawa:
- Insufficient credits: Walang sapat na credits ang account para sa task na ito, o umabot na sa credit limit ang account. Suriin ang iyong credit balanse, pagkatapos ay subukan muli.
- Free plan: Nangangailangan ng bayad na plano ang paggawa ng task. I-upgrade ang iyong plano sa iyong subscription settings, pagkatapos ay subukan muli.
Name
403 - Forbidden
Description
Nai-flag ng content moderation ang prompt. Baguhin ang prompt, pagkatapos ay ipadala muli ang request.
Name
429 - Too Many Requests
Description
Nalagpasan mo ang iyong rate limit. Maghintay, pagkatapos ay subukan muli. Tingnan ang Rate limits.

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

Kumuha ng Text to Motion task

Ibinabalik ang isang Text to Motion task gamit ang ID nito.

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
Ang task ID mula sa create response.

Ibinabalik

Ang Text to Motion task object.

GET/openapi/v1/text-to-motion

Ilista ang Mga Gawain ng Text to Motion

Nagbabalik ito ng isang paginated na listahan ng iyong mga gawain ng Text to Motion, ang pinakabago muna. Upang mag-page sa listahan, gamitin ang page_num at page_size.

Ang tugon ay isang array ng mga Text to Motion task object.

Ang mga gawaing ginawa mo gamit ang API ay nananatili sa API at hindi lumalabas sa My Assets sa web app. Upang hanapin ang isang gawain na hindi mo na alam ang ID, gamitin ang endpoint na ito.

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

Mag-stream ng Text to Motion task

Nagsa-stream ng mga update ng Text to Motion task bilang 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 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
}

Mga Parameter

Name
id
Type
path
Description
Ang task ID mula sa create response.

Ibinabalik

Isang stream ng Text to Motion task objects bilang Server-Sent Events.

Taglay ng bawat message event ang buong task object. Habang PENDING o IN_PROGRESS ang task, walang laman ang mga result field ("" o 0), at 0 ang finished_at at expires_at. Upang masubaybayan ang task, bantayan ang status at progress.

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

I-delete ang isang Text to Motion task

Permanenteng binubura ang isang Text to Motion task, kasama na ang motion clip nito. Hindi mo na maibabalik pa ang pagbura.

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

Path parameters

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

Status ng task

Kapag binura mo ang isang PENDING na task, maibabalik ang credits na ginamit noong ginawa mo ito.

Hindi maaaring i-delete ang isang IN_PROGRESS na task. Magbabalik ang request ng 409 Conflict, at magpapatuloy ang pagtakbo ng task. Hindi nagre-refund si Meshy para sa isang task na nagsimula na, kaya kung ide-delete mo ito, mawawalan ka ng credits at ng resulta. Hintayin munang makarating ito sa SUCCEEDED, FAILED, o CANCELED, bago ito i-delete.

Ang pagbura ng isang task na nasa final status na (SUCCEEDED, FAILED, o CANCELED) ay hindi nagre-refund ng credits nito.

Mga ibabalik

200 OK kapag na-delete na ang task, o 409 Conflict kapag ang task ay IN_PROGRESS.

Ang Text to Motion task object

Ang Text to Motion task object ay naglalarawan ng paglikha ng isang motion clip. Nakapaloob dito ang status, ang progress, at ang clip kapag nagtagumpay ang task.

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
Ang task ID. Ituring itong isang opaque string, at huwag umasa sa format nito.
Name
type
Type
string
Description
Ang task type, laging text-to-motion.
Name
status
Type
string
Description
Ang status ng task, isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, o CANCELED.
Name
progress
Type
integer
Description
Kung gaano na katapos ang task, bilang isang porsyento mula 0 hanggang 100.
Name
created_at
Type
timestamp
Description
Oras na nilikha ang task, sa Unix milliseconds.
Name
started_at
Type
timestamp
Description
Oras na nagsimula ang task, sa Unix milliseconds. Ito ay 0 hanggang magsimula ang task.
Name
finished_at
Type
timestamp
Description
Oras na natapos ang task, sa Unix milliseconds. Ito ay 0 hanggang matapos ang task.
Name
expires_at
Type
timestamp
Description
Oras na mawawalan ng bisa ang mga result file ng task, sa Unix milliseconds. Ito ay 0 hanggang matapos ang task. Pinapanatili ni Meshy ang clip sa loob ng 3 araw matapos matapos ang task, kaya i-download ito bago sumapit iyon.
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga task na nauuna sa task na ito sa pila. Makabuluhan lamang ang value na ito habang PENDING ang task. Hindi isinasama ang field na ito kapag 0 ang value.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na ginamit ng task, 10 para sa prime mode o 3 para sa swift mode. Ito ay 0 para sa isang FAILED na task, dahil irre-refund ni Meshy ang credits kapag nabigo ang isang task.
Name
task_error
Type
object
Description
Ang mga detalye ng error kapag nabigo ang task, at null kung hindi. Tingnan ang Errors.
Name
result
Type
object
Description
Ang nalikhang motion clip kapag nagtagumpay ang task. Hanggang doon, naroroon ang mga field ngunit walang laman ("" o 0).
- Name
  motion_url
  Type
  string
  Description
  Download URL para sa motion clip. Pipirmahan muli ni Meshy ang URL sa bawat pagbasa, at mawawalan ito ng bisa kasabay ng retention window ng task.
- Name
  motion_format
  Type
  string
  Description
  Ang file format ng clip, fbx para sa prime mode o bvh para sa swift mode.
- Name
  duration_ms
  Type
  integer
  Description
  Ang haba ng clip, sa milliseconds.
- Name
  mode
  Type
  string
  Description
  Ang mode na ginamit ni Meshy upang likhain ang clip, prime o swift.