Quickstart guide
Get started with the Uthana API in minutes. This guide will help you create your first AI-powered animation.
Prerequisites
- An Uthana account (sign up here)
- An API key (support@uthana.com)
Step 1: Verify your API key is valid
- 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.
- Go to the Web UI and sign in with your Uthana account.
- Click the button.
- Upload your character model in FBX (.fbx) or glTF (.glb/.gltf) format.
- Verify that the character model is loaded correctly by viewing an existing motion or generating a new one.
- Copy the character ID from the URL. It will look like
https://uthana.com/app/<character-id>/<motion-id>
. - 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:
- Go to the Web UI and sign in with your Uthana account.
- From the motions list, you should see your new motion – click on it to view it.
- 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>
. - 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 asmotion.fbx
ormotion.glb
.
Next steps
- Review the API reference for more details on the API
- Review the examples for more complete examples
- Join our Discord for support