How credits work
A credit is the unit a person spends on one AI call. You define the operation once as a named tool and give it a price. Every call to that tool then spends that many credits, recorded on the person's ledger. You write no metering code, and the browser cannot change the price.
Define the tool
A tool is a file in your project. The file sets how the tool runs: provider, model, instructions, template and inputs. You set its price and required access in the dashboard. Credits run from 1 to 10,000 per tool, or 0 for a tool included with access. A 0-credit tool must set requiresAny, and its calls are still metered.
{
"label": "Deep Research",
"provider": "openai",
"model": "gpt-4o",
"credits": 20,
"requires": "access:pro-max",
"instructions": "You are a careful research assistant. Answer with sources.",
"promptTemplate": "Research this question for a {{audience}} reader:\n\n{{question}}",
"inputs": [
{ "name": "question", "type": "text", "required": true, "maxLength": 2000 },
{ "name": "audience", "type": "text" }
],
"bounds": { "maxOutputTokens": 4000 }
}Upload it with npx gemmein sync. To sync to Live, add --live; you approve that push in your browser with the code Gemmein emails, item by item. Once the tool exists, the dashboard controls label, credits, unit and per, required access (requires / requiresAny), whether the tool is enabled, whether calls are recorded, and, on a transcribe tool, whether the upload is deleted after the run. The file's values for these apply once, when the tool is created.
Per-call and per-token pricing
Your app calls the tool by name, and Gemmein runs it on your provider key with the pinned model. The deep-research tool above is priced per call, so its 20 credits are spent before the call. A tool with "unit": "tokens" reserves a credit ceiling instead and settles when the answer ends.
// A name and inputs. The server composes the rest.
const answer = await g.ai.runText("deep-research", {
question: "How can I improve client onboarding?",
audience: "beginner"
});
// The person's own balance, in the browser, when signed in.
const { balance, reserved, expiring } = await g.credits.balance();Priced per call
The price is spent before the call and refunded in full if the provider fails before it answers. A call that dies mid-stream, or one the person abandons after the first byte, is not refunded.
Priced per token
A credit ceiling is reserved before the call, covering the request size plus the output cap. The charge settles at the provider's reported usage, up to that ceiling, when the stream ends cleanly. A stream that does not end cleanly, or a call abandoned mid-answer, costs the ceiling.
Top-ups
People buy more credits with a pack. AI-written checkout code often grants credits on the success redirect, which anyone who knows the URL can fake. Gemmein grants credits only when the signed payment webhook arrives. It verifies the event Stripe signs, writes it to the person's record, and grants the credits from it. You write no code for this.
Prompt for your coding agent
Paste this into Cursor, Claude, Bolt or Lovable so your agent builds from the documented API.
Read https://docs.gemmein.com/llms.txt and https://docs.gemmein.com/ai. I want to charge credits for an AI feature. Show me how to define a priced AI tool on the server (a tool file with provider, model, instructions and inputs), set its credit price and required access, and call it by name from my app. Explain how a per-call price is spent and a per-token price is reserved and settled, and how a person buys more credits, with the grant made on the signed payment webhook and never on the checkout redirect.
npx gemmein devRead the getting-started guideFrequently asked questions
Do the credits expire?
Credits sit on a grant, such as a credit pack. Credit packs never expire.
Can the browser set the price or pick the model?
No. The price, the model and the required access live on the server, and the app sends only a tool name and inputs. Raw provider calls from the browser are off by default.
Can I meter something that is not an AI call?
Yes. Spend credits from your own server for anything you want to meter that is not an AI tool call.