Text to Motion API

Generate character motion clips from natural-language descriptions. Describe an action — "a character waving", "a zombie shambling forward" — and receive a raw motion clip you can retarget onto rigged characters in your own pipeline or DCC tools.

The output is a standalone motion clip: it does not require, and is not attached to, a character model. To rig a character first, see the Rigging API.

POST/openapi/v1/text-to-motion

Create a Text to Motion Task

This endpoint creates a new task to generate a motion clip from a text prompt.

A task with mode prime costs 10 credits and generates with our highest-quality motion model. A task with mode swift costs 3 credits and generates faster with our economical motion model.

Parameters

Name
prompt
Type
string
Required
Description
A natural-language description of the motion to generate. Maximum 400 characters.
Name
mode
Type
string
default prime
Description
The motion generation mode. Available values: prime, swift. prime produces the highest quality and outputs FBX; swift is faster and cheaper and outputs BVH.
Name
duration
Type
number
Required
Description
The target duration of the motion clip in seconds. Between 2 and 10, in steps of 0.5 (for example 2, 2.5, 3, … 10).

Returns

The result property of the response contains the task id of the newly created Text to Motion task.

Failure Modes

Name
400 - Bad Request
Description
The request was unacceptable. Common causes:
- Missing or empty prompt: prompt is missing, blank, or longer than 400 characters.
- Invalid mode: mode is not prime or swift.
- Invalid duration: duration is missing, outside 2–10, or not on a 0.5 second step.
Name
401 - Unauthorized
Description
Authentication failed. Please check your API key.
Name
402 - Payment Required
Description
Insufficient credits to perform this task.
Name
403 - Forbidden
Description
The prompt was flagged by content moderation.
Name
429 - Too Many Requests
Description
You have exceeded your rate limit.

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

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

Retrieve a Text to Motion Task

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

Parameters

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

Returns

The response contains the Text to Motion Task object. Check The Text to Motion Task Object section for details.

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
}

GET/openapi/v1/text-to-motion

List Text to Motion Tasks

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

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

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/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

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

Parameters

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

Returns

Returns a stream of The 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 still empty ("" / 0) and finished_at / expires_at are 0; watch status and progress.

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 stream item, mirroring The Text to Motion Task Object structure
  "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
}

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

Delete a Text to Motion Task

This endpoint permanently deletes a Text to Motion task, including the generated motion clip. This action is irreversible.

Path Parameters

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

Returns

Returns 200 OK on success.

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

// Returns 200 Ok on success.

The Text to Motion Task Object

The Text to Motion Task object represents the work unit for generating a motion clip from a text prompt.

Properties

Name
id
Type
string
Description
Unique identifier for the task.
Name
type
Type
string
Description
Type of the task. The value is text-to-motion.
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. 0 until the task finishes. The generated clip is retained for 3 days after the task finishes; download it before it expires.
Name
preceding_tasks
Type
integer
Description
The count of preceding tasks in the queue. Meaningful only if status is PENDING; omitted when zero.
Name
consumed_credits
Type
integer
Description
The number of credits consumed by this task. 10 for prime mode, 3 for swift mode. Returns 0 for FAILED tasks (credits are refunded on failure).
Name
task_error
Type
object
Description
Error details for failed tasks; null unless the task FAILED. See Errors for the full task_error object reference.
Name
result
Type
object
Description
Contains the generated motion clip once the task SUCCEEDED; until then the fields are present but empty ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  Downloadable URL for the generated motion clip. The URL is re-signed on every read and expires with the task's retention window.
- Name
  motion_format
  Type
  string
  Description
  File format of the clip: fbx for prime mode, bvh for swift mode.
- Name
  duration_ms
  Type
  integer
  Description
  Duration of the generated clip in milliseconds.
- Name
  mode
  Type
  string
  Description
  The mode the clip was generated with: prime or swift.

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
}