API Teks ke Gerakan

Jana klip gerakan watak dari penerangan bahasa semula jadi. Huraikan aksi — "watak melambai", "zombi berjalan terhuyung ke depan" — dan terima klip gerakan mentah yang anda boleh sasarkan semula pada watak yang telah di-rig dalam saluran paip atau alat DCC anda sendiri.

Output adalah klip gerakan berdiri sendiri: ia tidak memerlukan atau dilampirkan kepada model watak. Untuk rig watak terlebih dahulu, lihat API Rigging.

POST/openapi/v1/text-to-motion

Cipta Tugas Teks ke Gerakan

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

Tugas dengan mode prime memerlukan 10 kredit dan menghasilkan dengan model gerakan berkualiti tertinggi kami. Tugas dengan mode swift memerlukan 3 kredit dan menghasilkan lebih cepat dengan model gerakan ekonomi kami.

Parameter

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

Memulangkan

Properti result dari respons mengandungi id tugas Teks ke Gerakan yang baru dicipta.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Penyebab biasa:
- Prompt hilang atau kosong: prompt tidak disertakan, kosong, atau lebih panjang daripada 400 aksara.
- Mode tidak sah: mode bukan prime atau swift.
- Tempoh tidak sah: duration tidak disertakan, di luar julat 2–10, atau tidak pada 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 tugas ini.
Name
403 - Forbidden
Description
Prompt telah ditandakan oleh moderation kandungan.
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda.

Permintaan

POST

/openapi/v1/text-to-motion

# Hasilkan klip gerakan dengan hanya parameter yang diperlukan
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": "seorang watak melambai",
    "duration": 3
  }'

# Hasilkan klip yang cepat dan ekonomi 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": "seorang watak melambai",
    "mode": "swift",
    "duration": 4.5
  }'

Response

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

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

Dapatkan Tugas Teks ke Gerakan

Endpoint ini membolehkan anda untuk mendapatkan tugas Teks ke Gerakan dengan memberikan id tugas yang sah. Rujuk kepada Objek Tugas Teks ke Gerakan untuk melihat ciri-ciri yang disertakan.

Parameter

Name
id
Type
path
Description
Pengenal pasti unik untuk tugas Teks ke Gerakan yang akan diambil.

Pulangan

Respons mengandungi objek Tugas Teks ke Gerakan. Semak seksyen Objek Tugas Teks ke Gerakan untuk butiran lanjut.

Permintaan

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

Respons

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

Senarai Tugasan Teks kepada Gerakan

Mengembalikan senarai dengan penomboran halaman bagi tugasan Teks kepada Gerakan pemanggil, yang terbaru dahulu. Penomboran halaman standard melalui page_num dan page_size.

Respons adalah satu array objek Teks kepada Gerakan.

Perhatikan bahawa tugasan yang dicipta melalui API diuruskan melalui API — ia tidak muncul dalam bahagian Aset saya di aplikasi web. Gunakan endpoint ini untuk mencari tugasan yang ID-nya anda tidak lagi 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}"

Respons

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

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

Strim Tugas Teks ke Pergerakan

Endpoint ini menstrim kemas kini masa nyata untuk satu tugasan Teks ke Pergerakan menggunakan Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Pengecam unik untuk tugasan Teks ke Pergerakan yang hendak distrim.

Mengembalikan

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

Setiap acara message membawa objek tugas penuh. Semasa tugas adalah PENDING atau IN_PROGRESS, medan result masih kosong ("" / 0) dan finished_at/expires_at adalah 0; perhatikan status dan progress.

Permintaan

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

Strim Respons

// Contoh acara ralat
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Acara mesej membawa objek tugas penuh di setiap peringkat; medan hasil
// kekal kosong sehingga tugas berjaya.
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 strim tugasan SUCCEEDED, mencerminkan struktur Objek Tugas Teks ke Pergerakan
  "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 Teks ke Gerakan

Endpoint ini memadamkan tugas Teks ke Gerakan secara kekal, termasuk klip gerakan yang dijana. Tindakan ini adalah tidak dapat dipulihkan.

Parameter Laluan

Name
id
Type
path
Description
ID bagi tugas Teks ke Gerakan untuk dipadamkan.

Mengembalikan

Mengembalikan 200 OK jika berjaya.

Permintaan

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

Respons

// Mengembalikan 200 Ok jika berjaya.

Objek Tugas Teks kepada Gerakan

Objek Tugas Teks kepada Gerakan mewakili unit kerja untuk menghasilkan klip gerakan daripada prompt teks.

Sifat

Name
id
Type
string
Description
Pengecam unik untuk tugas ini.
Name
type
Type
string
Description
Jenis tugas. Nilainya ialah text-to-motion.
Name
status
Type
string
Description
Status tugas. Nilai yang berpotensi: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Kemajuan tugas (0-100).
Name
created_at
Type
timestamp
Description
Cap masa (milisaat sejak epoch) apabila tugas ini dicipta.
Cap masa mewakili bilangan milisaat yang berlalu sejak 1 Januari 1970 UTC, mengikut piawaian RFC 3339. Sebagai contoh, 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 tidak 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 tamat tempoh. 0 sehingga tugas selesai. Klip yang dihasilkan disimpan selama 3 hari selepas tugas selesai; muat turunnya sebelum ia tamat tempoh.
Name
preceding_tasks
Type
integer
Description
Kiraan tugas sebelumnya dalam baris gilir. Bermakna hanya jika status adalah PENDING; tidak ditunjukkan jika kosong.
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 FAILED (kredit akan dikembalikan jika gagal).
Name
task_error
Type
object
Description
Butiran ralat untuk tugas yang gagal; null kecuali tugas FAILED. Lihat Ralat untuk rujukan penuh objek task_error.
Name
result
Type
object
Description
Mengandungi klip gerakan yang dijana selepas tugas SUCCEEDED; sehingga itu medan ada tetapi kosong ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  URL yang boleh dimuat turun untuk klip gerakan yang dijana. URL ini ditandatangani semula setiap kali baca dan tamat tempoh bersama tetingkap pengekalan tugas.
- Name
  motion_format
  Type
  string
  Description
  Format fail untuk 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 di mana klip dihasilkan: prime atau swift.

Contoh Objek Tugas Teks kepada 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
}