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 — a preset action from the animation library (action_id), several preset actions merged into one file (action_ids), 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, action_ids or motion_task_id.
Name
action_ids
Type
array of integers
Description
Several preset animation actions to apply at once, returned as a single file containing one animation clip per action — useful for driving a character from a state machine in a game engine. Provide 1 to 10 action_id values from the Animation Library Reference; ids must be unique. Costs 3 credits per action. Provide exactly one of action_id, action_ids or motion_task_id.
Passing a single-element action_ids is equivalent to passing that value as action_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, action_ids 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 action_ids, the task returns one merged file rather than one file per action: animation_glb_url and animation_fbx_url each point at a single asset containing every requested action as a separate clip.

Clip order: the order of the action_ids array, not the numeric order of the ids.
Clip names: the animation's name in the library, matching the names you get when exporting all animations of a character as a single file from the Meshy web app. If two requested ids resolve to the same clip name, the later one is suffixed with its action_id to keep names unique.
Post-processing: applied to the merged file, not to the individual clips.

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 none of action_id, action_ids and motion_task_id is provided.
- Conflicting parameters: more than one of action_id, action_ids and motion_task_id was 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: An action_id — or an entry of action_ids — does not correspond to a valid animation.
- Too many actions: action_ids contains more than 10 ids.
- Duplicate actions: action_ids contains the same id more than once.
- 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 several preset actions and get one file with one clip per 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",
    "action_ids": [10, 25, 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.

Task Status

A task that is still PENDING is deleted and the credits consumed at create-time are refunded.

A task that is already IN_PROGRESS cannot be deleted: the request is rejected with 409 Conflict and the task keeps running. Credits for a task the worker has already started are not refundable, so deleting it mid-run would cost you the credits and the result both. Wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it.

A task in a terminal state (SUCCEEDED, FAILED or CANCELED) is deleted without a refund.

Returns

Returns 200 OK on success, or 409 Conflict when the task is IN_PROGRESS.

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

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

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. For a task created with action_ids, this single file contains every requested action as a separate clip.
- Name
  animation_fbx_url
  Type
  string
  Description
  Downloadable URL for the animation in FBX format. For a task created with action_ids, this single file contains every requested action as a separate clip.
- 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
}

GET/openapi/v1/animations/library

List Animations

Returns every animation in the library, ordered by action_id. The response is a complete list rather than a page, so one call is enough to populate an action picker. Filters narrow the result; omit them all to fetch everything.

To browse the same catalogue by eye, with an animated preview of each action, see the Animation Library reference.

This endpoint is free — it consumes no credits.

Parameters

Name
search
Type
string
Description
Case-insensitive substring match on name or key. Matched literally, so % and _ are ordinary characters rather than wildcards.
Name
category
Type
string
Description
Exact match on category.
Available values:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
Exact match on sub_category. Accepted on its own — sub-category names are not unique across categories (Transitioning appears under both Fighting and DailyActions), so without a category the filter matches that sub-category wherever it appears.
Name
action_ids
Type
string
Description
Comma-separated list of action_id values to return, for resolving specific ids rather than browsing. Accepts at most 200 ids. Ids that no animation carries are simply absent from the response, so you can also use this to check whether ids you have stored are still available.

Combining filters

Filters are applied together — each one narrows the result further, so an animation is returned only if it satisfies all of them. Within a single filter, multiple values match any of them: search matches name or key, and action_ids matches any id in the list.

That means a combination with no overlap returns an empty array rather than an error. Action 92 is "Double Combo Attack", a Fighting animation:

?action_ids=92&category=Fighting returns action 92.
?action_ids=92&category=Dancing returns [] — it is not a Dancing animation.
?action_ids=92&search=walk returns [] — its name does not match walk.

To fetch specific animations regardless of their category, pass action_ids on its own.

Returns

Returns a list of The Animation Objects.

Every action_id returned here is accepted by Create an Animation Task above, and every id it accepts is returned here. Retired animations are absent from both. If you cache the library, refresh it periodically so a retired id does not linger in your picker.

Request

GET

/openapi/v1/animations/library

curl "https://api.meshy.ai/openapi/v1/animations/library?category=Fighting" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "action_id": 4,
    "name": "Attack",
    "key": "Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Attack.gif"
  },
  {
    "action_id": 92,
    "name": "Double Combo Attack",
    "key": "Double_Combo_Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
  }
]

The Animation Object

Name
action_id
Type
integer
Description
The value to pass as action_id when creating an animation task. Unique and stable, but not contiguous — retired animations leave gaps in the numbering, so never assume a range of ids is valid.
Name
name
Type
string
Description
Human-readable label, for display. Not unique: some animations share a name with a different variant, so use action_id or key as the identity.
Name
key
Type
string
Description
Unique stable slug for the animation. Use it when you need a non-numeric identifier to key your own storage on.
Name
category
Type
string
Description
Top-level grouping, e.g. Fighting.
Name
sub_category
Type
string
Description
Grouping within the category, e.g. AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL of an animated GIF previewing the action, suitable for rendering directly in your own picker.

Example Animation Object

{
  "action_id": 92,
  "name": "Double Combo Attack",
  "key": "Double_Combo_Attack",
  "category": "Fighting",
  "sub_category": "AttackingwithWeapon",
  "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
}