Text to Motion API

Hasilkan klip gerakan karakter dari deskripsi bahasa alami. Deskripsikan sebuah aksi — "karakter melambaikan tangan", "zombie berjalan terhuyung-huyung ke depan" — dan dapatkan klip gerakan mentah yang dapat Anda retarget ke karakter yang sudah di-rig dalam pipeline atau alat DCC Anda sendiri.

Outputnya adalah klip gerakan mandiri: tidak memerlukan, dan tidak terpasang pada, model karakter. Untuk melakukan rigging karakter terlebih dahulu, lihat Rigging API. Untuk menerapkan klip yang dihasilkan ke karakter yang sudah di-rig milik Anda, kirimkan id task sebagai motion_task_id ke Animation API — terapkan dalam jendela waktu retensi aset selama 3 hari.

POST/openapi/v1/text-to-motion

Membuat Task Text to Motion

Endpoint ini membuat task baru untuk menghasilkan klip motion dari sebuah prompt teks.

Task dengan mode prime membutuhkan 10 kredit dan menghasilkan dengan model motion berkualitas tertinggi kami. Task dengan mode swift membutuhkan 3 kredit dan menghasilkan lebih cepat dengan model motion ekonomis kami.

Parameter

Name
prompt
Type
string
Wajib
Description
Deskripsi dalam bahasa natural mengenai motion yang akan dihasilkan. Maksimal 400 karakter.
Name
mode
Type
string
default prime
Description
Mode pembuatan motion. Nilai yang tersedia: prime, swift. prime menghasilkan kualitas tertinggi dan menghasilkan output FBX; swift lebih cepat dan lebih murah serta menghasilkan output BVH.
Name
duration
Type
number
Wajib
Description
Target durasi klip motion dalam detik. Antara 2 dan 10, dengan langkah 0.5 (misalnya 2, 2.5, 3, … 10).

Hasil

Properti result pada respons berisi id task Text to Motion yang baru dibuat.

Mode Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Penyebab umum:
- Prompt hilang atau kosong: prompt hilang, kosong, atau lebih panjang dari 400 karakter.
- Mode tidak valid: mode bukan prime atau swift.
- Durasi tidak valid: duration hilang, di luar rentang 2–10, atau tidak berada pada langkah 0.5 detik.
Name
401 - Unauthorized
Description
Autentikasi gagal. Silakan periksa kunci API Anda.
Name
402 - Payment Required
Description
Kredit tidak cukup untuk melakukan task ini.
Name
403 - Forbidden
Description
Prompt ditandai oleh moderation konten.
Name
429 - Too Many Requests
Description
Anda telah melampaui batas laju 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

Mengambil Task Text to Motion

Endpoint ini memungkinkan Anda mengambil task Text to Motion berdasarkan id task yang valid. Lihat The Text to Motion Task Object untuk melihat properti apa saja yang disertakan.

Parameter

Name
id
Type
path
Description
Pengidentifikasi unik untuk task Text to Motion yang ingin diambil.

Returns

Respons berisi objek Text to Motion Task. Lihat bagian The Text to Motion Task Object untuk detailnya.

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

Daftar Tugas Text to Motion

Mengembalikan daftar tugas Text to Motion milik pemanggil secara terpaginasi, dimulai dari yang terbaru. Paginasi standar melalui page_num dan page_size.

Respons berupa array dari objek Task Text to Motion.

Perhatikan bahwa tugas yang dibuat melalui API dikelola melalui API — tugas tersebut tidak muncul di My Assets pada aplikasi web. Gunakan endpoint ini untuk menemukan tugas yang ID-nya sudah tidak Anda miliki lagi.

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

Melakukan Streaming Task Text to Motion

Endpoint ini melakukan streaming pembaruan secara real-time untuk task Text to Motion menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengidentifikasi unik untuk task Text to Motion yang akan di-stream.

Returns

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

Setiap event message membawa objek task secara lengkap. Selama task berstatus PENDING atau IN_PROGRESS, field result masih kosong ("" / 0) dan finished_at / expires_at bernilai 0; perhatikan 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

Menghapus Task Text to Motion

Endpoint ini menghapus task Text to Motion secara permanen, termasuk klip motion yang dihasilkan. Tindakan ini tidak dapat dibatalkan.

Parameter Path

Name
id
Type
path
Description
ID dari task Text to Motion yang akan dihapus.

Status Task

Task yang masih berstatus PENDING akan dihapus dan kredit yang digunakan saat pembuatan akan dikembalikan.

Task yang sudah berstatus IN_PROGRESS tidak dapat dihapus: permintaan akan ditolak dengan 409 Conflict dan task tetap berjalan. Kredit untuk task yang sudah mulai dikerjakan oleh worker tidak dapat dikembalikan, sehingga menghapusnya di tengah proses akan membuat Anda kehilangan kredit sekaligus hasilnya. Tunggu hingga mencapai status SUCCEEDED, FAILED, atau CANCELED, baru kemudian hapus.

Task dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) akan dihapus tanpa pengembalian kredit.

Pengembalian

Mengembalikan 200 OK jika berhasil, atau 409 Conflict ketika task berstatus IN_PROGRESS.

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

Objek Task Text to Motion

Objek Task Text to Motion merepresentasikan unit kerja untuk menghasilkan klip gerakan dari sebuah prompt teks.

Properties

Name
id
Type
string
Description
Pengidentifikasi unik untuk task.
Name
type
Type
string
Description
Jenis task. Nilainya adalah text-to-motion.
Name
status
Type
string
Description
Status task. Nilai yang memungkinkan: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress task (0-100).
Name
created_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) saat task dibuat.
Stempel waktu merepresentasikan jumlah milidetik yang berlalu sejak 1 Januari 1970 UTC, mengikuti standar RFC 3339. Sebagai contoh, Jumat, 1 September 2023 12:00:00 PM GMT direpresentasikan sebagai 1693569600000. Hal ini berlaku untuk semua stempel waktu di Meshy API.
Name
started_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) saat task mulai diproses. 0 jika belum dimulai.
Name
finished_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) saat task selesai. 0 jika belum selesai.
Name
expires_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) saat aset hasil task berakhir masa berlakunya (expire). 0 sampai task selesai. Klip yang dihasilkan disimpan selama 3 hari setelah task selesai; unduh sebelum masa berlakunya berakhir.
Name
preceding_tasks
Type
integer
Description
Jumlah task yang mendahului dalam antrean. Hanya berarti jika status adalah PENDING; dihilangkan jika nol.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang digunakan oleh task ini. 10 untuk mode prime, 3 untuk mode swift. Mengembalikan 0 untuk task yang FAILED (kredit dikembalikan jika gagal).
Name
task_error
Type
object
Description
Detail kesalahan untuk task yang gagal; null kecuali task tersebut FAILED. Lihat Kesalahan untuk referensi lengkap objek task_error.
Name
result
Type
object
Description
Berisi klip gerakan yang dihasilkan setelah task SUCCEEDED; sebelum itu, field-nya ada tetapi kosong ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  URL yang dapat diunduh untuk klip gerakan yang dihasilkan. URL ditandatangani ulang pada setiap pembacaan dan akan berakhir masa berlakunya sesuai jendela retensi task.
- Name
  motion_format
  Type
  string
  Description
  Format file klip: fbx untuk mode prime, bvh untuk mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  Durasi klip yang dihasilkan dalam milidetik.
- Name
  mode
  Type
  string
  Description
  Mode yang digunakan untuk menghasilkan 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
}