Skip to content

Your keys

echo-words reads its keys from one file, .deploy/.env in your checkout, wherever its server runs. Create it from the template:

mkdir -p .deploy
cp .deploy.example/.env .deploy/.env

On Oracle Cloud every deploy copies it to the VM; on your computer the app reads it where it is.

Gemini: the one key you need

GEMINI_API_KEY=...

Create it free at Google AI Studio. Gemini is the main model of the free pool and does most of the work: in measured runs with every key filled, it wrote about four answers in five. With this key alone the app works.

More free keys: optional failover

GROQ_API_KEY=...
OPENROUTER_API_KEY=...
ZAI_API_KEY=...

Each is free: Groq, OpenRouter, Z.AI. Every key you add puts more models into the pool. They race Gemini for each answer and take over when Gemini is slow, out of its free quota or down.

OpenAI: optional, paid

OPENAI_API_KEY=...

Create it at OpenAI. It pays for three things: the deeper article you ask for with one tap, a card the free pool failed to answer, and the lookup of a word you typed in your own language when Gemini did not answer it. Without it, the deeper article says it is unavailable, a card the pool failed shows the failure, and a lookup keeps the answer of whichever free model gave one.

It costs little. A deeper article costs about $0.036, so a dollar buys about 28 of them, and a paid card or lookup costs a fraction of a cent. A card goes to the paid model only when the free pool fails to answer it, or when you ask for the paid model on a failed card. A word or sentence typed in your own language — after !, or in letters the language you are learning does not use — goes to it when the free pool fails to answer, and also when one of the pool's other models answered in Gemini's place: they pick the wrong word far more often than Gemini does, and on the author's server they write about one answer in seven. On the author's own use over the 30 days to 2 October 2026, 14 deeper articles and 12 paid cards came to about $0.53 in all. The app also stops after 100 paid calls a day, which ECHOWORDS_API_DAILY_CAP changes. ECHOWORDS_API_MODEL= switches paid calls off entirely, even with the key set.

AnkiWeb login

ECHOWORDS_ANKIWEB_USER=...
ECHOWORDS_ANKIWEB_PASSWORD=...

The server needs your AnkiWeb login so that cards reach your decks; see Configuration. uv run inv dev on your computer does not sync with AnkiWeb, so it does not use the login.

Checking them

The app's Status screen lists the keys it is missing. The free pool's key list belongs to llmbroker, the library that runs the pool, and this command prints it for the installed release, with the same signup links:

uv run python -m llmbroker env freetier