OpenRouter

Overview

Ahena checks your OpenRouter API key, its credit limit, expiry and free-tier status, and that your configured model is in OpenRouter's model list (and not about to be removed). It also generates an adapter behind the common ahena.ai interface, using the official openai SDK pointed at OpenRouter. Your app calls OpenRouter directly. Ahena is never in the inference path, and its checks never send a completion on your account.

Package: @ahena/provider-openrouter · Category: ai · Default model: openai/gpt-5-mini Capabilities: text-generation, model-availability, key-limits

Maturity: verified against a fake of the API; not yet verified against the real service.

Connection

OPENROUTER_API_KEY (secret, sk-or-v1-…). Use a regular API key, not a management key.

OPENROUTER_API_KEY=sk-or-v1-… ahena connect openrouter -e production

Permissions

OpenRouter API keys have no scopes: a valid key can do everything a key can do, so Ahena can only check that the key works (permissionCheck: "authentication-only"). Ahena reads two endpoints: GET /api/v1/key (the key's own limit and usage) and GET /api/v1/models.

OpenRouter also has management keys (formerly "provisioning keys"), which can create, change and delete your other keys and read account credits. Ahena doesn't need one and Doctor warns (openrouter.key_kind) if you connect one. Give the key a credit limit so a leak or a runaway loop can't spend more than you meant, and give your app its own key.

Capabilities

Network: only openrouter.ai (enforced). The model list is read with offset/limit pagination (1000 per page) until links.next is null.

Configure

There's nothing to plan or apply: Ahena changes nothing in your OpenRouter account. You choose the provider and model in ahena.config.ts:

ai: {
  provider: { development: "ollama", production: "openrouter" },
  model: { development: "llama3.2", production: "openai/gpt-5-mini" },
},

Doctor findings that need a change (raise a credit limit, replace a key, buy credits, pick another model) are MANUAL or BILLABLE and carry the steps; Ahena never does them for you.

Generate

ahena generate openrouter writes:

• src/ahena/ai/types.ts: the shared AiAdapter interface.
• src/ahena/ai/providers/openrouter.ts: adapter() creates new OpenAI({ apiKey, baseURL: "https://openrouter.ai/api/v1" }) and calls chat.completions.create (system prompt as a system message, maxTokens as max_tokens). The returned model is the one OpenRouter says served the request. Optional app attribution headers (HTTP-Referer, X-OpenRouter-Title) are noted in a comment.
• .env.example.openrouter: OPENROUTER_API_KEY=.

Limitations

• The common interface covers text generation. Tools, structured outputs, streaming, provider routing preferences and fallbacks use ahena.ai.raw (OpenRouter-specific request fields).
• Account credits (GET /api/v1/credits) need a management key, so Ahena doesn't read them; it reports the connected key's own limit and usage instead.
• Key management (creating, rotating or deleting keys) isn't supported, by design.
• Model ids with routing shortcuts (:nitro, :floor, :exacto, :online) are checked against the base model; other unknown ids are reported as missing.
• ahena drift doesn't track AI providers.

Manual steps

1. Create a key at https://openrouter.ai/settings/keys and give it a credit limit.
2. Buy credits before production traffic (https://openrouter.ai/settings/credits).
3. Set OPENROUTER_API_KEY (and AI_PROVIDER=openrouter if several adapters exist) where your app runs.

Doctor checks

Set up step by step

1. Create the key. Sign in at https://openrouter.ai, open Settings → API Keys (https://openrouter.ai/settings/keys), choose Create API Key, name it (e.g. "Ahena production") and set a credit limit. Copy the sk-or-v1-… value; it's shown once.

2. Minimum permissions. OpenRouter keys have no scopes. Use a regular key, not a management key. A dedicated key for Ahena with a small credit limit is enough: Ahena never spends credits.

3. Connect.

   OPENROUTER_API_KEY=sk-or-v1-… ahena connect openrouter -e production

4. Verify the connection. ahena inspect openrouter -e production shows the key's limit, usage and the models it can see. A wrong key is reported as expired.

5. Run Doctor. ahena doctor -e production checks the key, its limit and expiry, free-tier status and your ai.model.

6. Plan. ahena plan -e production lists no OpenRouter changes: there's nothing to apply.

7. Make a change. The changes you make are in your project: set ai.provider and ai.model in ahena.config.ts, then run ahena generate -e production to write the adapter. Raising a credit limit or buying credits is done in OpenRouter.

8. Verify. Run ahena doctor -e production again: openrouter.model should be PASS for the new model.

9. Troubleshooting.

   Symptom	Cause	What to do
   openrouter.key FAIL, connection expired	Key deleted, disabled, expired or mistyped (HTTP 401)	Create a new key and reconnect.
   openrouter.key_limit FAIL	The key's credit limit is used up	Raise the limit in Settings → API Keys, or wait for it to reset.
   openrouter.model FAIL	Model id isn't in the list (typo, removed, or a provider prefix is missing)	Use an author/model id from https://openrouter.ai/models.
   openrouter.free_tier WARNING	The account has never bought credits	Buy credits before production traffic.
   Requests from your app return 402	The account is out of credits	Add credits in OpenRouter.
   HTTP 429	Rate limited	Ahena retries reads; wait and run Doctor again.

10. Disconnect and revoke. ahena disconnect openrouter -e production removes the stored key. Then delete or disable the key at https://openrouter.ai/settings/keys.

Disconnect behavior

Removes the connection and the key Ahena stored. Delete or disable the key at https://openrouter.ai/settings/keys. Nothing in your OpenRouter account is changed.