Text to Motion API

Hasilkan klip gerakan karakter dari deskripsi teks. Deskripsikan sebuah aksi, seperti "karakter yang melambaikan tangan" atau "zombi yang berjalan terseok-seok ke depan", dan dapatkan klip gerakan mentah. Anda dapat melakukan retarget klip tersebut ke karakter yang sudah memiliki rig di pipeline atau alat DCC Anda sendiri.

Keluarannya adalah klip gerakan yang berdiri sendiri. Klip ini tidak memerlukan model karakter, dan tidak terikat pada satu model pun. Untuk melakukan rigging pada karakter terlebih dahulu, lihat Rigging API. Untuk menerapkan sebuah klip ke karakter yang sudah di-rig, kirim id tugas sebagai motion_task_id ke Animation API.

POST/openapi/v1/text-to-motion

Membuat task Text to Motion

Membuat task Text to Motion, yang menghasilkan klip gerakan dari prompt teks.

Task berjalan di latar belakang. Untuk informasi berapa lama task biasanya berlangsung, lihat Waktu pemrosesan.

Task prime berbiaya 10 kredit dan menggunakan model gerakan Meshy berkualitas lebih tinggi. Task swift berbiaya 3 kredit dan menggunakan model gerakan yang lebih cepat dan lebih murah.

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
Wajib
Description
Teks yang mendeskripsikan gerakan yang akan dihasilkan, hingga 400 karakter. Teks yang lebih panjang mengembalikan 400.
Name
mode
Type
string
default prime
Description
Model gerakan, yang juga menentukan format file klip.
Nilai yang tersedia:
- prime: kualitas lebih tinggi, mengembalikan klip FBX
- swift: lebih cepat dan murah, mengembalikan klip BVH
Nilai lainnya akan mengembalikan 400.
Name
duration
Type
number
Wajib
Description
Target panjang klip dalam detik, dari 2 hingga 10 dengan kelipatan 0.5, misalnya 2, 2.5, atau 3. Nilai lainnya akan mengembalikan 400.

Hasil

Kolom result pada respons menyimpan ID dari task Text to Motion yang baru.

Mode kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat dijalankan. Pesan kesalahan menunjukkan masalah yang ditemukan. Misalnya:
- Prompt kosong atau tidak ada: prompt tidak ada, kosong, atau lebih panjang dari 400 karakter.
- Mode tidak valid: mode bukan prime atau swift.
- Durasi tidak valid: duration tidak ada, di luar rentang 2 hingga 10, atau tidak berada pada kelipatan 0.5 detik.
Perbaiki permintaan, lalu kirim ulang. Lihat Kesalahan.
Name
401 - Unauthorized
Description
Kunci API tidak ada atau tidak valid. Periksa header Authorization.
Name
402 - Payment Required
Description
Misalnya:
- Kredit tidak cukup: Akun tidak memiliki cukup kredit untuk task ini, atau akun telah mencapai batas kredit. Periksa saldo kredit Anda, lalu coba lagi.
- Paket gratis: Membuat task memerlukan paket berbayar. Tingkatkan paket Anda di pengaturan langganan, lalu coba lagi.
Name
403 - Forbidden
Description
Moderation konten menandai prompt tersebut. Ubah prompt, lalu kirim permintaan lagi.
Name
429 - Too Many Requests
Description
Anda melampaui batas laju. Tunggu, lalu coba lagi. Lihat Batas laju.

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

Mendapatkan task Text to Motion

Mengembalikan task 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 task dari respons pembuatan.

Returns

Objek task Text to Motion.

GET/openapi/v1/text-to-motion

Mendapatkan Daftar Tugas Text to Motion

Mengembalikan daftar tugas Text to Motion Anda dengan paginasi, yang terbaru terlebih dahulu. Untuk menelusuri halaman daftar, gunakan page_num dan page_size.

Respons berupa array dari objek tugas Text to Motion.

Tugas yang Anda buat dengan API tetap berada di API dan tidak muncul di My Assets pada aplikasi web. Untuk menemukan tugas yang ID-nya sudah tidak Anda miliki lagi, 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

Streaming tugas Text to Motion

