API Teks ke Gerakan

Hasilkan klip gerakan karakter dari deskripsi bahasa alami. Jelaskan sebuah aksi — "seorang karakter melambaikan tangan", "sebuah zombie sedang berjalan tertatih-tatih ke depan" — dan terima klip gerakan mentah yang dapat Anda sesuaikan dengan karakter ber-rig dalam pipeline atau alat DCC Anda sendiri.

Outputnya adalah klip gerakan mandiri: tidak memerlukan, dan tidak terhubung ke, model karakter. Untuk melakukan rigging karakter terlebih dahulu, lihat API Rigging.

POST/openapi/v1/text-to-motion

Membuat Tugas Teks ke Gerakan

Endpoint ini membuat tugas baru untuk menghasilkan klip gerakan dari prompt teks.

Tugas dengan mode prime membutuhkan biaya 10 kredit dan menghasilkan kualitas tertinggi dengan model gerakan kami. Tugas dengan mode swift membutuhkan biaya 3 kredit dan menghasilkan lebih cepat dengan model gerakan ekonomis kami.

Parameter

Name
prompt
Type
string
Wajib
Description
Deskripsi dalam bahasa alami tentang gerakan yang akan dihasilkan. Maksimum 400 karakter.
Name
mode
Type
string
default prime
Description
Mode generasi gerakan. Nilai yang tersedia: prime, swift. prime menghasilkan kualitas tertinggi dan output FBX; swift lebih cepat dan lebih murah dan output BVH.
Name
duration
Type
number
Wajib
Description
Durasi target dari klip gerakan dalam detik. Antara 2 dan 10, dalam langkah 0.5 (misalnya 2, 2.5, 3, … 10).

Hasil

Properti result dari respons berisi id tugas dari tugas Teks ke Gerakan 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 dari 400 karakter.
- Mode tidak valid: mode bukan prime atau swift.
- Durasi tidak valid: duration hilang, di luar 2–10, atau tidak pada langkah 0.5 detik.
Name
401 - Unauthorized
Description
Autentikasi gagal. Silakan periksa kunci API Anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melakukan tugas ini.
Name
403 - Forbidden
Description
Prompt ditandai oleh moderation konten.
Name
429 - Too Many Requests
Description
Anda telah melebihi batas laju Anda.

Request

POST

/openapi/v1/text-to-motion

# Hasilkan klip gerakan dengan parameter yang diperlukan saja
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
  }'

# Hasilkan klip cepat dan ekonomis dengan mode Swift
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 Tugas Text to Motion

Endpoint ini memungkinkan Anda untuk mengambil tugas Text to Motion dengan id tugas yang valid. Lihat Objek Tugas Text to Motion untuk melihat properti yang disertakan.

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas Text to Motion yang akan diambil.

Pengembalian

Respons berisi objek Tugas Text to Motion. Periksa bagian Objek Tugas Text to Motion 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 paginasi dari tugas Text to Motion pemanggil, yang terbaru terlebih dahulu. Paginasi standar melalui page_num dan page_size.

Responnya adalah array dari Objek Tugas Text to Motion.

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

Permintaan

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

Respon

[
  {
    "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
    "type": "text-to-motion",
    "status": "SUCCEEDED",
    "...": "..."
  }
]

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

Streaming Tugas Teks ke Gerakan

Endpoint ini mengalirkan pembaruan real-time untuk tugas Teks ke Gerakan menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengenal unik untuk tugas Teks ke Gerakan yang akan di-stream.

Mengembalikan

Mengembalikan aliran Objek Tugas Teks ke Gerakan sebagai Server-Sent Events.

Setiap acara message membawa objek tugas penuh. Ketika tugas berstatus PENDING atau IN_PROGRESS, bidang result masih kosong ("" / 0) dan finished_at / expires_at adalah 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

// Contoh acara error
event: error
data: {
  "status_code": 404,
  "message": "Tugas tidak ditemukan"
}

// Acara pesan membawa objek tugas penuh pada setiap tahap; bidang hasil
// tetap kosong sampai tugas berhasil.
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: { // Contoh item stream tugas SUCCEEDED, mencerminkan struktur Objek Tugas Teks ke Gerakan
  "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 Tugas Teks ke Gerakan

Endpoint ini secara permanen menghapus tugas Teks ke Gerakan, termasuk klip gerakan yang dihasilkan. Tindakan ini tidak dapat dibatalkan.

Parameter Jalur

Name
id
Type
path
Description
ID dari tugas Teks ke Gerakan yang ingin dihapus.

Mengembalikan

Mengembalikan 200 OK jika sukses.

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 Teks ke Gerakan

Objek Tugas Teks ke Gerakan mewakili unit kerja untuk menghasilkan klip gerakan dari sebuah teks prompt.

Properti

Name
id
Type
string
Description
Identifikasi unik untuk tugas.
Name
type
Type
string
Description
Jenis tugas. Nilainya adalah text-to-motion.
Name
status
Type
string
Description
Status dari tugas. Nilai yang mungkin: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Kemajuan dari tugas (0-100).
Name
created_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) ketika tugas dibuat.
Stempel waktu mewakili jumlah milidetik yang telah berlalu sejak 1 Januari 1970 UTC, mengikuti standar RFC 3339. Misalnya, Jumat, 1 September 2023, 12:00:00 PM GMT diwakili sebagai 1693569600000. Ini berlaku untuk semua stempel waktu dalam Meshy API.
Name
started_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) ketika tugas mulai diproses. 0 jika tidak dimulai.
Name
finished_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) ketika tugas selesai. 0 jika belum selesai.
Name
expires_at
Type
timestamp
Description
Stempel waktu (milidetik sejak epoch) ketika aset hasil tugas kedaluwarsa. 0 hingga tugas selesai. Klip yang dihasilkan disimpan selama 3 hari setelah tugas selesai; unduh sebelum kedaluwarsa.
Name
preceding_tasks
Type
integer
Description
Jumlah tugas sebelumnya dalam antrean. Bermakna hanya jika statusnya PENDING; diabaikan ketika nol.
Name
consumed_credits
Type
integer
Description
Jumlah kredit yang digunakan oleh tugas ini. 10 untuk mode prime, 3 untuk mode swift. Mengembalikan 0 untuk tugas yang FAILED (kredit akan dikembalikan jika gagal).
Name
task_error
Type
object
Description
Detail kesalahan untuk tugas yang gagal; null kecuali tugas FAILED. Lihat Kesalahan untuk referensi lengkap task_error objek.
Name
result
Type
object
Description
Mengandung klip gerakan yang dihasilkan setelah tugas SUCCEEDED; hingga saat itu bidangnya hadir tetapi kosong ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  URL yang dapat diunduh untuk klip gerakan yang dihasilkan. URL tersebut ditandatangani ulang pada setiap pembacaan dan kedaluwarsa dengan jangka waktu penyimpanan tugas.
- Name
  motion_format
  Type
  string
  Description
  Format file dari 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.

Contoh Objek Tugas Teks ke Gerakan

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