Edit & variants

There are a few ways to change a mascot after it exists, from cheapest to most involved. Pick the smallest one that does the job: a recolor or a prop switch is instant and free, an edit redraws the character, and a variant adds another look beside the current one, with every animation still working. Every change makes a new version, so nothing is ever lost.

Recolor#

Every mascot has a palette: named colour tokens such as fur or belly that its drawing references. Recoloring swaps token values and saves a new version. No model call is made, so it answers synchronously with the updated mascot. Read the token names from mascot.palette (or get_mascot over MCP).

POST/mascots/{id}/recolor

curl -X POST https://lumorig.com/api/v1/mascots/msc_…/recolor -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "palette": { "fur": "#3A5BFF", "belly": "#FFFFFF" } }'

Edit by instruction#

Describe the change in plain words (“make the ears bigger”, “give it a tiny top hat”). The editor agent continues the conversation that drew the mascot, so it remembers earlier decisions, then renders its work, checks the rig and fixes what it sees. The result is a new version on the same mascot.

POST/mascots/{id}/edit

Returns 202 with a job of type edit. When it succeeds, job.result holds mascot_id, version_id and a one-line summary of what changed.

curl -X POST https://lumorig.com/api/v1/mascots/msc_…/edit -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instruction": "make the ears bigger and rounder" }'
# 202 → { "id": "job_…", "type": "edit", "status": "queued", … }

Looks#

A look is another version of the same character kept beside it: an outfit, a seasonal hat, a team jersey. Making one is a variant: the agent changes the drawing but keeps the rig (part ids, pivots and joint limits), so every preset and saved animation keeps working, and the look you were on stays as it was. The mascot itself is the look called Original.

POST/mascots/{id}/variants

curl -X POST https://lumorig.com/api/v1/mascots/msc_…/variants -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Winter", "instruction": "wearing a red knitted scarf and a bobble hat" }'

The mascot lists its looks in mascot.looks, each with the version_id it is at now and whether it is current. Switching makes one current: the studio, exports and embeds show it from then on. An edit, recolor or prop switch stays in the look it was made on, so changing the Winter look never touches the Original.

POST/mascots/{id}/looks

curl -X POST https://lumorig.com/api/v1/mascots/msc_…/looks -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" -d '{ "look": "Winter" }'

To show a look on one page without switching the mascot, give the player its name: <lumorig-player src="…" look="Winter">. See Embed attributes.

Ready-made props#

Eleven props come ready to use, each with its own motion: a notepad and pencil (it writes, and the ink appears on the page), an open book, a laptop, a sign, a magnifying glass, a phone, a mug (it sips), a megaphone (it calls out), a skateboard (it rides), a stool (it sits) and a party hat with confetti. The arms are posed from the mascot's own rig and the prop is drawn in its outline and colours, so it takes a moment and costs nothing. Each one is a look of its own, so the original is kept. A mascot whose arms can't hold one is told why.

POST/mascots/{id}/gear

curl -X POST https://lumorig.com/api/v1/mascots/msc_…/gear -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" -d '{ "gear": "notes" }'

Its motion is a preset on that look: notes, read, type, sign, search, phone, sip, announce or ride. Send { "gear": "none" } to put the prop away and go back to the look it was added to.

Turn to the side#

A mascot drawn facing you can turn to a slight side view, up to about 30°, made from the same drawing: its face and front travel toward the turn while its outline stays. It is a look of its own, every animation plays from it, and it is instant and free. A full profile needs a new drawing: make it as a variant.

POST/mascots/{id}/turn

curl -X POST https://lumorig.com/api/v1/mascots/msc_…/turn -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" -d '{ "facing": "right" }'

Props#

A prop is something the mascot holds or wears that comes and goes: a mug, a frying pan, a crown. It is drawn as parts of its own, so hiding it leaves the mascot exactly as it was, and every animation works either way. The mascot lists them in mascot.props (id, name, on); a mascot rebuilt from a character sheet also suggests the props its other figures hold, in mascot.suggested_props.

POST/mascots/{id}/props/add

Adding a prop is an edit (a job of type edit). Showing or hiding one is instant and free, and saves a new version like a recolor:

POST/mascots/{id}/props

curl -X POST https://lumorig.com/api/v1/mascots/msc_…/props/add -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" -d '{ "description": "a small coffee mug in the left hand" }'

curl -X POST https://lumorig.com/api/v1/mascots/msc_…/props -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" -d '{ "on": { "coffee_mug": false } }'

An embed can switch props for itself, leaving the mascot as it is: <lumorig-player src="…" props="mug:off">.

An edit changes the character; a look is another version of it you can switch back to; a prop is one thing it holds or wears, on or off. Use an edit for fixes and design changes, a look for outfits, and a prop for anything that should come and go.

Versions#

Every drawing change (generate, rebuild, recolor, edit, variant, prop switch, manual spec) appends a version, and the mascot points at the newest one. List them to see the history, each with its own preview_url, and restore any of them to make it current again. Restoring doesn't delete anything newer.

curl https://lumorig.com/api/v1/mascots/msc_…/versions -H "Authorization: Bearer $LUMORIG_API_KEY"
curl -X POST https://lumorig.com/api/v1/mascots/msc_…/versions/ver_…/restore -H "Authorization: Bearer $LUMORIG_API_KEY"

Exporting an older version#

Exports accept version_id and previews accept v, so you can render any version without restoring it. See Export options.

Editing the spec directly#

A mascot is a MascotSpec JSON document, and you can replace it outright. The body is validated and sanitised like any agent output; an invalid spec returns 400 invalid_request with the problems in error.details. A valid one becomes a new version labelled Manual edit.

curl https://lumorig.com/api/v1/mascots/msc_…/spec -H "Authorization: Bearer $LUMORIG_API_KEY" > pip.json
# …edit pip.json…
curl -X PUT https://lumorig.com/api/v1/mascots/msc_…/spec -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" --data @pip.json
# 200 → { "mascot": { … }, "warnings": [ … ] }

warnings lists anything the SVG sanitiser removed (elements or attributes outside the allowed subset); the spec is saved without them. To create a brand-new mascot from a spec instead, POST /mascots with { "spec": … } (or lumorig.mascots.import(spec)); it answers 201 with no job.