API Animasi

Endpoint untuk menemui Animasi yang tersedia dan menggunakannya pada karakter yang mempunyai rig.

POST/openapi/v1/animations

Create an Animation Task

Endpoint ini membolehkan anda mencipta tugas baharu untuk menerapkan animasi pada watak yang telah di-rig sebelum ini — tindakan pratetap daripada pustaka animasi (action_id), beberapa tindakan pratetap yang digabungkan menjadi satu fail (action_ids), atau klip gerakan yang anda hasilkan dengan Text to Motion API (motion_task_id). Termasuk pilihan pasca-pemprosesan.

Parameter

Name
rig_task_id
Type
string
Diperlukan
Description
id bagi tugas rigging yang telah berjaya diselesaikan (daripada POST /openapi/v1/rigging). Watak daripada tugas ini akan dianimasikan.
Name
action_id
Type
integer
Description
Pengecam bagi tindakan animasi pratetap yang hendak diterapkan. Lihat Rujukan Pustaka Animasi untuk senarai lengkap animasi yang tersedia. Berikan tepat satu daripada action_id, action_ids atau motion_task_id.
Name
action_ids
Type
array of integers
Description
Beberapa tindakan animasi pratetap untuk diterapkan sekaligus, dikembalikan sebagai satu fail tunggal yang mengandungi satu klip animasi bagi setiap tindakan — berguna untuk menggerakkan watak daripada state machine dalam enjin permainan. Berikan 1 hingga 10 nilai action_id daripada Rujukan Pustaka Animasi; id mestilah unik. Kos 3 kredit bagi setiap tindakan. Berikan tepat satu daripada action_id, action_ids atau motion_task_id.
Memberikan action_ids dengan satu elemen adalah setara dengan memberikan nilai tersebut sebagai action_id.
Name
motion_task_id
Type
string
Description
id bagi tugas Text to Motion yang telah berjaya diselesaikan untuk diterapkan sebagai ganti tindakan pratetap. Klip yang dihasilkan disasarkan semula (retargeted) ke atas watak yang telah di-rig dan klip tersebut diambil snapshot pada masa penciptaan, jadi tugas ini tidak terjejas jika tugas sumber kemudiannya luput atau dipadam. Aset tugas sumber disimpan selama 3 hari — terapkan klip tersebut sebelum ia luput. Memerlukan rig biped. Berikan tepat satu daripada action_id, action_ids atau motion_task_id.
Name
post_process
Type
object
Description
Pasca-pemprosesan pilihan untuk output animasi. Tinggalkan ia untuk menerima fail animasi standard.

Hanya berlaku apabila post_process is set

Name
operation_type
Type
string
Diperlukan
Description
Jenis operasi yang hendak dilakukan. Nilai yang tersedia: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
lalai 30
Description
Kadar bingkai sasaran. Hanya terpakai apabila operation_type ialah change_fps. Nilai yang dibenarkan: 24, 25, 30, 60.

Dengan action_ids, tugas mengembalikan satu fail gabungan dan bukan satu fail bagi setiap tindakan: animation_glb_url dan animation_fbx_url masing-masing menunjuk kepada satu aset tunggal yang mengandungi setiap tindakan yang diminta sebagai klip yang berasingan.

Susunan klip: susunan array action_ids, bukan susunan angka bagi id tersebut.
Nama klip: nama animasi tersebut dalam pustaka, sepadan dengan nama yang anda perolehi apabila mengeksport semua animasi bagi sesuatu watak sebagai satu fail daripada aplikasi web Meshy. Jika dua id yang diminta merujuk kepada nama klip yang sama, id yang kemudian akan diberi imbuhan action_idnya untuk mengekalkan keunikan nama.
Pasca-pemprosesan: diterapkan pada fail gabungan, bukan pada klip individu.

Dengan motion_task_id, retarget mungkin menghasilkan animasi GLB sahaja. Jika anda meminta post_process dan tiada FBX tersedia, tugas akan gagal dengan task_error dan kredit anda akan dikembalikan secara automatik; tanpa post_process, tugas berjaya dan animation_fbx_url akan kosong.

