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 an animation to a previously rigged character — either a preset action from the animation library (action_id) or a motion clip you generated with the Text to Motion API (motion_task_id). 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
Description
The identifier of the preset animation action to apply. See the Animation Library Reference for a complete list of available animations. Provide exactly one of action_id or motion_task_id.
Name
motion_task_id
Type
string
Description
The id of a successfully completed Text to Motion task to apply instead of a preset action. The generated clip is retargeted onto the rigged character and the clip is snapshotted at creation time, so this task is unaffected if the source task later expires or is deleted. The source task's assets are retained for 3 days — apply the clip before it expires. Requires a biped rig. Provide exactly one of action_id or motion_task_id.
Name
post_process
Type
object
Description
Optional post-processing for the animation output. Omit it to receive the standard animation files.

Applies only when post_process is set

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.

With motion_task_id, the retarget may produce a GLB-only animation. If you requested post_process and no FBX is available, the task fails with a task_error and your credits are refunded automatically; without post_process the task succeeds and animation_fbx_url is empty.

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 is missing, or neither action_id nor motion_task_id is provided.
- Conflicting parameters: both action_id and motion_task_id were provided — they are mutually exclusive.
- 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.
- Motion task not ready: the motion_task_id task has not SUCCEEDED yet.
- Unsupported rig: motion_task_id requires a biped rig; quadruped rigs are rejected.
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, the motion task specified by motion_task_id was not found, or the motion clip has expired (source task assets are retained for 3 days).
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
  }'

# 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

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

  },

  "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

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

List Animation Tasks

Returns a paginated list of the caller's animation tasks, newest first. Standard pagination via page_num and page_size.

Note that tasks created through the API are managed through the API — they do not appear in the web app's My Assets. Use this endpoint to find a task whose ID you no longer have.

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

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

  },

  "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

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 details for failed tasks. See Errors for the full task_error object reference.
Name
consumed_credits
Type
integer
Description
The number of credits consumed by this task. Present when the task status is PENDING, IN_PROGRESS, or SUCCEEDED. Returns 0 for FAILED tasks (credits are refunded on failure).
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": ""

  },

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