API para sa Teksto tungo sa Galaw

Bumuo ng mga motion clip ng karakter mula sa mga natural na salaysay. Maglarawan ng aksyon — "isang karakter na kumakaway", "isang zombie na pasuray-suray na umuunlad" — at makatanggap ng isang raw motion clip na maaari mong i-retarget sa mga karakter na may rig sa iyong sariling pipeline o mga DCC tool.

Ang output ay isang hiwalay na motion clip: hindi ito nangangailangan, at hindi nakakabit, sa isang karakter na modelo. Upang mag-rig ng karakter muna, tingnan ang Rigging API.

POST/openapi/v1/text-to-motion

Gumawa ng Text to Motion Task

Ang endpoint na ito ay lumilikha ng bagong task para makagawa ng motion clip mula sa isang text prompt.

Ang isang task na may mode na prime ay nagkakahalaga ng 10 credits at lumilikha 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 lumilikha gamit ang aming matipid na motion model.

Mga Parametro

Name
prompt
Type
string
Kinakailangan
Description
Isang deskripsyon sa natural na wika ng motion na gagawin. Maximum na 400 na karakter.
Name
mode
Type
string
default prime
Description
Ang paraan ng motion generation. Mga magagamit na halaga: 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 mga hakbang ng 0.5 (halimbawa 2, 2.5, 3, … 10).

Mga Resulta

Ang result na ari-arian ng tugon ay naglalaman ng id ng task na bagong nalikhang Text to Motion task.

Mga Kapalpakan

Name
400 - Bad Request
Description
Ang kahilingan ay hindi katanggap-tanggap. Mga karaniwang sanhi:
- Nawawala o walang laman na prompt: nawawala ang prompt, blangko, o mas mahaba kaysa sa 400 na karakter.
- Hindi wasto na mode: ang mode ay hindi prime o swift.
- Hindi wasto na duration: nawawala ang duration, labas sa 2–10, o hindi nasa 0.5 na hakbang ng segundo.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Pakisuri ang iyong API key.
Name
402 - Payment Required
Description
Kulang ang credits para gawin ang task na ito.
Name
403 - Forbidden
Description
Ang prompt ay napansin ng content moderation.
Name
429 - Too Many Requests
Description
Lumampas ka na sa iyong rate limit.

Request

POST

/openapi/v1/text-to-motion

# Gumawa ng motion clip na may kinakailangang mga parametro lamang
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
  }'

# Gumawa ng mabilis at matipid na clip gamit ang 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

I-retrieve ang Task ng Text to Motion

Ang endpoint na ito ay nagbibigay-daan sa iyo na i-retrieve ang isang Text to Motion task gamit ang isang valid na task id. Tingnan ang The Text to Motion Task Object upang makita kung aling mga katangian ang kasama.

Mga Parameter

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

Ibinabalik

Ang tugon ay naglalaman ng Text to Motion Task na object. Suriin ang seksyon na 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

Listahan ng Mga Gawain sa Text to Motion

Nagbabalik ng isang nakapagpapahintulot na listahan ng mga gawain sa Text to Motion ng tumatawag, pinakabago muna. Karaniwang pagination sa pamamagitan ng page_num at page_size.

Ang tugon ay isang array ng mga Text to Motion Task na bagay.

Tandaan na ang mga gawaing nilikha sa pamamagitan ng API ay pinapamahalaan sa pamamagitan ng API — hindi ito lumilitaw sa My Assets ng web app. Gamitin ang endpoint na ito upang hanapin ang gawain na ang ID ay wala ka na.

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 isang Text to Motion Task

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

Mga Parameter

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

Mga Ibinabalik

Ibinabalik nito ang stream ng The Text to Motion Task Objects bilang Server-Sent Events.

Bawat message na kaganapan ay nagdadala ng buong object ng task. Habang ang task ay nasa PENDING o IN_PROGRESS, ang mga field ng result ay nananatiling 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

// Halimbawa ng error na kaganapan
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Ang mga mensahe na kaganapan ay nagdadala ng buong object ng task sa bawat yugto; ang mga field ng result ay nananatiling walang laman hanggang sa magtagumpay ang task.
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: { // Halimbawa ng SUCCEEDED na item ng task stream, na sumasalamin sa istruktura ng 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
}

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

Tanggalin ang isang Gawain sa Teksto sa Motion

Ang endpoint na ito ay permanenteng itatanggal ang isang Gawain sa Teksto sa Motion, kasama ang nabuo na motion clip. Ang aksyong ito ay hindi na mababawi.

Mga Parameter ng Path

Name
id
Type
path
Description
Ang ID ng Gawain sa Teksto sa Motion na itatanggalin.

Mga Return

Nagbabalik ng 200 OK kung 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

// Nagbabalik ng 200 Ok kung matagumpay.

Ang Objek na Task ng Teksto sa Galaw

Ang objek na Task ng Teksto sa Galaw ay kumakatawan sa yunit ng trabaho para sa pagbuo ng motion clip mula sa isang text prompt.

Mga Katangian

Name
id
Type
string
Description
Natatanging tagatukoy para sa task.
Name
type
Type
string
Description
Uri ng task. Ang halaga ay text-to-motion.
Name
status
Type
string
Description
Status ng task. Mga posibleng halaga: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progreso ng task (0-100).
Name
created_at
Type
timestamp
Description
Timestamp (milliseconds mula sa epoch) kung kailan nilikha ang task.
Ang timestamp ay kumakatawan sa bilang ng milliseconds na lumipas mula Enero 1, 1970 UTC, ayon sa RFC 3339 na pamantayan. Halimbawa, Biyernes, Setyembre 1, 2023 12:00:00 PM GMT ay kinakatawan bilang 1693569600000. Ito'y naaangkop sa lahat ng timestamp sa Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp (milliseconds mula sa epoch) kung kailan nagsimula ang pagproseso ng task. 0 kung hindi pa nagsisimula.
Name
finished_at
Type
timestamp
Description
Timestamp (milliseconds mula sa epoch) kung kailan natapos ang task. 0 kung hindi pa natatapos.
Name
expires_at
Type
timestamp
Description
Timestamp (milliseconds mula sa epoch) kung kailan mag-e-expire ang mga resulta ng task assets. 0 hangga't hindi natatapos ang task. Ang nabuong clip ay itinatago sa loob ng 3 araw matapos ang pagtatapos ng task; i-download ito bago mag-expire.
Name
preceding_tasks
Type
integer
Description
Bilang ng mga naunang task sa queue. May kahulugan lamang kung ang status ay PENDING; hindi isinama 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 task na FAILED (ang credits ay nire-refund kapag pumalya).
Name
task_error
Type
object
Description
Mga detalye ng error para sa mga task na pumalya; null maliban kung ang task ay FAILED. Tingnan ang Errors para sa kompletong sanggunian ng task_error na objek.
Name
result
Type
object
Description
Naglalaman ng nabuo na motion clip kapag ang task ay SUCCEEDED; hanggang noon ang mga patlang ay nandoon ngunit walang laman ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  Downloadable na URL para sa nabuo na motion clip. Ang URL ay muling nilalagdaan sa bawat pagbasa at mag-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 nabuo na clip sa milliseconds.
- Name
  mode
  Type
  string
  Description
  Ang mode na ginamit sa pagbuo ng clip: prime o swift.

Halimbawa ng Task na Objek ng Teksto sa Galaw

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