Text to Motion API

Jana klip pergerakan watak daripada huraian teks. Huraikan satu tindakan, seperti "watak melambai" atau "zombi berjalan tertatih-tatih ke hadapan", dan dapatkan klip pergerakan mentah. Anda boleh menyasarkan semula klip tersebut kepada watak yang telah di-rig dalam saluran paip atau alat DCC anda sendiri.

Output ialah klip pergerakan berdiri sendiri. Ia tidak memerlukan model watak, dan ia tidak dilampirkan kepada mana-mana satu. Untuk melakukan proses rigging pada watak terlebih dahulu, lihat Rigging API. Untuk menggunakan klip pada watak anda yang telah di-rig, hantar id tugas sebagai motion_task_id kepada Animasi API.

POST/openapi/v1/text-to-motion

Cipta tugas Text to Motion

Mencipta tugas Text to Motion, yang menjana klip gerakan daripada prompt teks.

Tugas ini dijalankan di latar belakang. Untuk tempoh biasa yang diambil oleh sesuatu tugas, lihat Masa pemprosesan.

Tugas prime berharga 10 kredit dan menggunakan model gerakan Meshy yang lebih berkualiti tinggi. Tugas swift berharga 3 kredit dan menggunakan model gerakan yang lebih pantas dan kos lebih rendah.

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

Parameter

Name
prompt
Type
string
Diperlukan
Description
Teks yang menerangkan gerakan untuk dijana, sehingga 400 aksara. Teks yang lebih panjang akan mengembalikan 400.
Name
mode
Type
string
lalai prime
Description
Model gerakan, yang juga menetapkan format fail klip.
Nilai yang tersedia:
- prime: kualiti lebih tinggi, mengembalikan klip FBX
- swift: lebih pantas dan lebih murah, mengembalikan klip BVH
Sebarang nilai lain akan mengembalikan 400.
Name
duration
Type
number
Diperlukan
Description
Panjang sasaran klip dalam saat, dari 2 hingga 10 dalam langkah 0.5, contohnya 2, 2.5, atau 3. Sebarang nilai lain akan mengembalikan 400.

Nilai pulangan

Medan result dalam respons mengandungi ID bagi tugas Text to Motion yang baharu.

Mod kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Mesej ralat menyatakan masalah yang ditemui. Contohnya:
- Prompt hilang atau kosong: prompt hilang, kosong, atau lebih panjang daripada 400 aksara.
- Mode tidak sah: mode bukan prime atau swift.
- Tempoh tidak sah: duration hilang, di luar julat 2 hingga 10, atau tidak berada pada langkah 0.5 saat.
Betulkan permintaan tersebut, kemudian hantar semula. Lihat Ralat.
Name
401 - Unauthorized
Description
Kunci API hilang atau tidak sah. Semak pengepala Authorization.
Name
402 - Payment Required
Description
Contohnya:
- Kredit tidak mencukupi: Akaun tidak mempunyai kredit yang mencukupi untuk tugas ini, atau akaun telah mencapai had kredit. Semak baki kredit anda, kemudian cuba semula.
- Pelan percuma: Mencipta tugas memerlukan pelan berbayar. Naik taraf pelan anda di tetapan langganan anda, kemudian cuba semula.
Name
403 - Forbidden
Description
Moderation kandungan menandakan prompt tersebut. Ubah prompt, kemudian hantar permintaan semula.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda. Tunggu, kemudian cuba semula. Lihat Had kadar.

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

Dapatkan tugas Text to Motion

Mengembalikan tugas Text to Motion berdasarkan ID-nya.

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
}

Parameter

Name
id
Type
path
Description
ID tugas daripada respons create.

Nilai Pulangan

Objek tugas Text to Motion.

GET/openapi/v1/text-to-motion

Senaraikan tugas Text to Motion

Mengembalikan senarai tugas Text to Motion anda secara bersebelah (paginated), bermula dengan yang terbaru. Untuk melayari senarai tersebut, gunakan page_num dan page_size.

Respons tersebut adalah array bagi objek tugas Text to Motion.

