Chapter 5

Create your first API key with OpenRouter

Pi Agent is installed and you have toured the interface. Now it needs an AI provider. This chapter uses OpenRouter for the first English-language setup: one account and one API key can access models from several providers, so you can get started without opening a separate account with each model vendor.

Why you need to create an API key

As explained in Chapter 1, Pi Agent uses BYOK (Bring Your Own Key). The add-on does not choose or pay for an AI service on your behalf. You create a key with a provider, then add that key to Pi Agent.

Think of Pi Agent as a stereo system: the speakers and amplifier are ready, but you still need to connect a source. This chapter helps you create that source; the next chapter shows you how to connect it.

Why start with OpenRouter? Three practical reasons:

  • One key, many model families — OpenRouter provides an OpenAI-compatible gateway to models from multiple vendors. You can change models later without repeating the account setup for every vendor.
  • Email-friendly signup — you can create an account with an email address or a supported sign-in provider. Availability and any verification step depend on OpenRouter’s current sign-in page.
  • A useful first setup for an international audience — the dashboard and documentation are in English, and the service is designed for API access from many regions. Model and payment availability can still vary by country.
Tip: If you prefer a direct relationship with a model vendor, see Appendix B for the other supported providers. The Models workflow is almost the same.

What exactly is an API key?

A restaurant may identify your table with an order card and charge everything recorded on that card to your bill. An API key plays a similar role: the provider uses it to associate requests and usage with your account.

An OpenRouter key is a secret string that normally begins with sk-or-v1-example-redacted. Pi Agent sends it with each request to OpenRouter, which authenticates the request and routes it to the model you selected.

Warning: If a key leaks, someone else can consume your credit or quota. Automated scanners search public repositories for exposed keys. Store it only in Pi Agent’s Models panel and in your password manager.Never post it to GitHub, chat groups, support forums, or screenshots.

Since Pi Agent v0.13.0, provider keys are stored locally in /data/pi-agent/models.json on your HA host. They are included when that data is captured by an HA backup. WoowTech does not receive the key. See Chapter 1 for the security boundary.

What OpenRouter is, and how it differs from a direct provider

OpenRouter is an API gateway rather than a model developer. It exposes models from companies such as OpenAI, Anthropic, Google, Meta, and others through a largely OpenAI-compatible API. The available catalog changes over time; use the current model catalog in the OpenRouter dashboard. For comparison, Zhipu AI's direct-provider documentation shows how one provider documents its own models and features.

This comparison helps you choose between an aggregator and a direct account:

Comparison Direct model provider OpenRouter
Who operates the API The company that develops or hosts the model A gateway that routes requests to listed model providers
Account setup A separate account and key for each provider One OpenRouter account and key for its catalog
Model choice Only that provider’s catalog Models from multiple providers, subject to current availability
API compatibility Provider-specific Primarily OpenAI-compatible; some provider-specific features may differ
Pricing The provider’s published API rates Model-specific OpenRouter rates shown in its catalog
Data handling Governed by that provider’s terms and settings Governed by OpenRouter plus the selected model provider and your privacy settings
Free access Depends on the provider Some models may have a free variant; availability and limits can change
Best fit You need direct billing or every provider-specific feature You want one setup for comparing several model families
Concept:No provider is best at every task. Many users keep two or three options and choose based on cost, latency, privacy, and output quality. Chapter 10 explains that strategy; for now, you only need one working key.

Create an OpenRouter API key in eight steps

