API Teks kepada Gerakan

Jana klip gerakan watak daripada penerangan bahasa semula jadi. Terangkan satu tindakan — "seorang watak melambai", "zombi berjalan tergagap-gagap ke hadapan" — dan dapatkan klip gerakan mentah yang boleh anda sasarkan semula (retarget) kepada watak yang telah dibolehkan skeleton (rigged) dalam saluran kerja atau alat DCC anda sendiri.

Output adalah klip gerakan berdiri sendiri: ia tidak memerlukan, dan tidak dilampirkan kepada, mana-mana model watak. Untuk melakukan rigging pada watak terlebih dahulu, sila rujuk API Rigging. Untuk mengaplikasikan klip yang dijana ke atas watak berigging anda, hantarkan id tugas sebagai motion_task_id kepada API Animasi — aplikasikannya dalam tempoh pengekalan aset selama 3 hari.

POST/openapi/v1/text-to-motion

Cipta Tugasan Text to Motion

Endpoint ini mencipta tugasan baharu untuk menjana klip pergerakan daripada prompt teks.

Tugasan dengan mode prime memerlukan 10 kredit dan dijana menggunakan model pergerakan berkualiti tertinggi kami. Tugasan dengan mode swift memerlukan 3 kredit dan dijana dengan lebih pantas menggunakan model pergerakan ekonomi kami.

Parameter

Name
prompt
Type
string
Diperlukan
Description
Penerangan bahasa semula jadi bagi pergerakan yang hendak dijana. Maksimum 400 aksara.
Name
mode
Type
string
lalai prime
Description
Mode penjanaan pergerakan. Nilai yang tersedia: prime, swift. prime menghasilkan kualiti tertinggi dan mengeluarkan FBX; swift lebih pantas dan lebih murah serta mengeluarkan BVH.
Name
duration
Type
number
Diperlukan
Description
Tempoh sasaran klip pergerakan dalam saat. Antara 2 dan 10, dalam langkah 0.5 (contohnya 2, 2.5, 3, … 10).

Pemulangan

Sifat result bagi respons mengandungi id tugasan bagi tugasan Text to Motion yang baharu dicipta.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak boleh diterima. Punca biasa:
- Prompt hilang atau kosong: prompt tiada, kosong, atau melebihi 400 aksara.
- Mode tidak sah: mode bukan prime atau swift.
- Tempoh tidak sah: duration tiada, di luar julat 2–10, atau tidak mengikut langkah 0.5 saat.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melaksanakan tugasan ini.
Name
403 - Forbidden
Description
Prompt telah ditandakan oleh moderation kandungan.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda.

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

Retrieve a Text to Motion Task

Endpoint ini membolehkan anda mendapatkan semula tugas Text to Motion berdasarkan id tugas yang sah. Rujuk The Text to Motion Task Object untuk melihat sifat-sifat yang disertakan.

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas Text to Motion yang hendak didapatkan semula.

Nilai Pulangan

Respons mengandungi objek Text to Motion Task. Rujuk bahagian The Text to Motion Task Object untuk maklumat lanjut.

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

Senaraikan Tugas Text to Motion

Mengembalikan senarai tugas Text to Motion pemanggil yang telah dinomborkan halaman, dengan yang terbaharu dahulu. Penomboran halaman standard melalui page_num dan page_size.

Respons adalah array bagi objek Tugas Text to Motion.

Perhatikan bahawa tugas yang dicipta melalui API diuruskan melalui API — ia tidak dipaparkan dalam My Assets pada aplikasi web. Gunakan endpoint ini untuk mencari tugas yang ID-nya tidak lagi anda miliki.

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

Alirkan Tugas Text to Motion

Endpoint ini mengalirkan kemas kini masa nyata untuk tugas Text to Motion menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas Text to Motion yang hendak dialirkan.

Pulangan

Mengembalikan aliran The Text to Motion Task Objects sebagai Server-Sent Events.

Setiap peristiwa message membawa objek tugas yang lengkap. Semasa tugas berstatus PENDING atau IN_PROGRESS, medan result masih kosong ("" / 0) dan finished_at / expires_at adalah 0; pantau status dan 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

Padam Tugas Text to Motion

Endpoint ini memadam secara kekal tugas Text to Motion, termasuk klip gerakan yang dijana. Tindakan ini tidak boleh dibatalkan.

Parameter Laluan

Name
id
Type
path
Description
ID tugas Text to Motion yang hendak dipadam.

Nilai Pulangan

Mengembalikan 200 OK apabila berjaya.

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.

Objek Tugas Text to Motion

Objek Tugas Text to Motion mewakili unit kerja untuk menghasilkan klip pergerakan daripada prompt teks.

Ciri-ciri

Name
id
Type
string
Description
Pengecam unik untuk tugas tersebut.
Name
type
Type
string
Description
Jenis tugas. Nilainya ialah text-to-motion.
Name
status
Type
string
Description
Status tugas. Nilai yang mungkin: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress tugas (0-100).
Name
created_at
Type
timestamp
Description
Cap masa (milisaat sejak epoch) apabila tugas dicipta.
Cap masa mewakili bilangan milisaat yang berlalu sejak 1 Januari 1970 UTC, mengikut piawaian RFC 3339. Contohnya, Jumaat, 1 September 2023 12:00:00 PM GMT diwakili sebagai 1693569600000. Ini terpakai kepada semua cap masa dalam Meshy API.
Name
started_at
Type
timestamp
Description
Cap masa (milisaat sejak epoch) apabila tugas mula diproses. 0 jika belum bermula.
Name
finished_at
Type
timestamp
Description
Cap masa (milisaat sejak epoch) apabila tugas selesai. 0 jika belum selesai.
Name
expires_at
Type
timestamp
Description
Cap masa (milisaat sejak epoch) apabila aset hasil tugas akan luput. 0 sehingga tugas selesai. Klip yang dijana disimpan selama 3 hari selepas tugas selesai; muat turun sebelum ia luput.
Name
preceding_tasks
Type
integer
Description
Bilangan tugas terdahulu dalam giliran. Hanya bermakna jika status adalah PENDING; diabaikan apabila sifar.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugas ini. 10 untuk mode prime, 3 untuk mode swift. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan apabila gagal).
Name
task_error
Type
object
Description
Butiran ralat untuk tugas yang gagal; null melainkan tugas FAILED. Lihat Ralat untuk rujukan penuh objek task_error.
Name
result
Type
object
Description
Mengandungi klip pergerakan yang dijana sebaik sahaja tugas SUCCEEDED; sehingga itu medan-medan tersebut wujud tetapi kosong ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  URL boleh muat turun untuk klip pergerakan yang dijana. URL ditandatangani semula setiap kali dibaca dan akan luput mengikut tempoh penyimpanan tugas tersebut.
- Name
  motion_format
  Type
  string
  Description
  Format fail klip: fbx untuk mode prime, bvh untuk mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  Tempoh klip yang dijana dalam milisaat.
- Name
  mode
  Type
  string
  Description
  Mode yang digunakan untuk menjana klip: prime atau 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
}