# Lumorig

> Lumorig is an AI mascot generator and character engine. Describe a character or upload an existing mascot; Claude Opus 5.5 draws it as a rigged vector character (named SVG parts with pivots). 15 preset motions are free; custom motions come from words or a reference video. Export Lottie (true vector), animated SVG, GIF, MP4, WebM, WebP, APNG, sprite sheets, stickers and logo badges, or embed it live with the <lumorig-player> web component. Interactive state-machine canvases (chatbot, AI agent, onboarding), REST API, TypeScript SDK, hosted MCP server and CLI. Plans: Free (200 credits/month), Maker $12/month, Studio $36/month.

## Pages
- [Home](https://lumorig.com): Animated AI mascot generator: rigged vector characters for products and agents.
- [Pricing](https://lumorig.com/pricing): Free, Maker and Studio plans. Presets and exports never cost credits.
- [Gallery](https://lumorig.com/gallery): Live, rigged example characters you can play, inspect and open in the studio.
- [Developers](https://lumorig.com/developers): Mascots as an API: REST, TypeScript SDK, hosted MCP server and CLI.
- [AI mascot generator](https://lumorig.com/ai-mascot-generator): Describe a mascot in a sentence and get a rigged, animated vector character. Free to start.
- [Animate your mascot](https://lumorig.com/mascot-animation): Upload the mascot you already have and get it back rigged, with 15 motions and custom animation.
- [Lottie generator](https://lumorig.com/lottie-animation-generator): Generate true-vector Lottie character animations (no embedded bitmaps) from a prompt or an upload.
- [Vector mascot generator](https://lumorig.com/vector-mascot-generator): Mascots as real vector: SVG stills, animated SVG, logo badges and palette tokens you can recolour.
- [All use cases](https://lumorig.com/use-cases): Where an animated mascot earns its place in a product.
- [Chatbot avatar](https://lumorig.com/use-cases/chatbot-avatar): An animated chatbot avatar that listens, thinks and talks in step with your chat widget.
- [AI agent mascot](https://lumorig.com/use-cases/ai-agent-mascot): A mascot that shows what your AI agent is doing: working, waiting for you, done or failed.
- [App mascot](https://lumorig.com/use-cases/app-mascot): A guide character for onboarding, empty states and streaks that weighs kilobytes, not megabytes.
- [Brand mascot](https://lumorig.com/use-cases/brand-mascot): One brand character across site, app, social, stickers and logo badge, consistent in every pose.
- [Lumorig vs Masko](https://lumorig.com/vs/masko): An honest, dated comparison of Lumorig and Masko for product mascots.

## Docs
- [Introduction](https://lumorig.com/docs): Lumorig turns an idea or an existing mascot into a rigged vector character you can animate, export and embed from code.
- [Quickstart](https://lumorig.com/docs/quickstart): Create a mascot, wait for it, export a Lottie file and embed it live, in about five minutes.
- [Authentication](https://lumorig.com/docs/authentication): People sign in with a browser session; code uses a workspace API key. Workspaces, roles, seats and keys.
- [Concepts](https://lumorig.com/docs/concepts): Mascots, rigs, animations, canvases, jobs and credits: the six nouns the whole API is built on.
- [Generate from an idea](https://lumorig.com/docs/guides/generate): Describe a character in a sentence and get back a rigged, animation-ready vector mascot.
- [Rebuild an upload](https://lumorig.com/docs/guides/rebuild): Upload the mascot you already have and get it back as a rigged vector, with a fidelity score against your original.
- [Animate](https://lumorig.com/docs/guides/animate): Fifteen presets fitted to any rig for free, custom motions described in words, and motions copied from a reference video.
- [Edit & variants](https://lumorig.com/docs/guides/edit-variants): Recolor instantly, change the design in plain words, branch rig-compatible looks, and roll back to any version.
- [Export formats](https://lumorig.com/docs/guides/export): Lottie, animated SVG, video with alpha, GIF, sprites, stickers, logos and stills, at any size. Exports never cost credits.
- [Embed with <lumorig-player>](https://lumorig.com/docs/guides/embed): One script tag and one element: a live, interactive mascot at about 8 KB gzipped.
- [Interactive canvases](https://lumorig.com/docs/guides/canvases): State machines that map your app's events to your mascot's motions, blended at runtime.
- [Scenes](https://lumorig.com/docs/guides/scenes): Place your mascot in an illustrated, fully vector scene for banners, empty states and social cards.
- [Webhooks](https://lumorig.com/docs/guides/webhooks): Get a signed POST when a job succeeds, fails or is canceled, instead of polling.
- [Use from AI agents (MCP)](https://lumorig.com/docs/guides/mcp): Give Claude Code, Cursor or any MCP client fourteen tools to create, animate, export and embed mascots.
- [CLI & terminal companion](https://lumorig.com/docs/guides/cli): The lumorig CLI creates, animates and exports mascots, plays them in your terminal, and runs a companion that reacts to your coding agent.
- [TypeScript SDK](https://lumorig.com/docs/guides/sdk): @lumorig/sdk: a typed, zero-dependency client for Node 18+, Bun, Deno and browsers.
- [REST API](https://lumorig.com/docs/api): Every endpoint in /api/v1, rendered from the live OpenAPI document.
- [Errors](https://lumorig.com/docs/errors): One error shape everywhere, stable machine-readable codes, and what to do about each.
- [Credits & limits](https://lumorig.com/docs/credits): What each model-backed action costs, what is always free, and the limits every request is checked against.
- [MascotSpec & AnimationClip](https://lumorig.com/docs/formats): The two JSON formats behind every mascot: the rigged drawing and the motion that plays on it.

## Gallery
- [Pip](https://lumorig.com/gallery/pip): a blue blob mascot. Quietly proud of every kilobyte.
- [Nova](https://lumorig.com/gallery/nova): a robot mascot. Has zero judgment about your variable names.
- [Penny](https://lumorig.com/gallery/penny): an otter mascot. Quietly proud of your savings streak.
- [Axi](https://lumorig.com/gallery/axi): an axolotl astronaut mascot. Floats through your first five minutes so you never feel lost in space.
- [Nipper](https://lumorig.com/gallery/nipper): a crab mascot. Wears the status light on its head and checks it twice.
- [Grumps](https://lumorig.com/gallery/grumps): a hedgehog barista mascot. Scowls at the espresso machine, draws a heart in every latte.
- [Beacon](https://lumorig.com/gallery/beacon): a lighthouse mascot. Keeps the light on so you never have to wonder.
- [Mothley](https://lumorig.com/gallery/mothley): a moth librarian mascot. Has read every page of your docs, twice, by lamplight.
- [Lumi](https://lumorig.com/gallery/lumi): a jellyfish mascot. Glows a little dimmer with every page, right on schedule.
- [Crumb](https://lumorig.com/gallery/crumb): a cactus mascot. Rises early, proofs patiently, never pricks a customer.
- [Glitch](https://lumorig.com/gallery/glitch): a dragon mascot. Hatched mid-speedrun and hasn’t stopped since.
- [Hush](https://lumorig.com/gallery/hush): a cloud mascot. A pocket cloud that breathes slower than you do, on purpose.
- [Postbot](https://lumorig.com/gallery/postbot): a mail robot mascot. Every envelope delivered, every open rate counted.
- [Sage](https://lumorig.com/gallery/sage): a turtle hiker mascot. Slow, steady, and never takes the wrong trail.
- [Rhett](https://lumorig.com/gallery/rhett): a rhino foreman mascot. Hard hat on, clipboard up, every task ticked.
- [Yuzu](https://lumorig.com/gallery/yuzu): a capybara mascot. Unbothered by your backlog, and by most things.
- [Brew](https://lumorig.com/gallery/brew): a coffee mug mascot. Always two sips ahead of your to-do list.
- [Swoop](https://lumorig.com/gallery/swoop): a paper plane mascot. Folds itself into every message and never misses a mention.

## Using Lumorig from an agent
Lumorig turns a description (or an existing mascot image) into a **rigged vector character** that animates cleanly and exports as true-vector Lottie/SVG, video, stickers, or a live web embed.

### Pick an interface
- **MCP tools available** (`create_mascot`, `animate_mascot`, …): use them — they wait for jobs and show previews.
- **CLI** (`lumorig`, from `npx lumorig`): good for scripts and saving files into the repo.
- **REST API**: `https://lumorig.com/api/v1`, `Authorization: Bearer $LUMORIG_API_KEY`. OpenAPI: `/api/v1/openapi.json`.

### Workflow
1. **Create.** From a prompt: be specific about who the mascot is (species/object, personality, brand, 1–2 signature details) and pick a style: `outlined`, `flat`, `kawaii`, `soft3d`, `retro`, `pixelish`. From an image: pass the file/URL; results include a `fidelity` score — if `needs_review` is true, show the user the side-by-side before building on it.
2. **Animate.** Presets are instant and free: `idle wave nod shake bounce celebrate jump talk sad surprised dance think working listen sleep` (with `intensity` 0.5–1.5). For anything else, describe the motion ("hops twice, then does a tiny bow").
3. **Ship.**
   - Web: `<script type="module" src="https://lumorig.com/player.js"></script>` + `<lumorig-player src="<bundle_url>" animation="wave" trigger="hover" follow-cursor>`; React: render the same `<lumorig-player>` element after loading player.js (React supports custom elements).
   - Files: `lottie` (smallest, vector), `animated-svg` (no JS), `webm` (alpha video), `mp4`, `gif`, `sticker`, `logo` (vector badge), `png`/`svg` stills.
   - Interactive states: create a canvas from a template (`chatbot`: listening/thinking/talking; `ai_agent`: status 0–4; `onboarding`: hello/success/error triggers), then `player.canvas = "<name>"; player.setInput("thinking", true)`.

### Tips
- Recolor by palette token is instant (`recolor_mascot` / `lumorig recolor <id> fur=#3b82f6`); prefer it over an AI edit for color changes.
- Use a **variant** (not an edit) for outfits/seasonal looks — all animations keep working.
- Private mascots embed via expiring signed links; make the mascot `public` for permanent embeds.
- Generation takes 1–4 minutes and costs a few cents to ~$1; exports and presets are free.

## API essentials
Base: https://lumorig.com/api/v1 — Authorization: Bearer lr_sk_…
- POST /mascots {prompt, style} | {image_url | upload_id, notes} | {spec} → {mascot, job}
- GET /jobs/{id}?wait=60 (long-poll) · GET /jobs/{id}/events (SSE)
- POST /mascots/{id}/animations {preset, intensity?, duration?} → instant | {prompt} → job
- POST /mascots/{id}/exports {format, animation?, size?, fps?, background?} → job → result.file.url
- POST /mascots/{id}/recolor {palette: {token: "#rrggbb"}} · POST /mascots/{id}/edit {instruction} · POST /mascots/{id}/variants {name, instruction}
- POST /mascots/{id}/canvases {name, template} · GET /mascots/{id}/bundle (player bundle) · POST /mascots/{id}/share
- POST /uploads (multipart file | {url}) · POST /analyze {url} · webhooks: POST /webhooks {url, events}
Full reference: https://lumorig.com/api/v1/openapi.json
MCP: claude mcp add --transport http lumorig https://lumorig.com/api/mcp --header "Authorization: Bearer lr_sk_…"  (or stdio: npx -y @lumorig/mcp with LUMORIG_API_KEY)