Skip to main content

Quickstart guide

Get started with the Uthana API in minutes. This guide will help you create your first AI-powered animation.

Prerequisites​

Step 1: Verify your API key is valid​

  1. Open a terminal and run the following command:
curl 'https://uthana.com/graphql' \
  -u <your-api-key>: \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __typename }"}'

After running this, you should see a response like: {"data":{"__typename":"Query"}}. This confirms your API key is working correctly.

Step 2: Prepare your character model​

(Note: You can skip this step if you're using the default character, "Tar", with the character ID cXi2eAP19XwQ.)

In order to generate motion for your character, you need to upload a 3D character model in FBX (.fbx) or glTF (.glb/.gltf) format. The easiest way to do this when you're just getting started is to use the Web UI to upload a new character.

  1. Go to the Web UI and sign in with your Uthana account.
  2. Click the button.
  3. Upload your character model in FBX (.fbx) or glTF (.glb/.gltf) format.
  4. Verify that the character model is loaded correctly by viewing an existing motion or generating a new one.
  5. Copy the character ID from the URL. It will look like https://uthana.com/app/<character-id>/<motion-id>.
  6. Save the character ID for later use.

You can also upload a character via the API. See the API documentation for more details.

Auto-rigging​

If your character doesn't have a skeleton rig, Uthana will automatically attempt to create one for you. The auto-rigging process typically takes an additional 30-60 seconds to complete, but allows you to use characters that weren't originally rigged for animation. If auto-rigging fails, you'll receive a detailed error message in the GraphQL response.

Step 3: Generate a new text-to-motion animation​

In your terminal, run the following command:

curl 'https://uthana.com/graphql?apikey=<your-api-key>' \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { create_text_to_motion(prompt: \"A person walking down the street\", model: \"text-to-motion\") { motion { id name } } }"}'

Text-to-motion results are returned immediately:

{
  "data": {
    "create_text_to_motion": {
      "motion": {
        "id": "<new-motion-id>",
        "name": "A person walking down the street"
      }
    }
  }
}

If there are any errors, they will be returned in a GraphQL errors array.

Video-to-motion results are returned as a job:

{
  "data": {
    "create_video_to_motion": {
      "job": {
        "id": "<new-job-id>",
        "status": "RESERVED"
      }
    }
  }
}

You can poll for status by querying jobs:

curl 'https://uthana.com/graphql?apikey=<your-api-key>' \
  -H "Content-Type: application/json" \
  -d '{"query": "query { jobs(method: \"VideoToMotion\", id: \"<new-job-id>\") { id status } }"}'

Step 4: View and download your motion​

You can view and download your motion in the Uthana Web UI:​

  1. Go to the Web UI and sign in with your Uthana account.
  2. From the motions list, you should see your new motion – click on it to view it.
  3. You can use the motions list and character selector to preview the motion – note that the url includes the character ID and motion ID: https://uthana.com/app/<character-id>/<motion-id>.
  4. You can also download the motion as FBX (.fbx) or glTF (.glb/.gltf) format directly from the web UI.

Or download the motion as FBX (.fbx) or glTF (.glb/.gltf) format directly from the API:​

# Download the motion as FBX
curl -L "https://uthana.com/motion/file/motion_viewer/<character-id>/<motion-id>/fbx/<character-id>-<motion-id>.fbx" \
  -u <your-api-key>: \
  -o motion.fbx

# Download the motion as GLB
curl -L "https://uthana.com/motion/file/motion_viewer/<character-id>/<motion-id>/glb/<character-id>-<motion-id>.glb" \
  -u <your-api-key>: \
  -o motion.glb
  • Replace <character-id> and <motion-id> with your actual IDs.
  • The -L flag follows redirects (if any).
  • The -o flag saves the file as motion.fbx or motion.glb.

Next steps​