REST API Reference

This page is generated from the OpenAPI 3.1 document at /api/v1/openapi.json, so it lists exactly what the server implements: 76 operations. Point any OpenAPI tool at that URL for client generation or a Postman collection.

Base URL#

base

https://lumorig.com/api/v1

Self-hosted servers use their own origin (MF_PUBLIC_URL). Every request needs Authorization: Bearer lr_sk_… except the ones marked no key needed. See Authentication.

Convention	Detail
Bodies	JSON (Content-Type: application/json). Uploads also take multipart/form-data.
Lists	`{ "object": "list", "data": [ … ] }`
Deletes	`{ "id": "…", "object": "…", "deleted": true }`
Long work	202 with a Job. Poll `GET /jobs/{id}?wait=60`, stream `/jobs/{id}/events`, or use a webhook.
Errors	`{ "error": { "code", "message", "details" } }`, see Errors.
Ids	Prefixed: `msc_` mascot, `anm_` animation, `cnv_` canvas, `ver_` version, `job_`, `file_`, `whk_`, `key_`.

Mascots#

GET/mascotsList mascots
POST/mascotsCreate a mascot
GET/mascots/{id}Get a mascot
PATCH/mascots/{id}Update a mascot
DELETE/mascots/{id}Delete a mascot
GET/mascots/{id}/specGet the MascotSpec
PUT/mascots/{id}/specReplace the MascotSpec (new version)
POST/mascots/{id}/recolorRecolor (instant)
POST/mascots/{id}/taglineSet a logo's tagline or web address
POST/mascots/{id}/editEdit by instruction
POST/mascots/{id}/looksSwitch to one of the mascot's looks by name (instant, free)
POST/mascots/{id}/turnTurn to a slight side view, as a look of its own (instant, free)
POST/mascots/{id}/gearGive the mascot a ready-made prop, as a look of its own with its motion (instant, free)
POST/mascots/{id}/propsShow or hide props (instant, free)
POST/mascots/{id}/props/addAdd a prop drawn as its own part (an edit job)
POST/mascots/{id}/variantsCreate a new look of the same rig (the current look is kept)
POST/mascots/{id}/retryRetry a failed creation (same upload and notes, or the same prompt; priced like the first time)
POST/mascots/{id}/pictures/{fileId}/useRig a picked design picture
GET/mascots/{id}/versionsList versions
POST/mascots/{id}/versions/{versionId}/restoreRestore a version
GET/mascots/{id}/previewRender a still
GET/mascots/{id}/bundlePlayer bundle for <lumorig-player>
POST/mascots/{id}/shareCreate an expiring share link
POST/analyzeMascot concepts from a website

List mascots#

GET/mascots

Response · 200

Mascots

List mascots response
Field	Type	Notes
`object`	"list"
`data`	Mascot[]

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Create a mascot#

POST/mascots

prompt designs a new mascot; upload_id/image_url rebuilds an existing one as a rigged vector; spec imports a MascotSpec directly (synchronous, 201).

Request body

One of 2 shapes:

Option 1 · prompt, style…

Create a mascot body, option 1
Field	Type	Notes
`prompt`	string	3–2000 chars
`style`	string	0–400 chars
`upload_id`	string
`image_url`	string (uri)
`name`	string	0–80 chars
`notes`	string	0–1000 chars
`detail`	"standard" \| "high"	high: richer rendering at a higher credit price
`engine`	"clips" \| "rebuild" \| "logo"	Uploads only. clips: your exact art, animated as video clips. rebuild: redrawn as a rigged vector (Inker). logo: a logo's own shapes traced into pieces (letters, marks, its badge) that play the logo motions (reveal, pop, spin…); 60 credits, ready at once.
`motions`	string[]	Clip uploads: the clips to make first (default wave; 19 presets).max 11 items
`pictures`	integer	Prompts: draw this many design pictures first (10 credits each) and wait for a pick: POST /mascots/{id}/pictures/{file_id}/use rigs the one you choose (90 credits). Without it, one picture is drawn and rigged straight away (100 credits). Style "realistic" is always pictures first and animated as video: POST /mascots/{id}/pictures/{file_id}/animate (the breathing rest is free, 60 credits a motion); without pictures, one is drawn and animated at once.1–4
`take`	integer	Prompts: which take of a batch this is (1-based); each take gets its own art direction.1–8
`takes`	integer	Prompts: how many takes the batch has.1–8
`batch`	string	Prompts: an id shared by the takes of one batch.0–80 chars
`max_credits`	number	Your own cap: the most credits this job may charge. A job whose work would pass it is stopped and refunded. Without it, a job you paid for always finishes, and model work past its price is charged once it has delivered.> 0

Option 2 · with spec

Create a mascot body, option 2
Field	Type	Notes
`spec`required	MascotSpec
`name`	string

Response · 202

Mascot and its generation job