Hasil Kembalian

Sifat result bagi respons mengandungi id tugas bagi tugas animasi yang baharu dicipta.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak dapat diterima. Punca biasa:
- Parameter hilang: rig_task_id tiada, atau tiada satu pun daripada action_id, action_ids dan motion_task_id diberikan.
- Parameter bercanggah: lebih daripada satu daripada action_id, action_ids dan motion_task_id diberikan — ia saling eksklusif.
- Tugas rig tidak sah: rig_task_id tidak sah atau merujuk kepada tugas yang gagal/tidak wujud.
- ID tindakan tidak sah: satu action_id — atau satu entri dalam action_ids — tidak sepadan dengan animasi yang sah.
- Terlalu banyak tindakan: action_ids mengandungi lebih daripada 10 id.
- Tindakan berganda: action_ids mengandungi id yang sama lebih daripada sekali.
- Tugas gerakan belum sedia: tugas motion_task_id belum lagi SUCCEEDED.
- Rig tidak disokong: motion_task_id memerlukan rig biped; rig quadruped ditolak.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melaksanakan tugas ini.
Name
404 - Not Found
Description
Tugas rigging yang ditentukan oleh rig_task_id tidak dijumpai, tugas gerakan yang ditentukan oleh motion_task_id tidak dijumpai, atau klip gerakan telah luput (aset tugas sumber disimpan selama 3 hari).
Name
429 - Too Many Requests
Description
Anda telah melebihi had kadar anda.

Request

POST

/openapi/v1/animations

# Animate a rigged model with required params only
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92
  }'

# Apply several preset actions and get one file with one clip per action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_ids": [10, 25, 92]
  }'

# Apply a generated Text to Motion clip instead of a preset action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "motion_task_id": "018c425b-b2c6-727e-d333-3c1887i9h791"
  }'

# With post-processing to change FPS
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92,
    "post_process": {
      "operation_type": "change_fps",
      "fps": 24
    }
  }'

Response

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

GET/openapi/v1/animations/:id

Dapatkan Tugas Animasi

Endpoint ini membolehkan anda mendapatkan tugas animasi dengan id tugas yang sah. Rujuk The Animation Task Object untuk melihat sifat-sifat yang disertakan.

Parameter

Name
id
Type
path
Description
Pengecam unik untuk tugas animasi yang hendak didapatkan.

Pulangan

Respons mengandungi objek Tugas Animasi. Semak bahagian The Animation Task Object untuk maklumat lanjut.

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791

curl https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791 
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.glb?Expires=...",
    "animation_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.fbx?Expires=...",
    "processed_usdz_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed.usdz?Expires=...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_armature.fbx?Expires=...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_60fps.fbx?Expires=..."
  },
  "preceding_tasks": 0
}

DELETE/openapi/v1/animations/:id

Padam Tugas Animasi

Endpoint ini memadamkan tugas animasi secara kekal, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh dibatalkan.

Parameter Laluan

Name
id
Type
path
Description
ID tugas animasi yang hendak dipadam.

Status Tugas

Tugas yang masih PENDING akan dipadam dan kredit yang digunakan pada masa penciptaan akan dikembalikan.

Tugas yang sudah IN_PROGRESS tidak boleh dipadam: permintaan akan ditolak dengan 409 Conflict dan tugas tersebut akan terus berjalan. Kredit bagi tugas yang telah mula diproses oleh worker tidak boleh dikembalikan, jadi memadamnya semasa ia sedang berjalan akan mengakibatkan anda kehilangan kredit dan juga hasilnya. Tunggu sehingga ia mencapai status SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugas yang berada dalam status terminal (SUCCEEDED, FAILED atau CANCELED) akan dipadam tanpa bayaran balik.

Pulangan

Memulangkan 200 OK jika berjaya, atau 409 Conflict apabila tugas berstatus IN_PROGRESS.

Request

DELETE

