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.

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