Create a mascot response
Field	Type	Notes
`mascot`	Mascot
`job`	Job

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a sleepy moth who guards the docs","style":"outlined"}'

Get a mascot#

GET/mascots/{id}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`include`	"spec" · query

Response · 200

Mascot

A Mascot object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123?include=spec" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Update a mascot#

PATCH/mascots/{id}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Update a mascot body
Field	Type	Notes
`name`	string
`public`	boolean

Response · 200

Mascot

A Mascot object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X PATCH "https://lumorig.com/api/v1/mascots/msc_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"public":true}'

Delete a mascot#

DELETE/mascots/{id}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Response · 200

Deleted

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X DELETE "https://lumorig.com/api/v1/mascots/msc_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Get the MascotSpec#

GET/mascots/{id}/spec

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`version`	string · query

Response · 200

Spec

A MascotSpec object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/spec" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Replace the MascotSpec (new version)#

PUT/mascots/{id}/spec

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

A MascotSpec object.

Response · 200

Mascot

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X PUT "https://lumorig.com/api/v1/mascots/msc_123/spec" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d @spec.json

Recolor (instant)#

POST/mascots/{id}/recolor

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Recolor (instant) body
Field	Type	Notes
`palette`required	record<string, string>

Response · 200

Mascot

A Mascot object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/recolor" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"palette":{"body":"#3a5bff"}}'

Set a logo's tagline or web address#

POST/mascots/{id}/tagline

A logo only (engine "logo"): a line under it in one of three fonts, brought in by every intro as the logo locks. 10 credits to set or change; empty text takes it off, free.

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Set a logo's tagline or web address body
Field	Type	Notes
`text`required	string	0–60 chars
`font`	"sans" \| "bold" \| "mono"

Response · 200

Mascot

A Mascot object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

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

Edit by instruction#

POST/mascots/{id}/edit

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Edit by instruction body
Field	Type	Notes
`instruction`required	string
`max_credits`	number	Your own cap: the most credits this job may charge. A job whose work would pass it is stopped and refunded. Without it, a job you paid for always finishes, and model work past its price is charged once it has delivered.

Response · 202

Job

A Job object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/edit" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instruction":"make the antennae longer"}'

Switch to one of the mascot's looks by name (instant, free)#

POST/mascots/{id}/looks

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Switch to one of the mascot's looks by name (instant, free) body
Field	Type	Notes
`look`required	string	"Original" or a variant's name (mascot.looks)

Response · 200

Mascot

A Mascot object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

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

Turn to a slight side view, as a look of its own (instant, free)#

POST/mascots/{id}/turn

Made from the same drawing with no model: the face and front travel toward the turn, the outline stays. Up to about 30°; a full profile needs a new drawing (variants). front goes back to the look it was turned from.

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Turn to a slight side view, as a look of its own (instant, free) body
Field	Type	Notes
`facing`required	"left" \| "right" \| "front"
`amount`	"slight" \| "three-quarter"	Default three-quarter (30°); slight is 18°

Response · 200

Mascot

A Mascot object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

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

Give the mascot a ready-made prop, as a look of its own with its motion (instant, free)#

POST/mascots/{id}/gear

The arms are posed into the drawing and the prop is drawn in the mascot's outline and colours, with no model. Each prop's motion becomes available on that look: notes → notes, book → read, laptop → type, sign → sign, magnifier → search, phone → phone, mug → sip, megaphone → announce, skateboard → ride, stool (it sits), party (a hat, confetti in celebrate). A character whose arms can't reach gets a 400 saying why. none puts it away.

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Give the mascot a ready-made prop, as a look of its own with its motion (instant, free) body
Field	Type	Notes
`gear`required	enum (12 values)	notes, book, laptop, sign, magnifier, phone, mug, megaphone, skateboard, stool, party, none

Response · 200

Mascot

A Mascot object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

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

Show or hide props (instant, free)#

POST/mascots/{id}/props

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Show or hide props (instant, free) body
Field	Type	Notes
`on`required	record<string, boolean>	Prop id → shown

Response · 200

Mascot

A Mascot object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

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

Add a prop drawn as its own part (an edit job)#

POST/mascots/{id}/props/add

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Add a prop drawn as its own part (an edit job) body
Field	Type	Notes
`description`required	string
`name`	string
`max_credits`	number	Your own cap: the most credits this job may charge. A job whose work would pass it is stopped and refunded. Without it, a job you paid for always finishes, and model work past its price is charged once it has delivered.

Response · 202

Job

A Job object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

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

Create a new look of the same rig (the current look is kept)#

POST/mascots/{id}/variants

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Create a new look of the same rig (the current look is kept) body
Field	Type	Notes
`name`required	string
`instruction`required	string
`max_credits`	number	Your own cap: the most credits this job may charge. A job whose work would pass it is stopped and refunded. Without it, a job you paid for always finishes, and model work past its price is charged once it has delivered.

