Credits & limits

Credits pay for the moments Lumorig draws, rebuilds, choreographs or edits something new. Prices are fixed per action, so you know the cost before you send the request. Moving and recolouring what you already have never costs anything, and neither does downloading it on Maker and Studio; on Free, one animation of each character downloads free and 50 credits unlocks the rest.

Prices per action#

GET /credits returns these same prices under prices, keyed by action name, so clients can show a cost before the user confirms.

Plans#

Paid plans grant credits every month. Free starts you with 100 credits, once (they don't refill or expire), and your first character runs even when it costs more. Here is what those credits buy if you spend them all on one kind of action:

• Allowances reset monthly. At the start of each calendar month your plan credits are set back to the plan's allowance. Unused plan credits don't roll over. Pack credits aren't touched.
• Rate limits apply to API keys. Requests authenticated with a key (REST, MCP, CLI, SDK) count against a one-minute window per workspace. Over it, you get 429 rate_limited with a Retry-After header. The studio in your browser isn't limited.
• Credits belong to the workspace. Everyone in a team workspace spends from one balance; seats cap how many people that is (pending invites count). See Workspaces, roles and seats.
• Need more credits? Buy a credit pack (below) or move up a plan. Free can buy the smallest pack without subscribing; the larger packs come with Maker and Studio.

Credit packs#

One-time top-ups, bought in the studio under Settings → Plan. Maker and Studio can buy any pack; Free can buy the smallest, with no subscription.

• Pack credits never expire. They stay through monthly resets and plan changes, even a move to Free.
• Plan credits are spent first. A job takes this month's plan credits, then pack credits for the rest. A refund puts each credit back where it came from.
• A refunded pack takes its credits back, as far as they're unspent.

Plan features beyond credits are on the pricing page.

Always free#

These never touch your balance, on any plan (downloads are free on Maker and Studio; on Free they are priced above):

• Presets: all 18 (and fly on winged characters), fitted to your rig (POST /mascots/{id}/animations { preset }).
• Recolor by palette token.
• Canvases: creating, editing and running state machines.
• Previews: rendered stills from GET /mascots/{id}/preview.
• Embeds: bundles for <lumorig-player>, however many views they get.

Also free: uploads, importing a spec you wrote, restoring versions, share links, and reading anything.

Charges, refunds and caps#

1. Charge. When a job that makes something starts, its price is taken from the balance. Without enough credits the request fails with 402 insufficient_credits and nothing is created. A batch of motions checks the total for every prompt before starting any of them. The error's details say where to get more: buy_credits_url on paid plans, upgrade_url on Free.
2. Refund. If the job fails or is canceled, the credits are returned automatically. A succeeded job keeps the charge.
3. A job finishes. A job you started isn't stopped halfway. Occasionally a job uses more credits than its listed price; the difference is charged after it delivers, as far as your balance goes, and shows as extra_credits. Our own retries are never charged. On the Free plan, a job may use up the free credits you have left, and stops only once those are spent. Pass max_credits to set the most a job may charge: a job that would need more is stopped and refunded.

{ "prompt": "a cheerful lighthouse keeper", "max_credits": 40 }

Every job reports what it costs you in credits (its price, less any refund, plus any extra_credits charged after it), and GET /usage totals the credits used by job type.

Checking your balance#

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

{
  "object": "credits",
  "billing": true,
  "plan": { "id": "free", "label": "Free", "price_usd": 0, "monthly_credits": 0 },
  "start_credits": 100,
  "withheld": null,
  "balance": 0,
  "plan_balance": 0,
  "pack_balance": 0,
  "packs": [{"id":"pack_500","credits":500,"price_usd":7}],
  "can_buy_packs": true,
  "prices": {"generate":100,"picture":10,"rig_picture":90,"generate_detailed":250,"reconstruct":150,"edit":40,"variant":60,"animate":20,"scene":50,"suggest":5,"analyze":5,"clip":60,"clip_pose":70,"art_edit":10,"logo":60,"tagline":10,"cinematic":60,"download":50},
  "free": ["presets", "recolor", "canvases", "previews", "embeds"]
}

balance is what you can spend: plan_balance (this month's plan credits) plus pack_balance (bought, never expire).

Limits#

Requests outside these bounds fail with 400 invalid_request.

• ErrorsWhat a 402 or a stopped job looks like.
• PricingPlans side by side.