You can complete these steps on a phone or computer. Labels can change as the dashboard evolves, so follow the current wording on the site when it differs slightly.

  1. Open the official OpenRouter site

    In your browser, open https://openrouter.ai/settings/keys. Confirm that the address uses openrouter.ai, not a look-alike such as openrouter.example. If you are signed out, the official page will ask you to sign in.

  2. Sign in or create an account

    Use one of the sign-in methods OpenRouter currently offers, such as email or a supported identity provider. Complete any verification shown on the official page, and do not reuse your Home Assistant password.

  3. Review the account and privacy settings

    Before adding credit or sending private content, review the privacy and data-policy settings shown in your account. Requests may be handled by the selected model provider, so choose settings and models that meet your requirements.

  4. Open the API Keys page

    From the dashboard, open API Keys in Settings. If the navigation labels have changed, return to the official settings page and follow the current dashboard link.

  5. Choose Create Key

    Select Create Key. OpenRouter may offer an optional credit limit for the key. Set only a limit suitable for your own budget; this guide does not invent or prescribe a business value.

  6. Give the key a recognizable name

    Choose a name that identifies this Pi Agent installation. Use a descriptive label, for example pi-agent-home, pi-agent-office, or test-2026-08. Separate keys make rotation and usage review easier.

  7. Create and copy the key

    Confirm the form, then copy the new key. OpenRouter keys normally begin with sk-or-v1- (for example, sk-or-v1-example-redacted). Use the Copy button so you do not omit any characters. Treat the full value as visible only during creation. If you lose it, create a replacement rather than trying to recover it from a masked preview such as sk-or-v1-….

  8. Store it in a password manager

    Save the key in a password manager such as 1Password, Bitwarden, Apple Passwords, or KeePass. Keep a local temporary note only long enough to complete Chapter 6, then delete it.

Warning: Do not continue until the complete key is stored safely. If the page no longer reveals it, revoke or delete that key and create another one.

How usage and credit work

OpenRouter measures model usage in tokens. Token counts vary by language and model, so do not estimate a bill from word count alone. Pi Agent sends both your prompt and relevant conversation context, and the model’s response also consumes tokens.

Rates and model availability change. Check the OpenRouter catalog and your account dashboard before choosing a model or adding credit. Use OpenRouter’s displayed rate for the selected route. For a direct-provider comparison, consult Zhipu AI's current pricing page.

Item What to check Notes
Input tokens The selected model’s current input rate Conversation history may be sent again as context
Output tokens The selected model’s current output rate Long answers generally consume more output tokens
Free model variants Whether a model ID currently has a free variant Availability and limits can change; do not assume production capacity
Account credit Your current balance and payment options Use only values shown in your own account

Instead of a made-up monthly estimate, monitor actual usage in the dashboard:

Usage pattern What affects it Recommended control
Occasional questions Prompt and response length Review usage after the first sessions
Daily conversations Context length and model choice Select an appropriate model and monitor the balance
Long research or coding sessions Large context and long output Use a key limit if the dashboard offers one
Video workflow (Chapter 17) The chosen model and number of generation steps Review each workflow’s usage rather than assuming a fixed cost
Tip:A free model can be useful for a first connectivity test, but free availability and rate limits are not guarantees. For regular use, choose a model based on its current price, privacy policy, and quality.

Does OpenRouter require identity verification?

OpenRouter’s sign-in and payment requirements can vary by method, country, and risk checks. Complete only the verification shown in your own account. This guide does not claim that every region or payment method is supported.

You do not need a mainland-China identity document for this OpenRouter walkthrough. You may still need to verify an email address or satisfy a payment provider’s requirements if you purchase credit.Do not submit identity documents to anyone claiming to “help” outside the official site. If the offered account or payment flow is unavailable in your country, choose a supported direct provider instead:

Your situation Recommended action
You only want to test the connection Check the current catalog for an available free model variant, then monitor its limits.
You need paid, predictable usage Review the payment methods, fees, and account terms displayed by OpenRouter before purchasing credit.
OpenRouter is not suitable for your policy or region See Appendix B and create a key directly with another supported provider.
Concept:Account eligibility and model availability are provider decisions. Do not bypass regional, identity, or payment controls; choose a provider you can use legitimately.

Where to store the key—and where not to store it

Treat an API key like a payment credential.

Safe storage:

  • Pi Agent’s Models panel — the next chapter shows how to add it. Pi Agent stores it in /data/pi-agent/models.json on your HA host. Anyone with root access to the host can still read that file.
  • Your password manager — use a reputable manager with a strong master password and multi-factor authentication where available.
  • An encrypted offline backup — keep access controlled and test that you can restore it.