Response · 202

Job

A Job object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

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

Retry a failed creation (same upload and notes, or the same prompt; priced like the first time)#

POST/mascots/{id}/retry

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Response · 202

Mascot and job

Retry a failed creation (same upload and notes, or the same prompt; priced like the first time) response
Field	Type	Notes
`mascot`	Mascot
`job`	Job

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/retry" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Rig a picked design picture#

POST/mascots/{id}/pictures/{fileId}/use

A mascot from words drawn pictures first (pictures on create) waits in status: "choosing"; this redraws the picked picture as a rigged vector (90 credits).

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`fileId`required	string · path

Request body

Rig a picked design picture body
Field	Type	Notes
`max_credits`	number	Your own cap: the most credits this job may charge. A job whose work would pass it is stopped and refunded. Without it, a job you paid for always finishes, and model work past its price is charged once it has delivered.

Response · 202

Mascot and job

Rig a picked design picture response
Field	Type	Notes
`mascot`	Mascot
`job`	Job

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/pictures/fileId_123/use" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

List versions#

GET/mascots/{id}/versions

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Response · 200

Versions

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/versions" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Restore a version#

POST/mascots/{id}/versions/{versionId}/restore

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`versionId`required	string · path

Response · 200

Mascot

A Mascot object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/versions/ver_123/restore" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Render a still#

GET/mascots/{id}/preview

Synchronous. Works with no key for public mascots.

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`format`	"png" \| "svg" \| "sticker" \| "logo" · query
`animation`	string · query
`t`	number · query	≥ 0
`size`	number · query	16–2048
`v`	string · query	Version id (makes the response cacheable)

Response · 200 · image/png, image/svg+xml

Image

Errors: 400 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/preview?format=png&animation=wave&t=0.4&size=512" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Player bundle for <lumorig-player>#

GET/mascots/{id}/bundleno key needed

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`token`	string · query	Signed share token for private mascots
`look`	string · query	A look by name instead of the current one
`props`	string · query	Props shown or hidden in this bundle only, e.g. mug:off,crown:on

Response · 200

Bundle

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/bundle"

POST/mascots/{id}/share

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Create an expiring share link body
Field	Type	Notes
`ttl_seconds`	integer

Response · 200

Share link

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/share" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds":86400}'

Mascot concepts from a website#

POST/analyze

Request body

Mascot concepts from a website body
Field	Type	Notes
`url`required	string (uri)

Response · 202

Job (result: brand analysis + 3 concepts)

A Job object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/analyze" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Animations#

GET/mascots/{id}/animationsList animations
POST/mascots/{id}/animationsCreate an animation
GET/mascots/{id}/animations/{animationId}Get an animation (with clip)
DELETE/mascots/{id}/animations/{animationId}Delete an animation
POST/mascots/{id}/animations/batchCreate several described animations
POST/mascots/{id}/suggestionsSuggest signature animations

List animations#

GET/mascots/{id}/animations

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Response · 200

Animations

List animations response
Field	Type	Notes
`object`	"list"
`data`	Animation[]

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/animations" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Create an animation#

POST/mascots/{id}/animations

preset is instant and free (201). prompt runs the motion designer (202 + job). reference_upload_id (an uploaded MP4/MOV/WebM) makes the mascot perform the motion in the video (202 + job). clip saves a hand-authored AnimationClip.

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

One of 4 shapes:

Option 1 · with preset

Create an animation body, option 1
Field	Type	Notes
`preset`required	enum (72 values)	idle, wave, nod, shake, bounce, celebrate, jump, talk, sad, surprised, dance, think, working, listen, sleep, fly, point, shrug, float, peek, laugh, type, ride, notes, read, sign, search, phone, sip, announce, walk, fade, draw, wipe, gleam, colour, neon, markname, behind, baseline, unveil, write, tracking, reveal, rise, typewriter, assemble, drop, pop, stamp, slide, merge, spread, flipin, tumble, standup, rollin, jackbox, flicker, shine, colourrun, pulse, wiggle, tada, jelly, swing, spin, flip, ripple, bop, glitch, scatter
`intensity`	number	0.25–2
`duration`	number	0.3–20
`arm`	"auto" \| "left" \| "right" \| "both"
`name`	string	0–60 chars

Option 2 · with prompt

Create an animation body, option 2
Field	Type	Notes
`prompt`required	string	3–1000 chars
`duration`	number	0.3–20
`name`	string	0–60 chars
`max_credits`	number	Your own cap: the most credits this job may charge. A job whose work would pass it is stopped and refunded. Without it, a job you paid for always finishes, and model work past its price is charged once it has delivered.> 0

Option 3 · with clip, name

Create an animation body, option 3
Field	Type	Notes
`clip`required	any
`name`required	string	0–60 chars