/openapi/v1/animations/018b314a-a1b5-716d-c222-2f1776f7f579

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/animations/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -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."
}

GET/openapi/v1/animations

List Animation Tasks

Mengembalikan senarai tugas animasi milik pemanggil yang telah dinomborkan halaman, yang terbaru dahulu. Penomboran halaman standard melalui page_num dan page_size.

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

Request

GET

/openapi/v1/animations

curl "https://api.meshy.ai/openapi/v1/animations?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/animations/:id/stream

Alirkan Tugas Animasi

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

Parameter

Name
id
Type
path
Description
Pengecam unik untuk tugas Animasi yang hendak dialirkan.

Pemulangan

Memulangkan aliran Objek Tugas Animasi sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, aliran respons hanya akan menyertakan medan progress dan status yang diperlukan.

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/stream

curl -N https://api.meshy.ai/openapi/v1/animations/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 event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Animation Task Object structure
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}

The Animation Task Object

Objek Animation Task mewakili unit kerja untuk menerapkan animasi kepada watak yang telah dirig.

Ciri-ciri

Name
id
Type
string
Description
Pengenal unik untuk tugasan.
Name
type
Type
string
Description
Jenis tugasan Animation. Nilainya ialah animate.
Name
status
Type
string
Description
Status tugasan. Nilai yang mungkin: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress tugasan (0-100).
Name
created_at
Type
timestamp
Description
Cap masa (milisaat sejak epoch) apabila tugasan 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 tugasan mula diproses. 0 jika belum bermula.
Name
finished_at
Type
timestamp
Description
Cap masa (milisaat sejak epoch) apabila tugasan selesai. 0 jika belum selesai.
Name
expires_at
Type
timestamp
Description
Cap masa (milisaat sejak epoch) apabila aset hasil tugasan luput.
Name
task_error
Type
object
Description
Butiran ralat untuk tugasan yang gagal. Lihat Errors untuk rujukan penuh objek task_error.
Name
consumed_credits
Type
integer
Description
Bilangan kredit yang digunakan oleh tugasan ini. Hadir apabila status tugasan ialah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugasan FAILED (kredit dikembalikan apabila gagal).
Name
result
Type
object
Description
Mengandungi URL animasi output jika tugasan SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  URL boleh muat turun untuk animasi dalam format GLB. Bagi tugasan yang dicipta dengan action_ids, fail tunggal ini mengandungi setiap aksi yang diminta sebagai klip berasingan.
- Name
  animation_fbx_url
  Type
  string
  Description
  URL boleh muat turun untuk animasi dalam format FBX. Bagi tugasan yang dicipta dengan action_ids, fail tunggal ini mengandungi setiap aksi yang diminta sebagai klip berasingan.
- Name
  processed_usdz_url
  Type
  string
  Description
  URL boleh muat turun untuk animasi yang telah diproses dalam format USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  URL boleh muat turun untuk rangka yang telah diproses dalam format FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  URL boleh muat turun untuk animasi dengan FPS yang telah diubah dalam format FBX (contohnya, jika operasi change_fps digunakan).
Name
preceding_tasks
Type
integer
Description
Bilangan tugasan terdahulu dalam baris gilir. Bermakna hanya jika status ialah PENDING.

Example Animation Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}

GET/openapi/v1/animations/library

Senaraikan Animasi

Mengembalikan setiap animasi dalam pustaka, disusun mengikut action_id. Respons adalah senarai lengkap dan bukannya satu halaman, jadi satu panggilan sudah memadai untuk mengisi pemilih tindakan. Penapis akan mempersempit hasil; abaikan semuanya untuk mendapatkan segalanya.

Untuk menyemak imbas katalog yang sama secara visual, dengan pratonton animasi bagi setiap tindakan, lihat rujukan Pustaka Animasi.

Endpoint ini adalah percuma — ia tidak menggunakan sebarang kredit.

Parameter