Never store it here:

  • A public GitHub repository — scanners can find secrets quickly. Removing the latest commit is not enough if the value remains in Git history.
  • Chat or community groups — messages and screenshots may be retained by other participants or the service.
  • Shared documents — link-sharing settings are easy to misconfigure and can change later.
  • A public support post — replace the real value with a clearly fake example.Redact the entire secret; use something like sk-or-v1-REDACTED.
  • Email — do not send an API key as ordinary email.
  • Screenshots or screen recordings — OCR can recover text that looks small on screen.
Danger: If a key may have leaked, act immediately: open OpenRouter’s API Keys page, delete or revoke the key, and create a replacement. Then review usage and account activity. Rotation stops future use of the old key; it does not undo earlier requests.

Do I have to use OpenRouter?

No. This chapter uses OpenRouter because it provides a practical international first setup and access to several model families. A direct provider can be a better choice when you need direct billing, a particular regional agreement, or provider-specific features.

Your priority Suggested first provider What to verify Where to continue
Compare several model families with one API OpenRouter Current model availability and account eligibility This chapter
Direct access to Claude models Anthropic Regional availability, billing, and API terms Appendix B
Direct access to OpenAI models OpenAI Regional availability, billing, and API terms Appendix B
Direct access to GLM models Zhipu AI / GLM Regional availability and current verification requirements Appendix B
Direct access to DeepSeek models DeepSeek Regional availability, billing, and API terms Appendix B
Tip:You can add another provider later. Chapter 10 explains when multiple providers are useful; the first goal is simply a secure, working configuration.

Common setup problems

  1. The sign-in email does not arrive

    Check spam and filtered folders, confirm that the address is correct, and wait before requesting another message. If the offered sign-in method remains unavailable, use another supported method shown by OpenRouter. Use only the official OpenRouter sign-in page.Do not follow links sent by strangers or enter the key on a third-party “verification” page.

  2. The copied key is rejected

    OpenRouter keys normally begin with sk-or-v1-REDACTED and must be copied in full. Use the Copy button rather than selecting part of the text manually. Remove accidental leading or trailing spaces and do not add quotation marks. Chapter 6’s Test action will confirm whether the complete credential was entered.

  3. I closed the page before saving the key

    Return to the API Keys page, revoke or delete the lost key, and create another one. A masked entry is not enough to recover the full secret.

  4. I cannot use a model that appears in the catalog

    Availability can depend on account settings, provider routing, region, credit, and the model’s current status. Read the model page and the exact error before changing settings. Refreshing the page with F5 may update the dashboard but will not fix an account or provider restriction.

  5. The account or payment method is not supported

    Do not invent account details or bypass provider controls. Choose a payment method offered to your account or use another supported provider from Appendix B.

  6. I opened a look-alike site

    Do not sign in or paste a key. Return to the official openrouter.ai domain, rotate any key you exposed, and change reused credentials.

FAQ

Can I use a provider other than OpenRouter?
Yes. Pi Agent supports multiple providers; see Appendix B. OpenRouter is the first English walkthrough, not a requirement. If you already have a supported direct-provider key, Chapter 6 uses the same overall Models workflow.
What if someone obtains my key?
Take two actions: revoke it immediately in OpenRouter’s API Keys page and create a replacement; then review usage for requests you do not recognize. If paid credit or account information may be affected, follow the support path shown in your account.
Do I need a new key after moving HA to another host?
No. The key belongs to your OpenRouter account, not to one HA host. Add the same key on the replacement host, or restore the HA backup that contains /data/pi-agent/models.json. See Chapter 20 for the backup procedure.
Can one key be used by more than one Pi Agent?
It may work, but separate keys are easier to rotate and audit. Shared limits and usage are also harder to attribute.Create a separately named key for each installation, such as pi-agent-home and pi-agent-office. Do not assume there is no account limit; follow the current API Keys page.
Does Pi Agent upload my key to WoowTech?
No. Pi Agent is an MIT-licensed open-source project; its source is on GitHub . The key is stored locally in /data/pi-agent/models.json, and requests go to the configured provider—for this walkthrough, OpenRouter. Chapter 1 describes the security boundary. Anyone administering the HA host can still access local data.
What should I do next?
Continue to Chapter 6: Paste the key into the Models panel. Enter the OpenRouter-compatible settings, run Test, and only then start a conversation in Chapter 7.