Option 4 · with reference_upload_id

Create an animation body, option 4
Field	Type	Notes
`reference_upload_id`required	string	An uploaded MP4/MOV/WebM whose motion the mascot should perform
`prompt`	string	0–1000 chars
`duration`	number	0.3–12
`name`	string	0–60 chars
`max_credits`	number	Your own cap: the most credits this job may charge. A job whose work would pass it is stopped and refunded. Without it, a job you paid for always finishes, and model work past its price is charged once it has delivered.> 0

Response · 201

Animation (preset/clip) or {job} (prompt)

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/animations" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset":"wave","intensity":1.2}'

Get an animation (with clip)#

GET/mascots/{id}/animations/{animationId}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`animationId`required	string · path

Response · 200

Animation

A Animation object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/animations/anm_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Delete an animation#

DELETE/mascots/{id}/animations/{animationId}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`animationId`required	string · path

Response · 200

Deleted

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X DELETE "https://lumorig.com/api/v1/mascots/msc_123/animations/anm_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Create several described animations#

POST/mascots/{id}/animations/batch

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Create several described animations body
Field	Type	Notes
`prompts`required	string[]	max 8 items
`duration`	number

Response · 202

Jobs

Create several described animations response
Field	Type	Notes
`object`	"list"
`data`	Job[]

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/animations/batch" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompts":["hops twice, then bows","peeks out from behind the desk"]}'

Suggest signature animations#

POST/mascots/{id}/suggestions

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Suggest signature animations body
Field	Type	Notes
`use_case`	string

Response · 200

Finished job (result.suggestions)

A Job object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/suggestions" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"use_case":"docs site helper that appears on empty search results"}'

Exports#

GET/mascots/{id}/cinematicsList a logo's cinematic intros
POST/mascots/{id}/cinematicsMake a logo's cinematic intro
DELETE/mascots/{id}/cinematics/{cinematicId}Delete a cinematic intro
GET/mascots/{id}/cinematics/{cinematicId}/videoA cinematic intro's MP4
POST/mascots/{id}/scenesCreate an illustrated vector scene
POST/mascots/{id}/exportsExport
GET/files/{id}Download a file

List a logo's cinematic intros#

GET/mascots/{id}/cinematics

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Response · 200

Cinematic intros (data[]: id, style, backdrop, frame, width, height, duration, lock, video_url)

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/cinematics" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Make a logo's cinematic intro#

POST/mascots/{id}/cinematics

A logo only: generated sparks, smoke or ink that resolve into the logo, then a blend into the logo exactly as drawn, held 1.5 s. A 1080p H.264 MP4 of about 5 s. 60 credits, a job of a few minutes; a take that doesn't end on the logo is made again at no cost, then the job fails and is refunded. A backdrop the logo's badge or letters would vanish on is a 400, nothing charged.

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Make a logo's cinematic intro body
Field	Type	Notes
`style`required	"sparks" \| "smoke" \| "ink"
`backdrop`	string	dark, light or #rrggbb (the style's own by default)
`frame`	"landscape" \| "portrait" \| "square"

Response · 202

Job (result.cinematic)

A Job object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

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

Delete a cinematic intro#

DELETE/mascots/{id}/cinematics/{cinematicId}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`cinematicId`required	string · path

Response · 200

Deleted

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X DELETE "https://lumorig.com/api/v1/mascots/msc_123/cinematics/cinematicId_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

A cinematic intro's MP4#

GET/mascots/{id}/cinematics/{cinematicId}/video

Free: at most 512 px with the small mark; Maker and Studio: the full file. Byte ranges are answered.

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`cinematicId`required	string · path
`sound`	"whoosh" \| "chime" \| "pluck" \| "digital" · query	A reveal sound under it, its hit on the burst
`download`	string · query	1: saved as a file

Response · 200

video/mp4

string (binary)

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/cinematics/cinematicId_123/video" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Create an illustrated vector scene#

POST/mascots/{id}/scenes

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Create an illustrated vector scene body
Field	Type	Notes
`prompt`required	string
`size`	"square" \| "wide" \| "banner" \| "portrait"
`animation`	string
`t`	number
`max_credits`	number	Your own cap: the most credits this job may charge. A job whose work would pass it is stopped and refunded. Without it, a job you paid for always finishes, and model work past its price is charged once it has delivered.

Response · 202

Job (result.svg, result.png)

A Job object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/scenes" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"cozy desk at night, leave the left half calm for copy","size":"wide"}'

Export#

POST/mascots/{id}/exports

