API Animasi

Endpoint untuk menemui animasi yang tersedia dan menerapkannya pada watak yang telah di-rig.

POST/openapi/v1/animations

Cipta Tugasan Animasi

Endpoint ini membolehkan anda mencipta tugasan baharu untuk menerapkan tindakan animasi tertentu pada watak yang telah melalui rigging sebelumnya. Termasuk pilihan pasca-pemprosesan.

Parameter

Name
rig_task_id
Type
string
Diperlukan
Description
id bagi tugasan rigging yang berjaya diselesaikan (daripada POST /openapi/v1/rigging). Watak daripada tugasan ini akan dianimasikan.
Name
action_id
Type
integer
Diperlukan
Description
Pengecam bagi tindakan animasi yang hendak diterapkan. Lihat Rujukan Pustaka animasi untuk senarai lengkap animasi yang tersedia.
Name
post_process
Type
object
Description
Pasca-pemprosesan pilihan untuk output animasi. Tinggalkan 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 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.

Mengembalikan

Sifat result dalam respons mengandungi id tugasan bagi tugasan animasi yang baru dicipta.

Mod Kegagalan

Name
400 - Bad Request
Description
Permintaan tidak boleh diterima. Punca lazim:
- Parameter tiada: rig_task_id atau action_id tiada.
- Tugasan rig tidak sah: rig_task_id tidak sah atau merujuk kepada tugasan yang gagal/tidak wujud.
- ID tindakan tidak sah: action_id tidak sepadan dengan animasi yang sah.
Name
401 - Unauthorized
Description
Pengesahan gagal. Sila semak kunci API anda.
Name
402 - Payment Required
Description
Kredit tidak mencukupi untuk melaksanakan tugasan ini.
Name
404 - Not Found
Description
Tugasan rigging yang ditentukan oleh rig_task_id tidak ditemui.
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
  }'

# 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 berdasarkan id tugas yang sah. Rujuk Objek Tugas Animasi untuk melihat sifat yang disertakan.

Parameter

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

Mengembalikan

Respons mengandungi objek Tugas Animasi. Semak bahagian Objek Tugas Animasi untuk butiran.

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 dipadamkan.

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/:id/stream

Strim Tugas Animasi

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

Parameter

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

Mengembalikan

Mengembalikan strim Objek Tugas Animasi sebagai Server-Sent Events.

Untuk tugas 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 menggunakan animasi pada watak yang telah di-rig.

Sifat

Name
id
Type
string
Description
Pengecam unik untuk tugas.
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 telah berlalu sejak 1 Januari 1970 UTC, mengikut standard 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 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 objek task_error penuh.
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 dibayar balik apabila 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.
- Name
  animation_fbx_url
  Type
  string
  Description
  URL yang boleh dimuat turun untuk animasi dalam format FBX.
- 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 (cth., jika operasi change_fps digunakan).
Name
preceding_tasks
Type
integer
Description
Bilangan tugas terdahulu dalam giliran. 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
}