Tugas yang anda cipta melalui API kekal di dalam API dan tidak dipaparkan dalam My Assets pada aplikasi web. Untuk mencari tugas yang ID-nya tidak lagi anda miliki, gunakan endpoint ini.

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

Strim tugas Text to Motion

Menstrim kemas kini tugas Text to Motion sebagai 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
}

Parameter

Name
id
Type
path
Description
ID tugas daripada respons create.

Returns

Satu strim objek tugas Text to Motion sebagai Server-Sent Events.

Setiap acara message membawa objek tugas yang lengkap. Semasa tugas berstatus PENDING atau IN_PROGRESS, medan result adalah kosong ("" atau 0), dan finished_at serta expires_at adalah 0. Untuk mengikuti tugas, perhatikan status dan progress.

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

Padam tugas Text to Motion

Memadam tugas Text to Motion secara kekal, termasuk klip gerakannya. Anda tidak boleh membatalkan padaman.

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

Parameter laluan

Name
id
Type
path
Description
ID tugas yang hendak dipadam.

Status tugas

Memadam tugas PENDING akan memulangkan semula kredit yang digunakan semasa anda mencipta tugas tersebut.

Tugas IN_PROGRESS tidak boleh dipadam. Permintaan akan memulangkan 409 Conflict, dan tugas tersebut terus berjalan. Meshy tidak memulangkan semula kredit untuk tugas yang telah bermula, jadi memadamnya akan merugikan anda kredit mahupun hasilnya. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED, atau CANCELED, kemudian padamkannya.

Memadam tugas yang berada dalam status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak memulangkan semula kreditnya.

Pulangan

200 OK apabila tugas berjaya dipadam, atau 409 Conflict apabila tugas berstatus IN_PROGRESS.

Objek tugas Text to Motion

Objek tugas Text to Motion menerangkan penjanaan satu klip gerakan. Ia menyimpan status, progress, dan klip apabila tugas berjaya.

Ciri-ciri

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
ID tugas. Anggap ia sebagai rentetan legap, dan jangan bergantung pada formatnya.
Name
type
Type
string
Description
Jenis tugas, sentiasa text-to-motion.
Name
status
Type
string
Description
Status tugas, salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.
Name
progress
Type
integer
Description
Sejauh mana tugas telah selesai, sebagai peratusan dari 0 hingga 100.
Name
created_at
Type
timestamp
Description
Masa tugas dicipta, dalam milisaat Unix.
Name
started_at
Type
timestamp
Description
Masa tugas bermula, dalam milisaat Unix. Nilainya 0 sehingga tugas bermula.
Name
finished_at
Type
timestamp
Description
Masa tugas selesai, dalam milisaat Unix. Nilainya 0 sehingga tugas selesai.
Name
expires_at
Type
timestamp
Description
Masa fail hasil tugas tamat tempoh, dalam milisaat Unix. Nilainya 0 sehingga tugas selesai. Meshy menyimpan klip selama 3 hari selepas tugas selesai, jadi muat turunkannya sebelum itu.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas yang mendahului tugas ini dalam baris gilir. Nilai ini hanya bermakna semasa tugas berstatus PENDING. Medan ini ditinggalkan apabila nilainya 0.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas, 10 untuk mode prime atau 3 untuk mode swift. Nilainya 0 untuk tugas FAILED, kerana Meshy mengembalikan kredit apabila tugas gagal.
Name
task_error
Type
object
Description
Butiran ralat apabila tugas gagal, dan null jika sebaliknya. Lihat Ralat.
Name
result
Type
object
Description
Klip gerakan yang dijana apabila tugas berjaya. Sebelum itu, medan-medan ini hadir tetapi kosong ("" atau 0).
- Name
  motion_url
  Type
  string
  Description
  URL muat turun untuk klip gerakan. Meshy menandatangani URL semula pada setiap bacaan, dan ia tamat tempoh mengikut tempoh pengekalan tugas.
- Name
  motion_format
  Type
  string
  Description
  Format fail klip, fbx untuk mode prime atau bvh untuk mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  Panjang klip, dalam milisaat.
- Name
  mode
  Type
  string
  Description
  Mode yang digunakan oleh Meshy untuk menjana klip, prime atau swift.