Text to Motion API

Generate character motion clips from text descriptions. Describe an action, such as "a character waving" or "a zombie shambling forward", and get a raw motion clip. You can retarget the clip onto rigged characters in your own pipeline or DCC tools.

The output is a standalone motion clip. It doesn't need a character model, and it isn't attached to one. To rig a character first, see the Rigging API. To apply a clip to your rigged character, send the task id as motion_task_id to the Animation API. Apply it within the 3-day asset retention window.

POST/openapi/v1/text-to-motion

Create a Text to Motion task

Creates a Text to Motion task, which generates a motion clip from a text prompt.

The task runs in the background. For how long a task usually takes, see Processing times.

A prime task costs 10 credits and uses Meshy's higher-quality motion model. A swift task costs 3 credits and uses a faster, lower-cost motion model.

Request

POST

/openapi/v1/text-to-motion

# Generate a motion clip with required params only
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "duration": 3
  }'

# Generate a fast, economical clip with Swift mode
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "mode": "swift",
    "duration": 4.5
  }'

Response

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

Parameters

Name
prompt
Type
string
Required
Description
Text that describes the motion to generate, up to 400 characters. Longer text returns 400.
Name
mode
Type
string
default prime
Description
The motion model, which also sets the clip's file format.
Available values:
- prime: higher quality, returns an FBX clip
- swift: faster and cheaper, returns a BVH clip
Any other value returns 400.
Name
duration
Type
number
Required
Description
The target clip length in seconds, from 2 to 10 in steps of 0.5, for example 2, 2.5, or 3. Any other value returns 400.

Returns

The result field of the response holds the ID of the new Text to Motion task.

Failure modes

Name
400 - Bad Request
Description
The request can't run. The error message says which problem it found. For example:
- Missing or empty prompt: prompt is missing, blank, or longer than 400 characters.
- Invalid mode: mode isn't prime or swift.
- Invalid duration: duration is missing, outside the range 2 to 10, or not on a 0.5 second step.
Fix the request, then send it again. See Errors.
Name
401 - Unauthorized
Description
The API key is missing or invalid. Check the Authorization header.
Name
402 - Payment Required
Description
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.
Name
403 - Forbidden
Description
Content moderation flagged the prompt. Change the prompt, then send the request again.
Name
429 - Too Many Requests
Description
You exceeded your rate limit. Wait, then retry. See Rate limits.

GET/openapi/v1/text-to-motion/:id

Get a Text to Motion task

Returns a Text to Motion task by its ID.

Request

GET

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791

curl https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

Parameters

Name
id
Type
path
Description
The task ID from the create response.

Returns

The Text to Motion task object.

GET/openapi/v1/text-to-motion

List Text to Motion tasks

Returns a paginated list of your Text to Motion tasks, newest first. To page through the list, use page_num and page_size.

The response is an array of Text to Motion task objects.

Tasks you create with the API stay in the API and don't appear in My Assets in the web app. To find a task whose ID you no longer have, use this endpoint.

Request

GET

/openapi/v1/text-to-motion

curl "https://api.meshy.ai/openapi/v1/text-to-motion?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
    "type": "text-to-motion",
    "status": "SUCCEEDED",
    "...": "..."
  }
]

GET/openapi/v1/text-to-motion/:id/stream

Stream a Text to Motion task

Streams a Text to Motion task's updates as Server-Sent Events (SSE).

Request

GET

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791/stream

curl -N https://api.meshy.ai/openapi/v1/text-to-motion/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 events carry the full task object at every stage; the result
// fields stay empty until the task succeeds.
event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "IN_PROGRESS",
  "progress": 50,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 0,
  "expires_at": 0,
  "task_error": null,
  "result": {
    "motion_url": "",
    "motion_format": "",
    "duration_ms": 0,
    "mode": ""
  },
  "consumed_credits": 10
}

event: message
data: { // Example of a SUCCEEDED task event, with the same fields as the Text to Motion task object
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

Parameters

Name
id
Type
path
Description
The task ID from the create response.

Returns

A stream of Text to Motion task objects as Server-Sent Events.

Every message event carries the full task object. While the task is PENDING or IN_PROGRESS, the result fields are empty ("" or 0), and finished_at and expires_at are 0. To follow the task, watch status and progress.

DELETE/openapi/v1/text-to-motion/:id

Delete a Text to Motion task

Permanently deletes a Text to Motion task, including its motion clip. You can't undo a delete.

Request

DELETE

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -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 keeps 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."
}

Path parameters

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

Task status

Deleting a PENDING task refunds the credits it used when you created it.

An IN_PROGRESS task can't be deleted. The request returns 409 Conflict, and the task keeps running. Meshy doesn't refund a task that has started, so deleting it would cost you both the credits and the result. Wait for it to reach SUCCEEDED, FAILED, or CANCELED, then delete it.

Deleting a task in a final status (SUCCEEDED, FAILED, or CANCELED) doesn't refund its credits.

Returns

200 OK when the task is deleted, or 409 Conflict when the task is IN_PROGRESS.

The Text to Motion task object

A Text to Motion task object describes the generation of one motion clip. It holds the status, the progress, and the clip when the task succeeds.

Properties

Example Text to Motion Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

Name
id
Type
string
Description
The task ID. Treat it as an opaque string, and don't rely on its format.
Name
type
Type
string
Description
The task type, always text-to-motion.
Name
status
Type
string
Description
The task status, one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, or CANCELED.
Name
progress
Type
integer
Description
How much of the task is done, as a percentage from 0 to 100.
Name
created_at
Type
timestamp
Description
Time the task was created, in Unix milliseconds.
Name
started_at
Type
timestamp
Description
Time the task started, in Unix milliseconds. It's 0 until the task starts.
Name
finished_at
Type
timestamp
Description
Time the task finished, in Unix milliseconds. It's 0 until the task finishes.
Name
expires_at
Type
timestamp
Description
Time the task's result files expire, in Unix milliseconds. It's 0 until the task finishes. Meshy keeps the clip for 3 days after the task finishes, so download it before then.
Name
preceding_tasks
Type
integer
Description
The number of tasks ahead of this one in the queue. The value is meaningful only while the task is PENDING. The field is left out when the value is 0.
Name
consumed_credits
Type
integer
Description
The number of credits the task used, 10 for prime mode or 3 for swift mode. It's 0 for a FAILED task, because Meshy refunds the credits when a task fails.
Name
task_error
Type
object
Description
The error details when the task fails, and null otherwise. See Errors.
Name
result
Type
object
Description
The generated motion clip when the task succeeds. Until then, the fields are present but empty ("" or 0).
- Name
  motion_url
  Type
  string
  Description
  Download URL for the motion clip. Meshy signs the URL again on every read, and it expires with the task's retention window.
- Name
  motion_format
  Type
  string
  Description
  The clip's file format, fbx for prime mode or bvh for swift mode.
- Name
  duration_ms
  Type
  integer
  Description
  The clip length, in milliseconds.
- Name
  mode
  Type
  string
  Description
  The mode Meshy used to generate the clip, prime or swift.