API Animasi

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

POST/openapi/v1/animations

Create an Animation Task

Endpoint ini membolehkan anda membuat tugas baharu untuk menerapkan animasi pada karakter yang telah dirig sebelumnya — tindakan praset daripada pustaka animasi (action_id), beberapa tindakan praset digabungkan menjadi satu fail (action_ids), atau klip gerakan yang anda hasilkan dengan Text to Motion API (motion_task_id). Termasuk pilihan pasca-pemprosesan.

Tugas ini dijalankan di latar belakang. Untuk tempoh biasa yang diperlukan, lihat Processing Times.

Parameter

Name
rig_task_id
Type
string
Diperlukan
Description
id bagi tugas rigging yang berjaya diselesaikan (daripada POST /openapi/v1/rigging). Karakter daripada tugas ini akan dianimasikan.
Name
action_id
Type
integer
Description
Pengenal pasti bagi tindakan animasi praset yang hendak digunakan. Lihat Animation Library Reference untuk senarai lengkap animasi yang tersedia. Sediakan tepat satu daripada action_id, action_ids atau motion_task_id.
Name
action_ids
Type
array of integers
Description
Beberapa tindakan animasi praset yang digunakan sekali gus, dikembalikan sebagai satu fail tunggal yang mengandungi satu klip animasi bagi setiap tindakan — berguna untuk menggerakkan karakter daripada mesin keadaan (state machine) dalam enjin permainan. Sediakan 1 hingga 10 nilai action_id daripada Animation Library Reference; id mestilah unik. Dikenakan 3 kredit bagi setiap tindakan. Sediakan tepat satu daripada action_id, action_ids atau motion_task_id.
Menghantar action_ids dengan satu elemen adalah setara dengan menghantar nilai tersebut sebagai action_id.
Name
motion_task_id
Type
string
Description
id bagi tugas Text to Motion yang berjaya diselesaikan untuk digunakan sebagai ganti kepada tindakan praset. Klip yang dihasilkan akan disasarkan semula (retargeted) ke atas karakter yang telah dirig dan klip tersebut diambil snapshot pada masa penciptaan, jadi tugas ini tidak terjejas jika tugas sumber tamat tempoh atau dipadamkan kemudian. Aset tugas sumber disimpan selama 3 hari — gunakan klip tersebut sebelum ia tamat tempoh. Memerlukan rig biped. Sediakan tepat satu daripada action_id, action_ids atau motion_task_id.
Name
post_process
Type
object
Description
Pasca-pemprosesan pilihan untuk output animasi. Tinggalkan parameter ini 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 berkenaan apabila operation_type ialah change_fps. Nilai yang dibenarkan: 24, 25, 30, 60.

Dengan action_ids, tugas tersebut mengembalikan satu fail gabungan dan bukannya 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 berasingan.

Susunan klip: mengikut susunan tatasusunan action_ids, bukan susunan nombor id tersebut.
Nama klip: nama animasi dalam pustaka, sepadan dengan nama yang anda peroleh apabila mengeksport semua animasi karakter sebagai satu fail daripada aplikasi web Meshy. Jika dua id yang diminta menghasilkan nama klip yang sama, id yang kemudian akan ditambah akhiran dengan action_id-nya bagi mengekalkan keunikan nama.
Pasca-pemprosesan: diterapkan pada fail gabungan, bukan pada klip individu.

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

Returns

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

