There are four ways to change a mascot after it exists, from cheapest to most involved. Pick the smallest one that does the job: a recolor is instant and free, an edit redraws the character, and a variant branches a separate look that keeps every animation working. Every change makes a new version, so nothing is ever lost.
| Change | Endpoint | Speed | Credits |
|---|---|---|---|
| Recolor palette tokens | POST /mascots/{id}/recolor | Instant | 0 |
| Edit by instruction | POST /mascots/{id}/edit | Job, about 15 s | 40 |
| Look variant | POST /mascots/{id}/variants | Job | 60 |
| Replace the spec yourself | PUT /mascots/{id}/spec | Instant | 0 |
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
| Name | Type | Description |
|---|---|---|
paletterequired | object | Map of token name to #rrggbb. Only tokens the mascot already has are accepted; unknown names return 400 invalid_request listing the known ones. |
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
| Name | Type | Description |
|---|---|---|
instructionrequired | string | What to change, 2–2000 characters. |
max_cost_usd | number | Abort the job if model spend passes this. It can only lower the built-in ceiling, never raise it. See Credits & limits. |
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", … }Look variants#
A variant is a separate look for the same character: an outfit, a seasonal hat, a team jersey. The agent changes the drawing but keeps the rig (part ids, pivots and joint limits) compatible, so every preset and saved animation keeps working. Variants are saved as versions labelled Variant: <name>, with the name in version.variant.
POST/mascots/{id}/variants
| Name | Type | Description |
|---|---|---|
namerequired | string | Short label for the look, 1–60 characters, e.g. "santa". |
instructionrequired | string | What the look is, 2–2000 characters. |
max_cost_usd | number | Optional spend cap, as for edits. |
curl -X POST https://lumorig.com/api/v1/mascots/msc_…/variants -H "Authorization: Bearer $LUMORIG_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "santa", "instruction": "wearing a red santa hat and a tiny scarf" }'An edit changes the character; a variant is another look of it. Use an edit for fixes and design changes, a variant for anything you would want to switch back from.
Versions#
Every drawing change (generate, rebuild, recolor, edit, variant, 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.
| Endpoint | Does |
|---|---|
GET/mascots/{id}/versions | Newest first: id, parent_id, kind, label, variant, created_at, preview_url. |
POST/mascots/{id}/versions/{versionId}/restore | Makes that version current and returns the mascot. |
GET/mascots/{id}/spec?version=ver_… | The MascotSpec of any version. |
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.