Name
search
Type
string
Description
Padanan subrentetan tanpa mengira huruf besar/kecil pada name atau key. Dipadankan secara literal, jadi % dan _ adalah aksara biasa dan bukannya kad bebas.
Name
category
Type
string
Description
Padanan tepat pada category.
Nilai yang tersedia:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
Padanan tepat pada sub_category. Boleh diterima dengan sendirinya — nama sub-kategori tidak unik merentasi kategori (Transitioning muncul di bawah kedua-dua Fighting dan DailyActions), jadi tanpa category penapis akan memadankan sub-kategori tersebut di mana-mana sahaja ia muncul.
Name
action_ids
Type
string
Description
Senarai nilai action_id yang dipisahkan koma untuk dikembalikan, bagi menyelesaikan id tertentu dan bukannya menyemak imbas. Menerima paling banyak 200 id. Id yang tiada animasi yang membawanya hanya akan tiada dalam respons, jadi anda juga boleh menggunakan ini untuk menyemak sama ada id yang telah anda simpan masih tersedia.

Menggabungkan penapis

Penapis digunakan bersama-sama — setiap satu mempersempit hasil dengan lebih lanjut, jadi animasi hanya dikembalikan jika ia memenuhi semua penapis tersebut. Dalam satu penapis, pelbagai nilai boleh memadankan mana-mana satu daripadanya: search memadankan name atau key, dan action_ids memadankan mana-mana id dalam senarai.

Ini bermakna gabungan yang tiada pertindihan akan mengembalikan tatasusunan kosong dan bukannya ralat. Tindakan 92 ialah "Double Combo Attack", satu animasi Fighting:

?action_ids=92&category=Fighting mengembalikan tindakan 92.
?action_ids=92&category=Dancing mengembalikan [] — ia bukan animasi Dancing.
?action_ids=92&search=walk mengembalikan [] — namanya tidak sepadan dengan walk.

Untuk mendapatkan animasi tertentu tanpa mengira kategorinya, hantar action_ids dengan sendirinya.

Mengembalikan

Mengembalikan senarai Objek Animasi.

Setiap action_id yang dikembalikan di sini diterima oleh Cipta Tugas Animasi di atas, dan setiap id yang diterimanya dikembalikan di sini. Animasi yang telah dinyahtauliahkan tiada dalam kedua-duanya. Jika anda menyimpan cache pustaka, muat semula secara berkala supaya id yang telah dinyahtauliahkan tidak berlarutan dalam pemilih anda.

Request

GET

/openapi/v1/animations/library

curl "https://api.meshy.ai/openapi/v1/animations/library?category=Fighting" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "action_id": 4,
    "name": "Attack",
    "key": "Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Attack.gif"
  },
  {
    "action_id": 92,
    "name": "Double Combo Attack",
    "key": "Double_Combo_Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
  }
]

Objek Animasi

Name
action_id
Type
integer
Description
Nilai yang perlu dihantar sebagai action_id semasa mencipta tugas animasi. Unik dan stabil, tetapi tidak berterusan — animasi yang telah dinyahaktifkan meninggalkan jurang dalam penomboran, jadi jangan sekali-kali menganggap sesuatu julat id itu sah.
Name
name
Type
string
Description
Label mesra manusia, untuk paparan. Tidak unik: sesetengah animasi berkongsi nama dengan varian yang berbeza, jadi gunakan action_id atau key sebagai identiti.
Name
key
Type
string
Description
Slug stabil yang unik untuk animasi tersebut. Gunakannya apabila anda memerlukan pengenal pasti bukan-nombor untuk mengunci storan anda sendiri.
Name
category
Type
string
Description
Pengelompokan peringkat atas, contohnya Fighting.
Name
sub_category
Type
string
Description
Pengelompokan dalam kategori tersebut, contohnya AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL bagi GIF beranimasi yang mempratonton aksi tersebut, sesuai untuk dipaparkan terus dalam pemilih anda sendiri.

Example Animation Object

{
  "action_id": 92,
  "name": "Double Combo Attack",
  "key": "Double_Combo_Attack",
  "category": "Fighting",
  "sub_category": "AttackingwithWeapon",
  "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
}