Melakukan streaming pembaruan 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 dari respons pembuatan.

Returns

Sebuah stream objek tugas Text to Motion sebagai Server-Sent Events.

Setiap event message membawa objek tugas secara lengkap. Selama tugas berstatus PENDING atau IN_PROGRESS, kolom result kosong ("" atau 0), dan finished_at serta expires_at bernilai 0. Untuk mengikuti perkembangan tugas, perhatikan status dan progress.

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

Menghapus tugas Text to Motion

Menghapus tugas Text to Motion secara permanen, termasuk klip motion-nya. Penghapusan tidak dapat dibatalkan.

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 path

Name
id
Type
path
Description
ID tugas yang akan dihapus.

Status tugas

Menghapus tugas PENDING akan mengembalikan kredit yang digunakan saat Anda membuatnya.

Tugas IN_PROGRESS tidak dapat dihapus. Permintaan akan mengembalikan 409 Conflict, dan tugas tersebut akan terus berjalan. Meshy tidak mengembalikan kredit untuk tugas yang sudah dimulai, jadi menghapusnya akan membuat Anda kehilangan baik kredit maupun hasilnya. Tunggu hingga tugas tersebut mencapai status SUCCEEDED, FAILED, atau CANCELED, lalu hapus.

Menghapus tugas dengan status akhir (SUCCEEDED, FAILED, atau CANCELED) tidak mengembalikan kreditnya.

Returns

200 OK ketika tugas berhasil dihapus, atau 409 Conflict ketika tugas berstatus IN_PROGRESS.

Objek tugas Text to Motion

Objek tugas Text to Motion menjelaskan pembuatan satu klip gerakan. Objek ini menyimpan status, progress, dan klip ketika tugas berhasil.

Properties

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. Perlakukan sebagai string buram, dan jangan bergantung pada formatnya.
Name
type
Type
string
Description
Jenis tugas, selalu text-to-motion.
Name
status
Type
string
Description
Status tugas, salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, atau CANCELED.
Name
progress
Type
integer
Description
Seberapa banyak tugas telah selesai, dalam persentase dari 0 hingga 100.
Name
created_at
Type
timestamp
Description
Waktu tugas dibuat, dalam milidetik Unix.
Name
started_at
Type
timestamp
Description
Waktu tugas dimulai, dalam milidetik Unix. Nilainya 0 sampai tugas dimulai.
Name
finished_at
Type
timestamp
Description
Waktu tugas selesai, dalam milidetik Unix. Nilainya 0 sampai tugas selesai.
Name
expires_at
Type
timestamp
Description
Waktu file hasil tugas kedaluwarsa, dalam milidetik Unix. Nilainya 0 sampai tugas selesai. Meshy menyimpan klip selama 3 hari setelah tugas selesai, jadi unduh sebelum waktu tersebut.
Name
preceding_tasks
Type
integer
Description
Jumlah tugas yang berada di depan tugas ini dalam antrean. Nilai ini hanya berarti selama tugas berstatus PENDING. Kolom ini tidak disertakan ketika nilainya 0.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang digunakan oleh tugas, 10 untuk mode prime atau 3 untuk mode swift. Nilainya 0 untuk tugas FAILED, karena Meshy mengembalikan kredit saat tugas gagal.
Name
task_error
Type
object
Description
Detail kesalahan saat tugas gagal, dan null jika tidak. Lihat Kesalahan.
Name
result
Type
object
Description
Klip gerakan yang dihasilkan ketika tugas berhasil. Sebelum itu, kolom-kolomnya tetap ada tetapi kosong ("" atau 0).
- Name
  motion_url
  Type
  string
  Description
  URL unduhan untuk klip gerakan. Meshy menandatangani ulang URL ini pada setiap pembacaan, dan URL ini kedaluwarsa sesuai jendela retensi tugas.
- Name
  motion_format
  Type
  string
  Description
  Format file klip, fbx untuk mode prime atau bvh untuk mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  Panjang klip, dalam milidetik.
- Name
  mode
  Type
  string
  Description
  Mode yang digunakan Meshy untuk menghasilkan klip, prime atau swift.