uthanaMotion() with generateMotion() turns a prompt into a skeletal animation clip (FBX or GLB). Upload your own humanoid character, and Uthana makes the clip on that rig. The adapter has no chat.
Warning
Motion generation is experimental. The API can change. Uthana bills for each second of motion.
npm i @tanstack/ai @tanstack/ai-uthanapnpm add @tanstack/ai @tanstack/ai-uthanayarn add @tanstack/ai @tanstack/ai-uthanabun add @tanstack/ai @tanstack/ai-uthanaCreate an API key in your Uthana account. Put it in the environment of your server:
UTHANA_API_KEY=your-uthana-keyuthanaMotion reads UTHANA_API_KEY. To pass the key in code, set apiKey:
import { uthanaMotion } from '@tanstack/ai-uthana'
const adapter = uthanaMotion('text-to-motion-3.0', {
apiKey: process.env.UTHANA_API_KEY,
})This script makes an axe attack and saves the FBX next to the script. A 3.0 job takes about 2 minutes. A 4 second clip costs about $0.40.
import { writeFile } from 'node:fs/promises'
import { generateMotion, getMotionJobStatus } from '@tanstack/ai'
import { uthanaMotion } from '@tanstack/ai-uthana'
const adapter = uthanaMotion('text-to-motion-3.0')
const { jobId } = await generateMotion({
adapter,
threadId: 'orc-attacks',
prompt:
'A heavy warrior raises a two-handed axe overhead and slams it down',
duration: 4,
})
let status = await getMotionJobStatus({ adapter, jobId })
while (status.status === 'pending' || status.status === 'processing') {
await new Promise((resolve) => setTimeout(resolve, 5000))
status = await getMotionJobStatus({ adapter, jobId })
}
if (!status.motion) {
throw new Error(status.error ?? 'Motion generation failed')
}
for (const asset of status.motion.assets) {
// asset.url is a data: URL that holds the whole file.
const response = await fetch(asset.url)
const fileName = asset.fileName ?? `orc-attack.${asset.format}`
await writeFile(fileName, Buffer.from(await response.arrayBuffer()))
console.log(`Saved ${fileName}`)
}Run the script. You now have an FBX attack clip on disk, made on Uthana's default character "Tar".
Uthana serves files only with your API key. So the adapter downloads each file and returns it as a data: URL. The URL does not expire, but it is large. Save the bytes with your game assets.
Pass stream: true. The server submits the job, checks it, and streams each status to the browser.
Server route at /api/generate/motion:
import {
generateMotion,
generationParamsFromRequest,
toServerSentEventsResponse,
} from '@tanstack/ai'
import { uthanaMotion } from '@tanstack/ai-uthana'
export async function POST(request: Request) {
const { input, threadId, runId } = await generationParamsFromRequest(
'motion',
request,
)
if (typeof input.prompt !== 'string') {
return new Response('Send a text prompt.', { status: 400 })
}
const stream = generateMotion({
adapter: uthanaMotion('text-to-motion-3.0'),
prompt: input.prompt,
duration: typeof input.duration === 'number' ? input.duration : undefined,
modelOptions: { formats: ['fbx', 'glb'] },
stream: true,
pollingInterval: 5000,
threadId,
runId,
})
return toServerSentEventsResponse(stream)
}In the browser, read the stream with the generic useGeneration hook and MotionGenerationResult. The client code is the same for every motion provider:
Each asset url is a data: URL, so a link with download={asset.fileName} saves the file.
A clip made on Tar needs a retarget in your engine. Upload your own character instead, and Uthana makes the clip on its proportions.
import { readFile } from 'node:fs/promises'
import { createUthanaCharacter } from '@tanstack/ai-uthana'
const bytes = await readFile('orc.glb')
const character = await createUthanaCharacter({
file: new Blob([bytes]),
fileName: 'orc.glb',
name: 'Orc',
})
console.log(character.characterId, character.autoRigConfidence)import { generateMotion } from '@tanstack/ai'
import { uthanaMotion } from '@tanstack/ai-uthana'
const { jobId } = await generateMotion({
adapter: uthanaMotion('text-to-motion-3.0'),
threadId: 'orc-attacks',
prompt: 'An orc chieftain swings a two-handed axe in a wide arc',
duration: 5,
modelOptions: { character_id: 'your-character-id', formats: ['fbx', 'glb'] },
})The downloaded files now hold your orc's skeleton and the attack.
About the upload:
The repo example has two scripts that do this from the command line:
Pass the id as a string literal.
| Id | Clip length | Price |
|---|---|---|
| text-to-motion-3.0 | 4 to 10 seconds | About $0.10 per second of motion |
| text-to-motion-3.0-lite | 5 to 10 seconds | About $0.10 per second of motion |
| text-to-motion-3.0-mini | 5 to 10 seconds | About $0.075 per second of motion |
Prices are from the Uthana docs and can change. Set the length with duration, in seconds.
A 3.0 job makes a source video first. Then Uthana takes the motion out of that video. The job result names the generated video.
Put these in modelOptions:
| Option | Meaning | Default |
|---|---|---|
| character_id | The character to make the clip for and download on | Tar (UTHANA_DEFAULT_CHARACTER_ID) |
| formats | The files to download: 'fbx', 'glb', or both | ['fbx'] |
| fps | The frame rate of the files: 24, 30, or 60 | Uthana's default |
| fast | Uthana's faster mode | false |
| rewrite_prompt | Uthana rewrites the prompt before it makes the clip | true |
status.motion (or the generation:result event) is a MotionGenerationResult. Each asset has:
The result has no seed and no usage. Uthana does not return them.
If a job fails, status.error holds the error text from Uthana.
getMotionJobStatus() downloads the files when the job is complete. The job id holds the character_id, formats, and fps of the submit, so any adapter downloads the same files:
import { getMotionJobStatus } from '@tanstack/ai'
import { uthanaMotion } from '@tanstack/ai-uthana'
// jobId is the id that generateMotion() returned, in any process.
export function checkMotionJob(jobId: string) {
return getMotionJobStatus({
adapter: uthanaMotion('text-to-motion-3.0'),
jobId,
})
}Keep the full job id. The part after ? holds the options.
On a pay-as-you-go Uthana account, downloads are unlimited. Other plans count download seconds each month. The adapter downloads each format in formats once for each clip.
uthanaByok from @tanstack/ai-uthana/byok declares Uthana for the BYOK store, with UTHANA_API_KEY as its env var. On the server, pass the key that you read as uthanaMotion(model, { apiKey }). See Bring Your Own Key.
| Export | What it does |
|---|---|
| uthanaMotion(model, config?) | Creates a motion adapter for generateMotion() |
| createUthanaCharacter(options) | Uploads a humanoid model and returns { characterId, name, autoRigConfidence? } |
| UTHANA_DEFAULT_CHARACTER_ID | The id of Tar, Uthana's default character |
The config fields:
createUthanaCharacter takes file, fileName, name, and autoRig, plus apiKey, baseUrl, fetch, and abortSignal.