Generate high-quality 3D character animations from simple text prompts. Text-to-motion is perfect for quickly creating animations without needing video input or motion capture data.

Learn more about [Text to motion](/content/product/text-to-motion/index.html).

## Overview

Text-to-motion allows you to describe an animation in natural language, and Uthana will generate a motion sequence that matches your description. Results are returned immediately—no polling required.

## Introducing text to motion 3.0 New

`text-to-motion-3.0` is now available to any account on the [pay-as-you-go plan](/content/docs/api/pricing/index.html). Use the new `create_text_to_motion_job` mutation with `model: "text-to-motion-3.0"`.

## Step-by-step tutorial

### Step 1: Set up the client

Install your client library and authenticate using your API key. See the [quickstart](/content/docs/api/#step-1-install-the-client/index.html) for setup instructions for each language.

### Step 2: Generate motion from text

Create a text-to-motion animation by sending a mutation with your text prompt.

- Shell
- Python
- TypeScript
- React
- C#

```
curl -X POST https://uthana.com/graphql \
  -u $API_KEY: \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation CreateTextToMotion($prompt: String!) { create_text_to_motion(prompt: $prompt) { motion { id name } } }", "variables": { "prompt": "a person walking down the street" }}'
```

### Step 3: Handle the response

Text-to-motion results are returned immediately. The response includes the motion ID and name.

- Shell
- Python
- TypeScript
- React
- C#

```
{
  "data": {
    "create_text_to_motion": {
      "motion": {
        "id": "m3G3XSJrjEJH",
        "name": "a person walking down the street"
      }
    }
  }
}
```

### Step 4: Download your motion

Once you have the motion ID, download it in FBX or GLB format.

- Shell

```
CHARACTER_ID="cXi2eAP19XwQ"  # Default character, or use your own
MOTION_ID="m3G3XSJrjEJH"

# Download as FBX (filename is customizable)
curl -L "https://uthana.com/motion/file/motion_viewer/$CHARACTER_ID/$MOTION_ID/fbx/motion.fbx" \
  -u $API_KEY: \
  -o motion.fbx

# Download as GLB (filename is customizable)
curl -L "https://uthana.com/motion/file/motion_viewer/$CHARACTER_ID/$MOTION_ID/glb/motion.glb" \
  -u $API_KEY: \
  -o motion.glb
```

## Text to motion 3.0

General availability

Text to motion 3.0 is an async, diffusion-based model that supports longer, higher-quality generations. Unlike the standard `create_text_to_motion` mutation (which returns a motion immediately), this uses `create_text_to_motion_job` and requires polling.

**Parameters:**

- `prompt`: Text description of the motion to generate.
- `model`: Must be `"text-to-motion-3.0"`.
- `character_id`: (optional) Character ID to retarget the motion to.
- `length`: (optional) Target video length in seconds, rounded to an integer between 4–10. Default is 8.
- `rewrite_prompt`: (optional) Rewrite the prompt into physical motion direction. Default is `true`.

### Enable foot IK

For better foot placement on uneven surfaces, enable foot IK:

- Shell

```
curl -X POST https://uthana.com/graphql \
  -u $API_KEY: \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { create_text_to_motion(prompt: \"walk casually\", foot_ik: true) { motion { id name } } }"}'
```

### Advanced options

For more control over generation parameters, use the `text-to-motion-2.0` or `text-to-motion-1.0` model:

- Shell

```
curl -X POST https://uthana.com/graphql \
  -u $API_KEY: \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { create_text_to_motion(prompt: \"confident stride\", model: \"text-to-motion-bucmd\") { motion { id name } } }"}'
```

## Error handling

Check for errors in response:

- Shell

```
if echo "$RESPONSE" | jq -e '.errors' > /dev/null; then
    echo "Error occurred:"
    echo "$RESPONSE" | jq '.errors'
fi
```

## Next steps

- Learn about [Locomotion](/content/docs/api/capabilities/locomotion/index.html) for predictable, controllable, looptable travel in a given direction
- Learn about [Video to motion](/content/docs/api/capabilities/video-to-motion/index.html) for converting video files
- Explore [Retargeting](/content/docs/api/capabilities/retargeting/index.html) to apply motions to custom characters
- Check the [API reference](/content/docs/api/graphql/index.html) for complete schema documentation.