Robot Control API

Complete API reference for controlling robot animations, expressions, and voice synthesis. All endpoints accept and return JSON.

Server

Checking...

Queue Length

—

Base URL

System

Health check and queue monitoring endpoints

GET /health

Server health check. Returns status and timestamp.

Try It

Response

Click "Send" to test

GET /api/robot/queue-length

Returns current number of commands waiting in the Redis queue.

Try It

Response

Click "Send" to test

GET /api/robot/commands

Pop the next command from queue (FIFO). Used by the robot terminal to consume commands. Warning: this removes the command from the queue.

Try It

Response

Click "Send" to test

Animation Control

Control robot expressions and Spine animations via the command queue

POST /api/commands/expression

Send an expression command. The robot terminal will play the corresponding "合成" animation.

Parameter	Type	Description
`expressionId` REQUIRED	string	Expression identifier: `happy` `sad` `angry` `surprised` `thinking` `embarrassed` `neutral`
`duration` optional	number	Duration in ms (default: 3000)
`clientId` optional	string	Client identifier for tracking

Expression → Animation Mapping:

😊 happy
合成微笑

😢 sad
合成哭

😠 angry
合成受擊

😲 surprised
合成驚訝

🤔 thinking
合成思考

😅 embarrassed
合成汗顏

😐 neutral
合成待机

Try It

expressionId

duration

curl -X POST /api/commands/expression \ -H "Content-Type: application/json" \ -d '{"expressionId":"happy","duration":3000}'

Response

Click an expression above, then "Send"

POST /api/commands/action

Send a Spine animation action command directly by animation name.

Parameter	Type	Description
`actionName` REQUIRED	string	Action/animation name
`spineAnimation` REQUIRED	string	Spine animation name (usually same as actionName)
`loop` optional	boolean	Whether to loop the animation (default: false)
`clientId` optional	string	Client identifier

Available Spine Animations:

合成受擊

合成吹口哨

合成哭

合成待机

合成待机2

合成微笑

合成思考

合成接收语音

合成汗顏

合成驚訝

Try It

spineAnimation

loop

curl -X POST /api/commands/action \ -H "Content-Type: application/json" \ -d '{"actionName":"合成待机","spineAnimation":"合成待机","loop":false}'

Response

Click an animation above, then "Send"

Voice / TTS

Text-to-Speech synthesis with lip-sync viseme data

POST /api/commands/tts

Send a TTS command to the robot queue. The robot terminal will synthesize speech and play with lip-sync.

Parameter	Type	Description
`text` REQUIRED	string	Text to speak
`voice` optional	string	`zh-CN` `zh-TW` `en-US` `ja-JP`
`speed` optional	number	Speed multiplier (default: 1.0)
`mouthAnimation` optional	string	Lip-sync method (default: "phoneme")
`clientId` optional	string	Client identifier

Try It

text

voice

speed

Response

Click "Send" to test

POST /api/azure-tts/synthesize

Azure Speech REST API synthesis. Returns audio (base64 MP3) and estimated viseme data for lip-sync. Visemes are generated from text heuristics.

Parameter	Type	Description
`text` REQUIRED	string	Text to synthesize
`voice` optional	string	Language hint (e.g. "en-US" or "zh-CN")
`speed` optional	number	Speed multiplier (default: 1.0)

Try It

text

speed

Response

Click "Send" to test (requires AZURE_SPEECH_KEY)

POST /api/azure-tts-sdk/synthesize

Azure Speech SDK synthesis with accurate real-time viseme events. Provides precise lip-sync timing from the SDK's viseme callback. Recommended for production use.

Parameter	Type	Description
`text` REQUIRED	string	Text to synthesize
`voice` optional	string	Language hint
`speed` optional	number	Speed multiplier (default: 1.0)

Try It

text

speed

Response Fields
`audio`	Base64 encoded MP3 audio
`visemes`	Array of `{start, end, visemeId, spineSlot}`
`duration`	Total audio duration in seconds
`voice`	Voice name used
`method`	"SDK"
`rawVisemeCount`	Number of raw viseme events from SDK
`mergedVisemeCount`	Number of merged visemes (optimized)

Response

Click "Send" to test (requires AZURE_SPEECH_KEY)

Batch Commands

Send multiple commands in a single request

POST /api/commands/batch

Send an array of commands to be pushed into the queue at once.

Parameter	Type	Description
`commands` REQUIRED	array	Array of command objects. Each must have `type` and `data`.

Try It

commands

Response

Click "Send" to test

Viseme Reference

Azure Viseme ID to Spine slot mapping used for lip-sync

Viseme ID	Phonemes	Spine Slot
0	Silence	`嘴正常`
1	ae, ax, ah	`A,e,H,i,I`
2	aa	`a,c,C,w,!`
3, 6, 7, 8, 20	ao, uh, ow, uw, w	`o.u`
4, 5, 9, 10, 21	ey, eh, iy, ih, y	`A,e,H,i,I`
11, 12	r, l	`r`
13, 14	s, z, sh, ch, jh, zh	`s,z`
15, 17	th, dh, d, t, n	`T,D,L`
16	f, v	`F,v`
18	k, g, ng	`G`
19	p, b, m	`b,m,p`