Auto-Rigging & Animation API

The Auto-Rigging & Animation API allows you to programmatically rig 3D models and apply animations to them using Meshy's backend capabilities. This section provides the necessary details to integrate these features into your application.

Please note that programmatic rigging and animation currently only works well with standard humanoid (bipedal) assets with clearly defined limbs and body structure at this time.

Auto-Rigging API

Endpoints for submitting and retrieving character rigging tasks. Rigging involves creating an internal skeleton (armature) and binding the model's mesh (skin) to it, making it ready for animation.

POST/openapi/v1/rigging

Create a Rigging Task

This endpoint allows you to create a new rigging task for a given 3D model. Upon successful completion, it provides a rigged character in standard formats and optionally basic walking/running animations.

Currently, auto-rigging is not suitable for the following models:

Untextured meshes
Non-humanoid assets
Humanoid assets with unclear limb and body structure

When using input_task_id, models with more than 300,000 faces are not supported for rigging. Please use the Remesh API to reduce the face count before rigging.

Parameters

Only one of input_task_id or model_url is required. If both are provided, input_task_id takes priority.

Name
input_task_id
Type
string
Required
Description
The input task that needs to be rigged. We currently support textured humanoid models.

Name
model_url
Type
string
Required
Description
Please provide a 3D model for Meshy to rig via a publicly accessible URL or Data URI. We currently support textured humanoid GLB files (.glb format).

Name
height_meters
Type
number
default 1.7
Description
The approximate height of the character model in meters. This aids in scaling and rigging accuracy. It must be a positive number.
Name
texture_image_url
Type
string
Description
The model's UV-unwrapped base color texture image. Publicly accessible URL or Data URI. We currently support .png formats.

Returns

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

Failure Modes

Name
400 - Bad Request
Description
The request was unacceptable. Common causes:
- Missing parameter: Either model_url or input_task_id must be provided.
- Invalid model format: The model_url points to a file with an unsupported extension (only .glb supported).
- Unreachable URL: The model_url could not be downloaded.
- Invalid input task: The input_task_id does not refer to a valid API task.
- Face count exceeded: The input model has more than 300,000 faces. Please use the Remesh API to reduce the face count before rigging.
Name
401 - Unauthorized
Description
Authentication failed. Please check your API key.
Name
402 - Payment Required
Description
Insufficient credits to perform this task.
Name
422 - Unprocessable Entity
Description
Pose estimation failed. The provided model may not be a valid humanoid character.
Name
429 - Too Many Requests
Description
You have exceeded your rate limit.

Request

POST

/openapi/v1/rigging

# Rig a model from a URL
curl https://api.meshy.ai/openapi/v1/rigging \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "YOUR_MODEL_URL_OR_DATA_URI",
    "height_meters": 1.8
  }'

Response

{
  "result": "018b314a-a1b5-716d-c222-2f1776f7f579"
}

GET/openapi/v1/rigging/:id

Retrieve a Rigging Task

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

Parameters

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

Returns

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

Request

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579 
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {
    "message": ""
  },
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}

DELETE/openapi/v1/rigging/:id

Delete a Rigging Task

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

Path Parameters

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

Returns

Returns 200 OK on success.

Request

DELETE

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/rigging/:id/stream

Stream a Rigging Task

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

Parameters

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

Returns

Returns a stream of The Rigging 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/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/stream

curl -N https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/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": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Rigging Task Object structure
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {
    "message": ""
  },
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/.../Character_output.fbx?...",
    "rigged_character_glb_url": "https://assets.meshy.ai/.../Character_output.glb?...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.glb?...",
      "walking_fbx_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.fbx?...",
      "walking_armature_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin_armature.glb?...",
      "running_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.glb?...",
      "running_fbx_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.fbx?...",
      "running_armature_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin_armature.glb?..."
    }
  },
  "preceding_tasks": 0
}

The Rigging Task Object

The Rigging Task object represents the work unit for rigging a character.

Properties

Name
id
Type
string
Description
Unique identifier for the task.
Name
type
Type
string
Description
Type of the Rigging task. The value is rig.
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). 0 if not started, 100 if succeeded.
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 and may be deleted.
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 asset URLs if the task SUCCEEDED, null otherwise.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  Downloadable URL for the rigged character in FBX format.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  Downloadable URL for the rigged character in GLB format.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Contains URLs for default animations. (e.g. if generate_basic_animations was implicitly true or enabled by default).
  Name
  walking_glb_url
  Type
  string
  Description
  Downloadable URL for walking animation in GLB format (with skin).
  Name
  walking_fbx_url
  Type
  string
  Description
  Downloadable URL for walking animation in FBX format (with skin).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Downloadable URL for walking animation armature in GLB format.
  Name
  running_glb_url
  Type
  string
  Description
  Downloadable URL for running animation in GLB format (with skin).
  Name
  running_fbx_url
  Type
  string
  Description
  Downloadable URL for running animation in FBX format (with skin).
  Name
  running_armature_glb_url
  Type
  string
  Description
  Downloadable URL for running animation armature in GLB format.
Name
preceding_tasks
Type
integer
Description
The count of preceding tasks in the queue. Meaningful only if status is PENDING.

Example Rigging Task Object

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {
    "message": ""
  },
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}