No model call. Maker and Studio: every format, no credits. Free: watermarked png, gif and email-gif up to 512 px, the first animation downloaded of a character is free (any allowed format and size, and also as lottie, dotlottie or animated-svg with the mark); anything else of it costs 50 credits once and unlocks all its downloads (402 insufficient_credits without enough). Mascot.free_download says which animation is the free one.

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Export body
Field	Type	Notes
`format`required	enum (18 values)	gif, email-gif, mp4, webm, mov, prores, wav, webp, apng, sprite, lottie, dotlottie, animated-svg, png, svg, sticker, logo, logo-png
`animation`	string
`size`	integer	64–2048
`fps`	integer	6–60
`background`	string	pattern ^#[0-9a-fA-F]{6}$
`t`	number	≥ 0
`version_id`	string
`duration`	number	Seconds: plays the whole animation in this time (a logo intro as a 1 s app splash or a 2 s sting)0.3–20
`frame`	"square" \| "landscape" \| "portrait" \| "feed" \| "tight"	The video's shape: square (default), landscape 16:9, portrait 9:16 or feed 4:5, the mascot centred, or tight, cropped close around a logo (an email GIF of a logo's default); for GIF, video, WebP, APNG and animated SVG
`sound`	"whoosh" \| "chime" \| "pluck" \| "digital"	A logo intro's reveal sound, timed to the motion (a build that peaks as the logo locks, then a hit): whoosh, chime, pluck or digital; in MP4, MOV and ProRes, or alone as format wav

Response · 202

Job (result.file)

A Job object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/exports" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format":"lottie","animation":"wave"}'

Download a file#

GET/files/{id}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path
`download`	string · query

Response · 200

File bytes

curl

curl "https://lumorig.com/api/v1/files/file_123?download=1" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -o mascot.json

Canvases#

GET/mascots/{id}/canvasesList canvases
POST/mascots/{id}/canvasesCreate a canvas
PATCH/mascots/{id}/canvases/{canvasId}Update a canvas
DELETE/mascots/{id}/canvases/{canvasId}Delete a canvas

List canvases#

GET/mascots/{id}/canvases

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Response · 200

Canvases

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/canvases" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Create a canvas#

POST/mascots/{id}/canvases

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Create a canvas body
Field	Type	Notes
`name`required	string
`template`	"chatbot" \| "ai_agent" \| "onboarding"
`graph`	CanvasGraph

Response · 201

Canvas

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/canvases" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"assistant","template":"chatbot"}'

Update a canvas#

PATCH/mascots/{id}/canvases/{canvasId}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`canvasId`required	string · path

Request body

Update a canvas body
Field	Type	Notes
`name`	string
`graph`	CanvasGraph

Response · 200

Canvas

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X PATCH "https://lumorig.com/api/v1/mascots/msc_123/canvases/cnv_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"helper"}'

Delete a canvas#

DELETE/mascots/{id}/canvases/{canvasId}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`canvasId`required	string · path

Response · 200

Deleted

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X DELETE "https://lumorig.com/api/v1/mascots/msc_123/canvases/cnv_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Jobs#

GET/jobsList jobs
GET/jobs/{id}Get a job (long-poll with ?wait=seconds, max 120)
GET/jobs/{id}/eventsStream job events (SSE)
POST/jobs/{id}/cancelCancel a job

List jobs#

GET/jobs

Parameters

Parameters
Field	Type	Notes
`status`	string · query
`type`	string · query
`mascot_id`	string · query
`limit`	string · query

Response · 200

Jobs

List jobs response
Field	Type	Notes
`object`	"list"
`data`	Job[]

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/jobs" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Get a job (long-poll with ?wait=seconds, max 120)#

GET/jobs/{id}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path
`wait`	integer · query	≤ 120

Response · 200

Job

A Job object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/jobs/job_123?wait=60" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Stream job events (SSE)#

GET/jobs/{id}/events

Parameters

Parameters
Field	Type	Notes
`id`required	string · path
`after`	integer · query

Response · 200 · text/event-stream

text/event-stream: queued, started, progress, tool_call, tool_input_delta, draft, usage, finished

curl

curl -N "https://lumorig.com/api/v1/jobs/job_123/events" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Cancel a job#

POST/jobs/{id}/cancel

Parameters

Parameters
Field	Type	Notes
`id`required	string · path

Response · 200

Job

A Job object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/jobs/job_123/cancel" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Uploads#

POST/uploadsUpload an image

Upload an image#

POST/uploads

Request body · multipart/form-data or application/json

multipart/form-data

Upload an image body
Field	Type	Notes
`file`	string (binary)

application/json

Upload an image body
Field	Type	Notes
`url`	string (uri)

Response · 201

Uploaded file

A File object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/uploads" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -F "file=@./mascot.png"

List webhooks#

GET/webhooks

Response · 200

Webhooks

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/webhooks" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Create a webhook#

POST/webhooks

Deliveries are signed: Lumorig-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "t.body">.

Request body

Create a webhook body
Field	Type	Notes
`url`required	string (uri)
`events`	"job.succeeded" \| "job.failed" \| "job.canceled" \| "*"[]	items: job.succeeded, job.failed, job.canceled, *

