API Animasi

Endpoint untuk mencari animasi yang tersedia dan menggunakannya pada watak yang mempunyai rig.

POST/openapi/v1/animations

Cipta Tugas Animasi

Endpoint ini membolehkan anda mencipta tugas baharu untuk mengaplikasikan animasi pada watak yang telah menjalani rigging sebelumnya — sama ada tindakan pratetap daripada pustaka animasi (action_id) atau klip gerakan yang anda jana 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 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 digunakan. Lihat Rujukan Pustaka Animasi untuk senarai lengkap animasi yang tersedia. Berikan tepat satu daripada action_id atau motion_task_id.
Name
motion_task_id
Type
string
Description
id bagi tugas Text to Motion yang berjaya diselesaikan untuk digunakan sebagai ganti tindakan pratetap. Klip yang dijana akan diretarget ke atas watak yang telah menjalani rigging dan klip tersebut diambil snapshot pada masa penciptaan, jadi tugas ini tidak akan terjejas jika tugas sumber kemudiannya tamat tempoh atau dipadam. Aset tugas sumber disimpan selama 3 hari — gunakan klip tersebut sebelum ia tamat tempoh. Memerlukan rig biped. Berikan tepat satu daripada action_id atau motion_task_id.
Name
post_process
Type
object
Description
Pasca-pemprosesan pilihan untuk output animasi. Abaikan 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 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.

Nilai Pulangan

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

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak boleh diterima. Punca biasa:
- Parameter hilang: rig_task_id tiada, atau kedua-dua action_id dan motion_task_id tidak disediakan.
- Parameter bercanggah: kedua-dua action_id dan motion_task_id telah disediakan — kedua-duanya 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 tidak sepadan dengan mana-mana animasi yang sah.
- Tugas gerakan belum sedia: tugas motion_task_id masih belum SUCCEEDED.
- Rig tidak disokong: motion_task_id memerlukan rig biped; rig quadruped akan 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 dinyatakan oleh rig_task_id tidak ditemui, tugas gerakan yang dinyatakan oleh motion_task_id tidak ditemui, 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 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 memadam tugas Animasi secara kekal, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh dibatalkan.

Parameter Laluan

Name
id
Type
path
Description
ID bagi tugas Animasi yang hendak dipadam.

Pulangan

Mengembalikan 200 OK apabila berjaya.

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

// Returns 200 Ok on success.

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
Pengecam unik untuk tugas ini.
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) apabila tugas dicipta.
Cap masa mewakili bilangan milisaat yang berlalu sejak 1 Januari 1970 UTC, mengikut piawaian RFC 3339. Contohnya, 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 belum 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.
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 dikembalikan semula apabila gagal).
Name
result
Type
object
Description
Mengandungi URL animasi output jika tugas SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  URL boleh muat turun untuk animasi dalam format GLB.
- Name
  animation_fbx_url
  Type
  string
  Description
  URL boleh muat turun untuk animasi dalam format FBX.
- 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 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
}