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 using our auto-rigging system. This process typically takes an additional 30-60 seconds to complete, but allows you to use characters that weren't originally rigged for animation. In the Web UI, you'll see a message like "No rig detected in scene. Auto-rigging in progress..." and the system will use the create_rig mutation automatically.

If you are using the API to upload a character, you will need to implement this as part of your error handling of the create_character mutation.

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\", character_id: \"cXi2eAP19XwQ\", model: \"text-to-motion\") { ok, job_id, motion { id, name } } }"}'

This will return a job_id for your new animation, which you can use to check its status and retrieve the final result:

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

You can also use the job_id to check the status of your request. Some requests will take a few seconds to complete, and will immediately return a motion object, while others may take a few minutes.

curl 'https://uthana.com/graphql?apikey=<your-api-key>' \
  -H "Content-Type: application/json" \
  -d '{"query": "query { get_motion(id: \"<new-motion-id>\") { id, name, org_id, created, updated, training, motion_viewer, tags } }"}'

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​