Response · 201

Webhook (secret shown once)

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/webhooks" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your.app/hooks/lumorig","events":["job.succeeded","job.failed"]}'

Delete a webhook#

DELETE/webhooks/{id}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path

Response · 200

Deleted

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X DELETE "https://lumorig.com/api/v1/webhooks/whk_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Workspace#

GET/workspaceGet the current workspace
PATCH/workspaceRename the workspace
GET/workspace/membersList members
PATCH/workspace/members/{userId}Change a member's role
DELETE/workspace/members/{userId}Remove a member, or leave
POST/workspace/transferTransfer ownership
DELETE/workspace/invites/{id}Revoke a pending invite
POST/workspace/invites/{id}/resendResend an invite with a fresh link
GET/workspace/invitesList pending invites
POST/workspace/invitesInvite someone by email

Get the current workspace#

GET/workspace

Name, plan, your role and seats (limit, members, pending, used, available). With an API key: the key's workspace. With a studio session: the active workspace (the Lumorig-Workspace header selects another one you belong to).

Response · 200

Workspace

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/workspace" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Rename the workspace#

PATCH/workspace

Admins. Studio session only: API keys get 403 session_required.

Request body

Rename the workspace body
Field	Type	Notes
`name`	string

Response · 200

Workspace

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X PATCH "https://lumorig.com/api/v1/workspace" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

List members#

GET/workspace/members

Response · 200

Members (owner first)

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/workspace/members" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Change a member's role#

PATCH/workspace/members/{userId}

Admins; only the owner changes another admin. Studio session only: API keys get 403 session_required.

Parameters

Parameters
Field	Type	Notes
`userId`required	string · path	Member user id (usr_…); your own id to leave

Request body

Change a member's role body
Field	Type	Notes
`role`required	"member" \| "admin"

Response · 200

Member

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X PATCH "https://lumorig.com/api/v1/workspace/members/userId_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"…"}'

Remove a member, or leave#

DELETE/workspace/members/{userId}

Admins remove others; anyone can pass their own id to leave (owners transfer first). Studio session only: API keys get 403 session_required.

Parameters

Parameters
Field	Type	Notes
`userId`required	string · path	Member user id (usr_…); your own id to leave

Response · 200

Removed

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X DELETE "https://lumorig.com/api/v1/workspace/members/userId_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Transfer ownership#

POST/workspace/transfer

Owner only; you become an admin. Studio session only: API keys get 403 session_required.

Request body

Transfer ownership body
Field	Type	Notes
`user_id`required	string

Response · 200

Members

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

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

Revoke a pending invite#

DELETE/workspace/invites/{id}

Admins. Studio session only: API keys get 403 session_required.

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Invite id

Response · 200

Revoked invite

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X DELETE "https://lumorig.com/api/v1/workspace/invites/msc_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Resend an invite with a fresh link#

POST/workspace/invites/{id}/resend

Admins. The previous link stops working. Studio session only: API keys get 403 session_required.

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Invite id

Response · 200

Invite and its new link

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/workspace/invites/msc_123/resend" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

List pending invites#

GET/workspace/invites

Admins and the owner (API keys can read the list; changing invites needs a studio session).

Response · 200

Invites

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/workspace/invites" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Invite someone by email#

POST/workspace/invites

Studio session only (API keys get 403 session_required). A pending invite holds a seat for 7 days; beyond the plan's seats the response is 402 seat_limit with details: { seats, used, members, pending }.

Request body

Invite someone by email body
Field	Type	Notes
`email`required	string (email)
`role`	"member" \| "admin"

Response · 201

Invite and its link (shown once)

Invite someone by email response
Field	Type	Notes
`invite`	object
`invite_url`	string

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

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

Account#

DELETE/keys/{id}Revoke an API key
GET/keysList API keys
POST/keysCreate an API key
GET/usageCredits used, by job type
GET/creditsCredit balances, plan, credit packs, and per-action prices

Revoke an API key#

DELETE/keys/{id}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path

Response · 200

Revoked

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X DELETE "https://lumorig.com/api/v1/keys/key_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

List API keys#

GET/keys

Response · 200

Keys

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/keys" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Create an API key#

POST/keys

Request body

Create an API key body
Field	Type	Notes
`name`	string

Response · 201

Key (shown once)

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/keys" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI"}'

Credits used, by job type#

GET/usage

Response · 200

Usage

Credits used, by job type response
Field	Type	Notes
`object`	"usage"
`credits`	object
`total_credits`	integer
`by_type`	object[]

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/usage" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Credit balances, plan, credit packs, and per-action prices#

GET/credits

