KeyCall

One consistent interface for validating AI-provider API keys, listing and filtering the models available to them, and making normalized calls, so every product stops rebuilding the same model-picker filters and provider wrappers.

Status: early release (0.2.0). Key validation, model listing and filtering, text generation, and native web search with normalized citations all work and are live-verified against every supported provider. Streaming, structured output, general tool calling, and non-text modalities are not implemented yet. The API is settled but may still shift before 1.0.

Docs: USAGE.md for the full API and CLI reference · CHANGELOG.md for version history.

Quick start

from keycall import KeyCall, Message, ModelCategory, TextInput

with KeyCall(provider="openai", api_key=secret) as client:
    discovery = client.list_models(categories={ModelCategory.TEXT_GENERATION})

    result = client.generate_text(
        model=discovery.models[0].id,
        messages=[Message(role="user", content=[TextInput(text="Hello.")])],
    )

print(result.text)
print(result.usage.total_tokens)
print(result.round_trip_duration_ms)

• Explicit provider, always. KeyCall never guesses which vendor issued a key and never sends a credential to more than the one provider you name.
• No credential storage. Keys live in memory for the client's lifetime, wrapped in a redacting type that keeps them out of reprs, logs, traces, exceptions, and pickles. Your app decides how to store them.
• Model filtering built in. Text-generation models by default; embeddings, image, audio, and other categories on request; unknown models never silently enter the default picker.
• Typed errors. Invalid key, rate limit, provider outage, timeout, and malformed response are distinguishable, never collapsed into "invalid key."
• Web search with citations. web_search=True turns on the provider's native search tool (OpenAI, Anthropic, Gemini; Perplexity always searches) and returns sources normalized to one Citation shape.
• Hardened transport. TLS always verified, redirects refused, response sizes capped, SSRF and DNS-rebinding guards on custom endpoints, and generation is never silently retried.

Provider support

Live-verified 2026-08-05 (one model-list call plus one bounded generation per provider):

Two provider quirks worth knowing, both handled:

Gemini keeps retired models in its list endpoint (gemini-2.5-flash returns "no longer available to new users") with no lifecycle field to pre-filter on, and meters quota per model and tier, so one model's 429 says nothing about the next. Its supportedGenerationMethods is also a transport signal rather than a modality claim: TTS variants advertise generateContent and then refuse a text response, so KeyCall lets a distinctive identifier modality outrank it.

Perplexity's GET /v1/models is scoped to the Agent API and returns vendor-prefixed router models (anthropic/..., perplexity/sonar) that the Sonar route rejects. Sonar's own models are not API-discoverable, so KeyCall maintains them in its catalog and uses the list call purely as a credential check.

Because of quirks like these, keycall verify --generate walks the filtered models in provider order and prints the outcome of every attempt until one succeeds, so drift stays visible rather than being masked by a silent retry.

Local viewer

keycall view --source ./keys.toml

Opens a token-protected local web app over your loaded targets: a dashboard with live key checks, a sortable model browser with category filters, a playground for real generation calls (web search included), and a verify report. Keys never leave the server process and never appear in the browser.

Or double-click / run a launcher from a fresh clone — it creates the venv, installs KeyCall, finds your key file, and starts the viewer: launch.command (macOS), launch.sh (Linux/macOS), launch.bat (Windows).

Verifying keys from the command line

keycall verify --source ./keys.toml

keycall verify --source ./keys.toml --generate

--generate also makes one small bounded call per target. Sources can be TXT, JSON, or TOML, an explicit env:VAR_NAME reference, or an interactive prompt. See keycall-test-keys.example.toml for the format and USAGE.md for the full reference. Keys never appear in output, and KeyCall never writes to or deletes your credential file.

Installation

pip install keycall

Development

pip install -e ".[dev]"
pytest

Author

Built by Mo Shehu.

License

AGPL-3.0-or-later. See LICENSE.