Paying for the model

Paying for the model

Every answer costs a little: providers charge for the AI model by the word. Your server pays one of three ways. provider.mode in config.yml picks between the first two.

Your own key (byok)

Bring a key from OpenRouter or any other OpenAI-compatible API, and you pay the provider directly.

1. Fill in provider in plugins/Allay/config.yml:

   provider:
     mode: byok
     byok:
       base_url: "https://openrouter.ai/api/v1"   # any OpenAI-compatible API
       api_key: "sk-or-v1-…"
       model: ""             # empty: the backend's default; it must be able to call tools
       search_model: ""      # empty: no web search; on OpenRouter, say, "perplexity/sonar"

2. Run /allay reload.
3. Run /allay status. It shows the API, the models, and the key with all but its ends hidden.

Allay looks into the game through tools, so a model that can't call them won't work. When a question fails, the note under it tells an operator what to change.

On allay.chat your own key costs nothing extra, up to 20 questions a minute and 2000 a day per server. Since 6.0 allay.chat still wants to know which server asks: on the first question Allay gets a free license as the server's identity and keeps it in license.key. It pays for nothing, and /allay status shows it. A key from before 5.0 in http.custom_headers (X-OpenRouter-Token) keeps working as your own OpenRouter key.

A subscription (hosted, the default)

The backend answers on its own key and models, and you pay in Telegram Stars.

1. Run /allay link. The plugin gets a license, saves it in plugins/Allay/license.key, and shows a [Pay in Telegram] button; the console gets the plain link. The link works once and for 24 hours.

2. Pick a plan in the bot and pay with Stars:

   Plan	Stars	Period
   Week	150 ⭐	7 days
   Month	500 ⭐	30 days, renews by itself
   Year	10 000 ⭐	365 days, the limit refills every 30 days

3. Run /allay status. It shows the plan, the date it's paid until, and a bar of how much of this period's limit is used.

Each plan has a usage limit per period. Allay checks the subscription every 5 minutes and tells operators online:

• when a payment comes in;
• when the limit passes 80% and 100%;
• three days before a subscription that doesn't renew runs out, with a [Renew] button.

When the subscription lapses, players get a short, friendly note instead of an answer, and operators also get a link to pay. To pay again, run /allay link: it keeps the same license.

⚠️ Keep license.key to yourself. Whoever has it uses your subscription. Back it up with the server, but don't share it or commit it to a public repository. It never goes into the log, and config.yml doesn't hold it, so you can share your config when asking for help.

Solo, for your own world

With the Fabric or NeoForge mod in your own game, a singleplayer world or a LAN world you host, /allay link works without cheats and makes a Solo license. It answers you alone, with a smaller limit for a smaller price:

Plan	Stars	Period	Limit
Solo week	50 ⭐	7 days	$0.25
Solo month	150 ⭐	30 days, renews by itself	$1
Solo year	3000 ⭐	365 days	$2 every 30 days

The license lives in config/allay/license.key of your game, so every world uses it. Whoever pays can hand it to another player in the bot's /status once every 30 days. Another player in your LAN world gets a note that the license is taken.

Your own backend

An Allay Server started with SELFHOSTED=1 has no billing: it answers every plugin that sends its PLUGIN_TOKEN on its own key. Point server.url at it and put the token in server.token, as Installation shows, and there's nothing to pay or link. /allay status says so.

Limits per player

Whoever pays, you can cap what Allay spends.

1. Turn the quota on and set a monthly budget:

   quota:
     enabled: true
     monthly_usd: 20.0
     daily: true          # the budget opens day by day: by the 10th, a third of it
     tiers:
       default: 1          # everyone
       vip: 3              # players with allay.quota.vip weigh three times as much

2. Give tiers with your permission plugin: allay.quota.<tier>, with any tier names you like.
3. Optionally give a tier its own model:

   models:
     vip: "anthropic/claude-sonnet-5.5"   # players with allay.model.vip get this model

4. Run /allay reload.

How the split works

Nobody books money they don't use. A player's limit is what's open of the budget so far, times their weight, over the weights of everyone who asked this month:

• a VIP alone may use all of it;
• with one regular player around, it's 75% and 25%;
• a third player makes it 60%, 20%, and 20%.

There's no guarantee, only a fair split. A player with several tiers gets the biggest weight, and operators get the biggest there is. Whoever reaches their limit hears when more comes: tomorrow with daily, else next month. Spending lives in plugins/Allay/quota.json.

A weight that isn't a number above 0 makes the config wrong. Allay then answers nobody, tells admins what's wrong when they join, and asks players to talk to an admin.

A model by tier replaces provider.byok.model. A self-hosted backend honors it too, on its own key. With several model tiers, the first one in the list that the player has wins.

Next: First steps