Animations

Animations are multi-track recordings of servo positions over time. They can be recorded with the joystick and stored permanently, or generated on the fly as ad-hoc animations that expire after 24 hours.

GET /api/v1/animation — List all stored animations.

GET /api/v1/animation/{animationId} — Get a single animation by its MongoDB ObjectId.

POST /api/v1/animation — Create or update a stored animation. Accepts a raw animation JSON string.

DELETE /api/v1/animation/{animationId} — Delete an animation and all of its tracks.

POST /api/v1/animation/play — Play a stored animation on a creature’s universe. If resumePlaylist is true, the active playlist resumes after this animation finishes.

{
  "animation_id": "ObjectId string",
  "universe": 1,
  "resumePlaylist": false
}

POST /api/v1/animation/interrupt — Interrupt the currently playing animation with a new one. Uses the cooperative scheduler — the running animation yields gracefully. Same request format as /animation/play.

Ad-Hoc Animations

Ad-hoc animations are generated on the fly from text. The server calls ElevenLabs for TTS, generates lip sync data, blends it with a body animation, and plays the result. These are stored in a TTL collection and expire after 24 hours.

GET /api/v1/animation/ad-hoc — List all ad-hoc animations currently in the TTL collection.

GET /api/v1/animation/ad-hoc/{animationId} — Get a specific ad-hoc animation by its ID.

POST /api/v1/animation/ad-hoc — Create and immediately play an ad-hoc speech animation. This is an async job — returns 202 with a job ID and reports progress over the WebSocket.

{
  "creature_id": "uuid",
  "text": "Hello, I'm Beaky!",
  "resume_playlist": false
}

POST /api/v1/animation/ad-hoc/prepare — Create an ad-hoc animation but don’t play it yet. Use this when timing matters — prepare ahead of time, then trigger playback manually. Same request format as above. Returns 202 with a job ID; the animation ID is delivered via the WebSocket when the job completes.

POST /api/v1/animation/ad-hoc/play — Play a previously prepared ad-hoc animation.

{
  "animation_id": "ObjectId string",
  "resume_playlist": false
}

Lip Sync Generation

POST /api/v1/animation/generate-lipsync — Regenerate lip sync data for an existing animation. Runs as an async job, returns 202 with a job ID.

{
  "animation_id": "ObjectId string"
}