Animation API

Mga endpoint para sa pagtuklas ng mga available na animation at paglalapat ng mga ito sa mga karakter na may rig.

POST/openapi/v1/animations

Gumawa ng Animation Task

Pinapayagan ka ng endpoint na ito na gumawa ng bagong task upang ilapat ang isang partikular na animation action sa isang character na dati nang na-rig. May kasamang mga opsyon sa post-processing.

Mga parameter

Name
rig_task_id
Type
string
Kinakailangan
Description
Ang id ng isang matagumpay na nakumpletong rigging task (mula sa POST /openapi/v1/rigging). Ang character mula sa task na ito ang ia-animate.
Name
action_id
Type
integer
Kinakailangan
Description
Ang identifier ng animation action na ilalapat. Tingnan ang Sanggunian ng Animation Library para sa kumpletong listahan ng mga available na animation.
Name
post_process
Type
object
Description
Opsyonal na post-processing para sa animation output. Huwag itong isama upang matanggap ang karaniwang animation files.

Naaangkop lamang kapag post_process is set

Name
operation_type
Type
string
Kinakailangan
Description
Ang uri ng operation na isasagawa. Mga available na value: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
default 30
Description
Ang target na frame rate. Naaangkop lamang kapag ang operation_type ay change_fps. Mga pinapayagang value: 24, 25, 30, 60.

Mga Ibinabalik

Naglalaman ang result property ng response ng task id ng bagong ginawang animation task.

Mga Failure Mode

Name
400 - Bad Request
Description
Hindi katanggap-tanggap ang request. Mga karaniwang sanhi:
- Nawawalang parameter: Nawawala ang rig_task_id o action_id.
- Invalid na rig task: Invalid ang rig_task_id o tumutukoy ito sa isang failed/hindi umiiral na task.
- Invalid na action ID: Ang action_id ay hindi tumutugma sa isang valid na animation.
Name
401 - Unauthorized
Description
Nabigo ang authentication. Pakisuri ang iyong API key.
Name
402 - Payment Required
Description
Hindi sapat ang credits upang maisagawa ang task na ito.
Name
404 - Not Found
Description
Hindi nahanap ang rigging task na tinukoy ng rig_task_id.
Name
429 - Too Many Requests
Description
Lumampas ka na sa iyong rate limit.

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

Kunin ang isang Animation Task

Pinapayagan ka ng endpoint na ito na kunin ang isang animation task gamit ang valid na task id. Sumangguni sa The Animation Task Object upang makita kung aling mga property ang kasama.

Mga Parameter

Name
id
Type
path
Description
Natatanging identifier para sa animation task na kukunin.

Mga Ibinabalik

Naglalaman ang response ng Animation Task object. Tingnan ang seksyong The Animation Task Object para sa mga detalye.

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

Burahin ang isang Gawain sa Animation

Permanenteng binubura ng endpoint na ito ang isang gawain sa Animation, kabilang ang lahat ng kaugnay na modelo at data. Hindi na mababawi ang aksyong ito.

Mga Parameter ng Path

Name
id
Type
path
Description
Ang ID ng gawain sa Animation na buburahin.

Mga Ibinabalik

Nagbabalik ng 200 OK kapag matagumpay.

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

I-stream ang isang Animation Task

Ang endpoint na ito ay nag-stream ng real-time na mga update para sa isang Animation task gamit ang Server-Sent Events (SSE).

Mga Parameter

Name
id
Type
path
Description
Natatanging identifier para sa Animation task na i-stream.

Mga Ibinabalik

Nagbabalik ng stream ng Mga Animation Task Object bilang Server-Sent Events.

Para sa mga task na PENDING o IN_PROGRESS, isasama lamang ng response stream ang kinakailangang mga field na progress at status.

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
}

Ang Object ng Animation Task

Ang object na Animation Task ay kumakatawan sa yunit ng trabaho para sa paglalapat ng Animation sa isang character na may rig.

Mga Property

Name
id
Type
string
Description
Natatanging identifier para sa task.
Name
type
Type
string
Description
Uri ng Animation task. Ang value ay animate.
Name
status
Type
string
Description
Status ng task. Mga posibleng value: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
progress ng task (0-100).
Name
created_at
Type
timestamp
Description
timestamp (milliseconds mula noong epoch) kung kailan ginawa ang task.
Ang timestamp ay kumakatawan sa bilang ng milliseconds na lumipas mula Enero 1, 1970 UTC, ayon sa RFC 3339 standard. Halimbawa, ang Biyernes, Setyembre 1, 2023 12:00:00 PM GMT ay kinakatawan bilang 1693569600000. Nalalapat ito sa lahat ng timestamp sa Meshy API.
Name
started_at
Type
timestamp
Description
timestamp (milliseconds mula noong epoch) kung kailan nagsimulang iproseso ang task. 0 kung hindi pa nagsisimula.
Name
finished_at
Type
timestamp
Description
timestamp (milliseconds mula noong epoch) kung kailan natapos ang task. 0 kung hindi pa tapos.
Name
expires_at
Type
timestamp
Description
timestamp (milliseconds mula noong epoch) kung kailan mag-e-expire ang mga asset ng resulta ng task.
Name
task_error
Type
object
Description
Mga detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa kumpletong reference ng object na task_error.
Name
consumed_credits
Type
integer
Description
Ang bilang ng credits na nakonsumo ng task na ito. Naroroon kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga FAILED task (ibinabalik ang credits kapag nabigo).
Name
result
Type
object
Description
Naglalaman ng mga output Animation URL kung ang task ay SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  Nada-download na URL para sa Animation sa format na GLB.
- Name
  animation_fbx_url
  Type
  string
  Description
  Nada-download na URL para sa Animation sa format na FBX.
- Name
  processed_usdz_url
  Type
  string
  Description
  Nada-download na URL para sa naprosesong Animation sa format na USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  Nada-download na URL para sa naprosesong armature sa format na FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  Nada-download na URL para sa Animation na may binagong FPS sa format na FBX (hal., kung ginamit ang operation na change_fps).
Name
preceding_tasks
Type
integer
Description
Ang bilang ng mga nauunang task sa queue. Makabuluhan lamang kung ang status ay 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
}