Animation API

Endpoints for discovering available animations and applying them to rigged characters.

POST/openapi/v1/animations

Create an Animation Task

This endpoint allows you to create a new task to apply a specific animation action to a previously rigged character. Includes post-processing options.

Parameters

Name
rig_task_id
Type
string
Required
Description
The id of a successfully completed rigging task (from POST /openapi/v1/rigging). The character from this task will be animated.
Name
action_id
Type
integer
Required
Description
The identifier of the animation action to apply. See the Animation Library Reference for a complete list of available animations.
Name
post_process
Type
object
Description
Parameters for post-processing animation files.
- Name
  operation_type
  Type
  string
  Required
  Description
  The type of operation to perform. Available values: change_fps, fbx2usdz, extract_armature.
- Name
  fps
  Type
  integer
  default 30
  Description
  The target frame rate. Applicable only when operation_type is change_fps. Allowed values: 24, 25, 30, 60.

Returns

The result property of the response contains the task id of the newly created animation task.

Failure Modes

Name
400 - Bad Request
Description
The request was unacceptable. Common causes:
- Missing parameter: rig_task_id or action_id is missing.
- Invalid rig task: The rig_task_id is invalid or refers to a failed/non-existent task.
- Invalid action ID: The action_id does not correspond to a valid animation.
Name
401 - Unauthorized
Description
Authentication failed. Please check your API key.
Name
402 - Payment Required
Description
Insufficient credits to perform this task.
Name
404 - Not Found
Description
The rigging task specified by rig_task_id was not found.
Name
429 - Too Many Requests
Description
You have exceeded your 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

Retrieve an Animation Task

This endpoint allows you to retrieve an animation task given a valid task id. Refer to The Animation Task Object to see which properties are included.

Parameters

Name
id
Type
path
Description
Unique identifier for the animation task to retrieve.

Returns

The response contains the Animation Task object. Check The Animation Task Object section for details.

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": ""
  },
  "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

Delete an Animation Task

This endpoint permanently deletes an animation task, including all associated models and data. This action is irreversible.

Path Parameters

Name
id
Type
path
Description
The ID of the animation task to delete.

Returns

Returns 200 OK on success.

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

Stream an Animation Task

This endpoint streams real-time updates for an Animation task using Server-Sent Events (SSE).

Parameters

Name
id
Type
path
Description
Unique identifier for the Animation task to stream.

Returns

Returns a stream of The Animation Task Objects as Server-Sent Events.

For PENDING or IN_PROGRESS tasks, the response stream will only include necessary progress and status fields.

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": ""
  },
  "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

The Animation Task object represents the work unit for applying an animation to a rigged character.

Properties

Name
id
Type
string
Description
Unique identifier for the task.
Name
type
Type
string
Description
Type of the Animation task. The value is animate.
Name
status
Type
string
Description
Status of the task. Possible values: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress of the task (0-100).
Name
created_at
Type
timestamp
Description
Timestamp (milliseconds since epoch) when the task was created.
A timestamp represents the number of milliseconds elapsed since January 1, 1970 UTC, following the RFC 3339 standard. For example, Friday, September 1, 2023 12:00:00 PM GMT is represented as 1693569600000. This applies to all timestamps in Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp (milliseconds since epoch) when the task started processing. 0 if not started.
Name
finished_at
Type
timestamp
Description
Timestamp (milliseconds since epoch) when the task finished. 0 if not finished.
Name
expires_at
Type
timestamp
Description
Timestamp (milliseconds since epoch) when the task result assets expire.
Name
task_error
Type
object
Description
Error object if the task failed, otherwise an object with an empty message string. See Errors for more details.
- Name
  message
  Type
  string
  Description
  Detailed error message. Empty if task succeeded.
Name
result
Type
object
Description
Contains the output animation URLs if the task SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  Downloadable URL for the animation in GLB format.
- Name
  animation_fbx_url
  Type
  string
  Description
  Downloadable URL for the animation in FBX format.
- Name
  processed_usdz_url
  Type
  string
  Description
  Downloadable URL for the processed animation in USDZ format.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  Downloadable URL for the processed armature in FBX format.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  Downloadable URL for the animation with changed FPS in FBX format (e.g., if change_fps operation was used).
Name
preceding_tasks
Type
integer
Description
The count of preceding tasks in the queue. Meaningful only if status is 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": ""
  },
  "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
}