Animation API

The ID of the Rigging task whose character to animate, from POST /openapi/v1/rigging. The task must have the status SUCCEEDED.

Required unless you send action_ids or motion_task_id. The ID of the preset animation to apply. For the full list of animations, see the Animation Library reference or List animations.

Required unless you send action_id or motion_task_id. The IDs of 1 to 10 preset animations to apply at once, with no repeats. More than 10 IDs, or a repeated ID, returns 400. For the IDs, see the Animation Library reference.

Meshy returns one file with one animation clip per action, which suits a state machine in a game engine. Meshy charges for each action in the list. See Pricing.

A list with one ID works the same as sending that ID as action_id.

Required unless you send action_id or action_ids. The ID of a Text to Motion task whose clip to apply instead of a preset action. The task must have the status SUCCEEDED, and the rig must be a biped.

Meshy retargets the clip onto the rigged character. It copies the clip when you create this task, so this task isn't affected if the Text to Motion task later expires or you delete it. Meshy keeps the Text to Motion task's files for 3 days, so apply the clip before then.

Post-processing for the animation output. Leave it out to get the standard animation files.

With motion_task_id, the retarget can produce a GLB-only animation. If you send post_process and no FBX file is available, the task fails with a task_error, and Meshy refunds your credits. Without post_process, the task succeeds, and animation_fbx_url is empty.

The request can't run. The error message says which problem it found. For example:

• Missing parameter: rig_task_id is missing, or none of action_id, action_ids, and motion_task_id was sent.
• Conflicting parameters: The request has more than one of action_id, action_ids, and motion_task_id. Send only one.
• Invalid rig task: rig_task_id isn't a valid task ID, isn't a Rigging task, or points to a task that hasn't succeeded.
• Invalid action ID: An action_id, or an entry in action_ids, isn't a valid animation.
• Too many actions: action_ids has more than 10 IDs.
• Duplicate actions: action_ids has the same ID more than once.
• Motion task not ready: The motion_task_id task hasn't reached SUCCEEDED yet.
• Unsupported rig: motion_task_id needs a biped rig, and Meshy rejects a quadruped rig.

Fix the request, then send it again. See Errors.

The API key is missing or invalid. Check the Authorization header.

For example:

• Insufficient credits: The account doesn't have enough credits for this task, or the account reached a credit limit. Check your credit balance, then retry.
• Free plan: Creating a task requires a paid plan. Upgrade your plan in your subscription settings, then retry.

The rig_task_id task is a bas-relief model, which this endpoint can't animate. The message is This model type does not support this operation. Rig a different model.

Meshy can't find a task or file the request needs. One of these applies:

• Meshy can't find the rig_task_id task among your tasks. Check the ID.
• Meshy deleted the rig_task_id task's files after its expires_at. Rig the character again.
• Meshy can't find the motion_task_id task. Check the ID.
• The motion clip expired, because Meshy keeps a Text to Motion task's files for 3 days. Create another Text to Motion task.

You exceeded your rate limit. Wait, then retry. See Rate limits.

The task ID from the create response.

The ID of the task to delete.

The task ID from the create response.

The task ID. Treat it as an opaque string, and don't rely on its format.

The task type, always animate.

The task status, one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, or CANCELED.

How much of the task is done, as a percentage. It's 0 until the task starts and 100 when it succeeds.

Time the task was created, in Unix milliseconds.

Time the task started, in Unix milliseconds. It's 0 until the task starts.

Time the task finished, in Unix milliseconds. It's 0 until the task finishes.

Time the task's result files expire, in Unix milliseconds.

The error details when the task fails. See Errors.

The number of credits the task used. Present when the status is PENDING, IN_PROGRESS, or SUCCEEDED. It's 0 for a FAILED task, because Meshy refunds the credits when a task fails.

Download URLs for the animation files, when the task has the status SUCCEEDED.

The number of tasks ahead of this one in the queue. The value is meaningful only while the task is PENDING.

Text to search for. Meshy returns the animations whose name or key contains this text, ignoring case. Meshy matches the text literally, so % and _ aren't wildcards.

The category to list, as an exact match. An unknown category returns an empty list.

Available values:

• WalkAndRun
• BodyMovements
• DailyActions
• Fighting
• Dancing

The subcategory to list, as an exact match. You can send it without category. Subcategory names aren't unique across categories. For example, Transitioning is under both Fighting and DailyActions. So without category, the filter matches the subcategory in every category.

The animations to return, as up to 200 comma-separated action_id values. Use it to look up specific IDs instead of browsing. More than 200 IDs returns 400.

The response leaves out an ID that no animation has. So you can also use this filter to check whether IDs you stored are still available.

The value to send as action_id when you create an Animation task. It's unique and stable, but not contiguous. Retired animations leave gaps in the numbering, so don't assume that every ID in a range is valid.

The animation's display name. It isn't unique, because some animations share a name with another variant. To identify an animation, use action_id or key.

A unique, stable slug for the animation. Use it when you need a non-numeric ID to key your own storage on.

The top-level group, for example Fighting.

The group within the category, for example AttackingwithWeapon.

URL of an animated GIF preview of the action. You can show it directly in your own picker.