A job that makes something takes its price in credits when it starts (plan credits first, then pack credits) and refunds them if it fails or is canceled. Occasionally a job uses more than its listed price; the difference is charged after it delivers (its extra_credits), as far as the balance goes and never past its max_credits. Without enough credits they return 402 insufficient_credits, with details.buy_credits_url (where this plan's packs are sold) and, on Free, details.upgrade_url. A Free workspace's first creation (a character from words, a rebuild, a clip) runs even when the allowance is short: the shortfall, up to first_result credits, is granted once; so does its first chat edit, up to first_edit credits.

Response · 200

Credits

A Credits object.

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/credits" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Catalog#

GET/clip-motionsList clip motions (presets for clip mascots)
GET/presetsList animation presets
GET/stylesList style presets
GET/canvas-templatesList canvas templates

List clip motions (presets for clip mascots)#

GET/clip-motionsno key needed

Response · 200

Motions

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/clip-motions"

List animation presets#

GET/presetsno key needed

Response · 200

Presets

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/presets"

List style presets#

GET/stylesno key needed

Response · 200

Styles

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/styles"

List canvas templates#

GET/canvas-templatesno key needed

Response · 200

Templates

object

Errors: 400 · 401 · 404 · 429 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/canvas-templates"

Schemas#

Shared objects referenced above. The full MascotSpec and AnimationClip formats are explained in MascotSpec & AnimationClip.

MascotSpec#

MascotSpec fields
Field	Type	Notes
`specVersion`required	1
`name`required	string	1–∞ chars
`description`required	string
`archetype`required	"biped" \| "quadruped" \| "blob" \| "winged" \| "object" \| "custom"
`canvas`required	object
`palette`required	object[]
`parts`required	object[]
`anchors`required	object[]
`engine`	"inker" \| "logo"
`face`	object
`cropped`	boolean
`stance`	"standing" \| "hanging" \| "seated" \| "floating"
`gear`	string
`view`	number
`props`	object[]
`tagline`	object
`meta`	object

AnimationClip#

AnimationClip fields
Field	Type	Notes
`clipVersion`required	1
`name`required	string	1–∞ chars
`duration`required	number	Seconds0.2–20
`loop`required	boolean
`tracks`required	object \| object[]
`modifiers`required	object \| object \| object[]
`notes`	string[]
`letGo`	string[]
`joints`	object[]
`effects`	object[]

CanvasGraph#

CanvasGraph fields
Field	Type	Notes
`canvasVersion`required	1
`inputs`required	object[]
`states`required	object[]
`initial`required	string	pattern ^[a-z][a-z0-9_]*$
`transitions`required	object[]

ErrorResponse#

ErrorResponse fields
Field	Type	Notes
`error`	object

File#

File fields
Field	Type	Notes
`id`	string
`object`	"file"
`kind`	string
`mime`	string
`bytes`	integer
`url`	string
`created_at`	string

Job#

Job fields
Field	Type	Notes
`id`	string
`object`	"job"
`type`	enum (16 values)	generate, reconstruct, edit, variant, animate, export, analyze, suggest, scene, expressions, clip, art_edit, picture, logo, tagline, cinematic
`status`	"queued" \| "running" \| "succeeded" \| "failed" \| "canceled"
`mascot_id`	string \| null
`result`	any
`error`	string \| null
`credits`	integer	Credits this job costs: its price, less any refund, plus any extra_credits. Free jobs: 0.
`extra_credits`	integer	Credits charged after the job delivered, past its listed price (as far as the balance went, never past max_credits). Usually 0.
`created_at`	string
`started_at`	string \| null
`finished_at`	string \| null

Animation#

Animation fields
Field	Type	Notes
`id`	string
`name`	string
`source`	"preset" \| "prompt" \| "custom"
`preset`	enum (72 values)	idle, wave, nod, shake, bounce, celebrate, jump, talk, sad, surprised, dance, think, working, listen, sleep, fly, point, shrug, float, peek, laugh, type, ride, notes, read, sign, search, phone, sip, announce, walk, fade, draw, wipe, gleam, colour, neon, markname, behind, baseline, unveil, write, tracking, reveal, rise, typewriter, assemble, drop, pop, stamp, slide, merge, spread, flipin, tumble, standup, rollin, jackbox, flicker, shine, colourrun, pulse, wiggle, tada, jelly, swing, spin, flip, ripple, bop, glitch, scatter
`duration`	number
`loop`	boolean
`clip`	AnimationClip

Mascot#

Mascot fields
Field	Type	Notes
`id`	string
`object`	"mascot"
`kind`	"vector" \| "clips"	vector: a rigged MascotSpec (animations); clips: your own art animated as video (clips)
`clips`	Clip[]
`name`	string
`status`	"generating" \| "ready" \| "failed"
`source`	"prompt" \| "image" \| "svg"
`fidelity`	number \| null	Rebuild similarity to the upload (0–1)
`needs_review`	boolean
`palette`	object[]
`looks`	object[]
`props`	object[]
`suggested_props`	string[]
`parts`	object[]
`animations`	Animation[]
`preview_url`	string \| null
`bundle_url`	string
`upload_url`	string \| null	The picture a rebuild was made from; null for a mascot from words
`downloads_unlocked`	boolean	Downloads cost nothing more: a paid plan, or on Free a character whose downloads were unlocked.
`free_download`	string \| null	Free plan, not unlocked: the one animation that downloads free (an animation name or a clip id). Null while none has been downloaded: the first animation downloaded becomes it.

ExportFormat#

Clip#

Clip fields
Field	Type	Notes
`id`	string
`object`	"clip"
`name`	string
`motion`	string \| null
`prompt`	string \| null
`status`	"generating" \| "ready" \| "failed"
`regenerating`	boolean
`loop`	boolean
`duration`	number \| null
`size`	integer \| null	Master resolution, px
`full_size`	integer \| null	The largest download: the figure's longest side at the master's resolution, px
`attempts`	integer \| null
`checks`	object \| null
`error`	string \| null
`preview_url`	string \| null
`rest_url`	string \| null

Credits#

Credits fields
Field	Type	Notes
`object`	"credits"
`billing`	boolean	False on unmetered installs (balances are null).
`plan`	object
`balance`	integer \| null	Everything spendable: plan_balance + pack_balance.
`plan_balance`	integer \| null	This month's plan credits. Reset to the allowance each month; unused ones expire. Spent first.
`first_result`	integer	Free, before its first creation has finished: credits granted on top of the balance if that first creation is short, so a first result never meets the paywall. 0 otherwise.
`first_motion`	integer	Free, before its first described motion has finished: credits granted on top of the balance if that motion is short, when the character's description asked for motion. 0 otherwise.
`first_edit`	integer	Free, before its first chat edit has finished: credits granted on top of the balance if that first edit is short, so the first change to a first result never meets the paywall either. 0 otherwise.
`pack_balance`	integer \| null	Bought credit-pack credits. Never expire; spent after plan credits.
`packs`	object[]	The packs this plan can buy (Free: the smallest).
`can_buy_packs`	boolean	This plan can buy the packs listed: Maker and Studio any, Free the smallest.
`prices`	record<string, integer>	Credits per priced action: model-backed jobs, and `download` (unlocking a character's downloads on the Free plan).
`note`	string	Why this workspace gets no monthly credits, when it gets none.
`upload_engines`	"clips" \| "rebuild" \| "logo"[]	What `engine` can be when creating a mascot from an upload.items: clips, rebuild, logo

InsufficientCreditsDetails#

details of a 402 insufficient_credits error.

InsufficientCreditsDetails fields
Field	Type	Notes
`needed`	integer
`balance`	integer
`buy_credits_url`	string	Where to buy a credit pack.
`upgrade_url`	string	Free: where to upgrade (alongside its one-off pack).

REST API

Base URL#

Mascots#

List mascots#

Create a mascot#

Get a mascot#

Update a mascot#

Delete a mascot#

Get the MascotSpec#

Replace the MascotSpec (new version)#

Recolor (instant)#

Set a logo's tagline or web address#

Edit by instruction#

Switch to one of the mascot's looks by name (instant, free)#

Turn to a slight side view, as a look of its own (instant, free)#

Give the mascot a ready-made prop, as a look of its own with its motion (instant, free)#

Show or hide props (instant, free)#

Add a prop drawn as its own part (an edit job)#

Create a new look of the same rig (the current look is kept)#

Retry a failed creation (same upload and notes, or the same prompt; priced like the first time)#

Rig a picked design picture#

List versions#

Restore a version#

Render a still#

Player bundle for <lumorig-player>#

Create an expiring share link#

Mascot concepts from a website#

Animations#

List animations#

Create an animation#

Get an animation (with clip)#

Delete an animation#

Create several described animations#

Suggest signature animations#

Exports#

List a logo's cinematic intros#

Make a logo's cinematic intro#

Delete a cinematic intro#

A cinematic intro's MP4#

Create an illustrated vector scene#

Export#

Download a file#

Canvases#

List canvases#

Create a canvas#

Update a canvas#

Delete a canvas#

Jobs#

List jobs#

Get a job (long-poll with ?wait=seconds, max 120)#

Stream job events (SSE)#

Cancel a job#

Uploads#

Upload an image#

Webhooks#

List webhooks#

Create a webhook#

Delete a webhook#

Workspace#

Get the current workspace#

Rename the workspace#

List members#

Change a member's role#

Remove a member, or leave#

Transfer ownership#

Revoke a pending invite#

Resend an invite with a fresh link#

List pending invites#

Invite someone by email#

Account#

Revoke an API key#

List API keys#

Create an API key#

Credits used, by job type#

Credit balances, plan, credit packs, and per-action prices#

Catalog#

List clip motions (presets for clip mascots)#

List animation presets#

List style presets#

List canvas templates#