Models, keys and limits

Choosing a model

Every bubble has its own model. It starts on the default model you set on the Models page, and you can change it in the bubble’s inspector: provider, model, key and reply format. Favourite models and per-role defaults for a project live on the Models page too.

OpenRouter and NVIDIA accept any model name you type, so a model that is not in the list yet can still be used.

For adding keys and where they are stored, see Add a provider key.

Pools

A pool is an ordered list of up to eight models (and up to eight keys) that a bubble uses as one. When the model in use is rate-limited, down, or keeps sending answers it cannot read, the pool moves on to the next entry.

• Batch (the default), cycle and proportional decide how entries are picked.
• A failed entry rests for ten minutes before it is tried again.
• A pass waits at most eight minutes in total for a free entry, and tells you when it has been waiting.

On free provider tiers, pools help most. Put two or three free models in one pool, and a bubble keeps working when one of them is out of requests. Start free makes one for you: see First run on free models.

Rate limits

Perfica tracks requests per minute and per day for each model and key, and spaces calls so a bubble does not trip the provider’s limit.

It works out each limit in this order:

1. what you typed on the Limits page,
2. what the provider’s rate-limit refusals have taught it,
3. the published limits it ships with (for example, OpenRouter’s free models at 20 a minute and 50 a day, and Google’s free tier).

Local models (Ollama, LM Studio) have no limit.

When a limit is reached

• A pool skips an entry whose allowance is spent and moves to the next one.
• When nothing is left to ask, the loop pauses on the same bubble, with a notice saying when it will try again, and then resumes on its own: at the time the provider or the day’s reset gives, or otherwise after 5, 10, 20 and 40 minutes and then every hour, for as long as the board is left alone. Pause, Stop or Play ends the waiting; the notice also offers Add a paid key.
• None of this spends the loop’s error caps, unless the loop has Continue on error on, and a retry that was refused before any model answered does not count as one of the loop’s passes.

When a provider is down

Dropped connections and server errors are asked again three times, over about seven seconds. If the provider is still down, the loop stops on the same bubble with a notice, the model provider stopped answering, and waits for Play. No error is counted.

Cost

The Usage tab shows this board’s tokens and cost over time, By model and By role, from the provider’s own token counts. A model the price table does not cover shows n/a, never $0, and totals are marked +. Local Ollama models count as free.

Images

A bubble can be shown images: pasted into a Manager message or a task card, or read from the project. If its model cannot see, the board’s vision model describes the image instead. Set it on the Models page under Helper models. Without one, a blind model stops with a notice rather than guessing what the picture shows.