Track · character

Character track

Parametric character renderer. Lucky (the Great Dane) is the reference character; the engine is breed-agnostic — characters are defined by a manifest at data/characters/<name>.manifest.json.

Endpoints

Route	Auth	Purpose
`GET /api/v1/character`	`character:v1:use`	Full parametric access — pose / mood / size / motion.
`GET /api/v1/character/demo`	public	Curated preview — three fixed variants, tight size bounds. No JWT needed.

Quick example — authenticated

<img
  src="https://urja.insightsbyomkar.com/api/v1/character?pose=listening&mood=attentive&size=256"
  width="256" height="256" alt="Lucky listening" />

Keys hit the Authorization: Bearer <jwt> header. See the quickstart for the server-side-proxy pattern — customer-facing pages should never put a raw key in an <img src>.

Quick example — public preview (no key)

<img
  src="https://urja.insightsbyomkar.com/api/v1/character/demo?variant=resting&size=200"
  width="200" height="200" alt="Lucky resting" />

Three variants available: listening, resting, beside-you.

Parameters (authenticated endpoint)

Param	Default	Notes
`name`	`lucky`	Character slug. Only `lucky` ships today; the renderer is breed-agnostic.
`pose`	`idle`	`idle` \	`resting` \	`listening` \	`beside-you`.
`mood`	—	`soft` \	`attentive` \	`warm` \	`uncertain` \	`joyful` \	`quiet`.
`size`	`240`	Integer px, clamped `[24, 1200]`.
`motion`	`auto`	`auto` \	`static` \	`breathing-only` \	`full`. Animated variants use SMIL, play inside an `<img>` with zero JS runtime.
`label`	derived	Overrides the `aria-label` on the SVG root.

auto picks full when size ≥ 200 and static below that (tiny poster frames for avatar chips). Pin static for OG cards and print.

Response contract

Content-Type: image/svg+xml; charset=utf-8
Cache-Control: public, max-age=86400, s-maxage=604800, immutable — 1-day

browser, 1-week CDN cache. Output is deterministic per (name, pose, mood, size, motion) — two identical URLs return byte-identical bodies.

X-RateLimit-* headers on every 2xx (see rate limits).

Motion modes

Mode	Breathing	Blinking	Notes
`static`	—	—	Pose frozen. Cheapest.
`breathing-only`	yes	—	Subtle chest rise/fall. Good for beside-you + resting.
`full`	yes	yes	Ambient idle — breathing + rare blink.
`auto`	size-derived	size-derived	Default. Picks `full` at ≥ 200 px, `static` below.

Common integrations

Hero image — pose=listening, size=1200, motion=auto. SMIL breath cycle plays inside a plain <img>.
Avatar chip — size=64, motion=static. Still frame, minimal bytes.
Scene composition — use /api/v1/scene?character=lucky&pose=... to get a backdrop + character in one SVG.
Chapter divider — pose=resting, size=400, motion=breathing-only.

Errors

400 — unknown pose / mood / motion. Body includes an available: list.
401 — missing or invalid JWT. The demo endpoint never 401s.
429 — rate-limit exceeded. Retry-After header set.