Failure Modes

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 disediakan.
- Parameter bercanggah: lebih daripada satu daripada action_id, action_ids dan motion_task_id disediakan — ketiga-tiganya saling eksklusif.
- Tugas rig tidak sah: rig_task_id tidak sah atau merujuk kepada tugas yang gagal/tidak wujud.
- ID tindakan tidak sah: action_id — atau salah satu entri action_ids — tidak sepadan dengan mana-mana animasi yang sah.
- Terlalu banyak tindakan: action_ids mengandungi lebih daripada 10 id.
- Tindakan pendua: 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 kuadruped akan ditolak.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk menjalankan tugas ini.
Name
404 - Not Found
Description
Tugas rigging yang dinyatakan oleh rig_task_id tidak dijumpai, tugas gerakan yang dinyatakan oleh motion_task_id tidak dijumpai, atau klip gerakan telah tamat tempoh (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 Semula Tugas Animasi

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

Parameter

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

Pulangan

Respons mengandungi objek Animation Task. 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 Tugasan Animasi

Endpoint ini memadamkan tugasan animasi secara kekal, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh dibuat asal.

Parameter Laluan

Name
id
Type
path
Description
ID bagi tugasan animasi yang hendak dipadamkan.

Status Tugasan

Tugasan yang masih PENDING akan dipadamkan dan kredit yang digunakan semasa penciptaan akan dikembalikan.

Tugasan yang sudah IN_PROGRESS tidak boleh dipadamkan: permintaan akan ditolak dengan 409 Conflict dan tugasan tersebut akan terus berjalan. Kredit bagi tugasan yang pekerja telah mula jalankan tidak boleh dikembalikan, jadi memadamkannya semasa ia sedang berjalan akan menyebabkan anda kehilangan kredit dan juga hasilnya. Tunggu sehingga ia mencapai SUCCEEDED, FAILED atau CANCELED, kemudian padamkannya.

Tugasan yang berada dalam keadaan akhir (SUCCEEDED, FAILED atau CANCELED) akan dipadamkan tanpa sebarang bayaran balik.

Mengembalikan

Mengembalikan 200 OK apabila berjaya, atau 409 Conflict apabila tugasan tersebut 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

Senaraikan Tugas Animasi

Mengembalikan senarai bertuku halaman bagi tugas animasi pemanggil, terbaharu dahulu. Penomboran halaman standard melalui page_num dan page_size.

Perhatikan bahawa tugas yang dicipta melalui API diuruskan melalui API — tugas tersebut tidak muncul dalam My Assets pada 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

Strim Tugasan Animasi

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

Parameter

Name
id
Type
path
Description
Pengecam unik untuk tugasan Animasi yang akan distrim.

Pulangan

Mengembalikan strim Objek Tugasan Animasi sebagai Server-Sent Events.

Untuk tugasan PENDING atau IN_PROGRESS, strim 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
}

Objek Tugas Animasi

Objek Tugas Animasi mewakili unit kerja untuk menerapkan animasi pada aksara yang mempunyai rig.

Ciri-ciri

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

Senarai Animasi

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

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

Endpoint ini 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 digunakan secara bersendirian — nama sub-kategori tidak unik merentas 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 melayari. Menerima paling banyak 200 id. Id yang tidak dimiliki oleh mana-mana animasi hanya tidak wujud dalam respons, jadi anda juga boleh menggunakan ini untuk menyemak sama ada id yang telah anda simpan masih tersedia.

Menggabungkan penapis

Penapis dikenakan bersama-sama — setiap satu mengecilkan hasil dengan lebih lanjut, jadi sesuatu animasi hanya dikembalikan jika ia memenuhi kesemuanya. Dalam satu penapis tunggal, pelbagai nilai memadankan mana-mana antaranya: search memadankan name atau key, dan action_ids memadankan mana-mana id dalam senarai.

Ini bermakna gabungan tanpa pertindihan akan mengembalikan tatasusunan kosong dan bukannya ralat. Tindakan 92 ialah "Double Combo Attack", sebuah 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 secara bersendirian.

Kembalian

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 tidak wujud dalam kedua-duanya. Jika anda menyimpan cache pustaka tersebut, segarkannya secara berkala supaya id yang telah dinyahtauliahkan tidak berlama-lama 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 apabila mencipta tugas animasi. Unik dan stabil, tetapi tidak berturutan — animasi yang dinyahaktifkan meninggalkan jurang dalam penomboran, jadi jangan sesekali anggap sesuatu julat id itu sah.
Name
name
Type
string
Description
Label mesra manusia, untuk paparan. Tidak unik: sesetengah animasi berkongsi nama yang sama dengan varian yang berbeza, jadi gunakan action_id atau key sebagai identiti.
Name
key
Type
string
Description
Slug unik dan stabil untuk animasi tersebut. Gunakannya apabila anda memerlukan pengecam bukan-nombor untuk menjadi kunci bagi 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"
}