Text to motion | Uthana API Docs

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.

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

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.

{
  "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.

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:

Enable foot IK

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

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:

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:

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

Next steps