# KeepRouter API key setup: from the free model to a controlled paid request

> Use the published free model to check authentication and a basic chat request. Moving to a paid model requires its exact catalog ID, a key that allows it and sufficient prepaid credit. Verify one request before increasing the workload.

_Published 2026-09-23 · Updated 2026-09-29 · [KeepRouter Editorial](https://keeprouter.com/editorial-policy#editorial-team) · 6 minute read_

![Layered responsibility map between an application, AI gateway, and model providers](https://keeprouter.com/editorial/blog/ai-gateway-guide.png)

_Authentication, model scope, account credit and useful output are separate checks._

A first KeepRouter request should answer a small question: can this application authenticate and receive a response from the intended endpoint? Start with the published [free model](/models/free) and a key scoped to that model. Once the basic path works, evaluate a paid model separately with its own scope and a measured request.

KeepRouter uses prepaid USD credit for paid usage. The free model is a specific catalog entry; its existence does not make every catalog model free. Likewise, a successful free text request does not demonstrate a paid model's tool support, image handling, context behavior or quality. The [quickstart](/docs/quickstart) and current catalog are the operational references for this walkthrough.

## Create a key with a purpose

Open the account console from the site's sign-in action and create a key for the test application. Use a descriptive name so you can identify its traffic later. Restrict the model allowlist to `free` for the initial request. Where appropriate, set the key's expiry and spend controls using the options shown in the console.

Keep the revealed credential in your runtime's secret storage or a local environment variable. Do not put it in a browser bundle, a public repository or a support screenshot. A key identifies the application to the service; the model allowlist defines which catalog models it may request. Account credit and key permission are separate conditions.

| Control | What it answers | What it does not establish |
|---|---|---|
| Credential | Is this caller recognized? | Whether every model is allowed |
| Model allowlist | Is this model in scope? | Whether the account has paid credit |
| Spend control | Is this key within its configured budget? | Whether a requested endpoint is compatible |
| Account credit | Can paid usage be funded? | Whether the output meets the application need |

Avoid using a broadly scoped production key to debug a new client. A distinct test key makes the resulting request records easier to interpret and can be revoked when the experiment is complete.

## Run a minimal free-model request

After setting `KEEPROUTER_KEY` in the current process environment, this Python example sends one basic chat request. It reads the key value rather than treating its variable name as a literal string. The example is provided for you to run; it does not imply that an account or request was created for this article.

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://keeprouter.com/v1",
    api_key=os.environ["KEEPROUTER_KEY"],
    timeout=30.0,
    max_retries=0,
)
reply = client.chat.completions.create(
    model="free",
    messages=[{"role": "user", "content": "Reply with a short greeting."}],
    max_tokens=64,
)
print(reply.id, reply.model)
print(reply.choices[0].message.content)
print(reply.usage.model_dump() if reply.usage else "usage missing")
```

Use a current OpenAI Python SDK version recorded in the project lockfile. If your application runs in a container or deployment platform, setting a variable in an unrelated terminal does not configure that process. Confirm the runtime has the variable without printing it.

The SDK base is `https://keeprouter.com/v1`; the SDK appends the chat operation. Supplying the full `/chat/completions` path as the base can construct the wrong URL. Anthropic clients use a different request shape; use the [Anthropic-compatible API guide](/features/anthropic-compatible-api) when that is the interface your application needs.

## Diagnose the first error by its layer

| Symptom | First checks |
|---|---|
| 401 | Key is present in this process, copied correctly and not revoked |
| Model denied | Exact requested ID is included in the key's allowlist |
| Model not found | ID exists in the current catalog; no foreign namespace was copied |
| 404 | Host and base path are correct for the client family |
| Insufficient credit or budget | Account balance and this key's remaining limit |
| Unsupported operation | Selected model publishes the endpoint being called |

Keep the request identifier and status for diagnosis. An authentication error is not a reason to top up, and a funded account does not repair an invalid base URL. Use the [error reference](/docs/errors) before changing several settings at once. If you ask support for help, send the safe request metadata and a redacted payload rather than the API key.

## Prepare a paid request deliberately

Choose one candidate from the [model catalog](/models) and inspect its price unit and endpoint. A chat model such as [Claude Sonnet 4.6](/models/claude-sonnet-4-6) is a separate choice from an image, speech or video route. Use the [API cost calculator](/tools/api-cost-calculator) with the token or other unit assumptions relevant to that exact operation.

Create a new paid-test key with an allowlist containing the exact model you selected. Keep the original free-only key unchanged so each test has a clear scope. Add prepaid credit through the console's available payment flow and confirm the credited balance there. Review the displayed checkout total, fees and taxes where applicable; the model's token rate is not the same thing as the payment checkout total. A completed browser redirect alone is not evidence that credit has reached the account.

Replace `KEEPROUTER_KEY` in the application runtime with the newly created paid-test key, then restart the process or recreate the SDK client so it reads the new value. A client created with the free-only key keeps that credential; topping up or changing the model ID does not replace it.

Keep the test small, choose an output limit supported by the selected route, and send a synthetic task with a clear expected result. Reuse the earlier script only for a compatible chat model, replacing `free` with the verified ID and adapting any route-specific fields. A non-chat model needs its own operation and payload.

## Match the response to the usage record

After the paid call, compare the requested model, time, status, input, output, cache information and recorded charge in the console. Retain the request identifier on the application side. If the client timed out, investigate the record before repeating the operation; a timeout does not prove that upstream work never happened.

Distinguish four milestones: the account exists, the key authenticates, the request completes, and its result is useful. A product can reach the first three and still need a better prompt or model evaluation. Track the first useful paid task rather than treating key creation as successful adoption.

## Know what the free call did and did not prove

A successful free-model call confirms the basic client path for that key and model. It does not prove that a paid model is funded, allowed by the key or compatible with every field. Before the first paid request, open the intended model page, check the unit price and output limit, then inspect one usage record. The [KeepRouter quickstart](https://keeprouter.com/docs/quickstart) is the setup reference. Keep the first paid task small enough that a mistake is easy to understand and correct.

## Move the verified setup into the application

Save the base URL and exact model ID as configuration, inject the secret at runtime, and keep a separate key for each application environment where practical. Test deployment using a harmless bounded request and verify its usage record. Retire the disposable test key after the application key has been checked.

Keep the [SDK configuration guide](/use-cases/openai-sdk) with the application runbook. Revisit the model's endpoint and customer rate before major workload changes. Increasing concurrency, adding tools or sending images each creates a new test case; none is proven by the original free greeting.

## Frequently asked questions

### Can I test before adding paid credit?

Use the published free model with a key scoped to free, subject to its current availability and limits.

### Why does a paid request fail after the free request worked?

Check the exact paid model ID, key allowlist, credit, key limits and endpoint independently.

### Is key creation the same as successful activation?

No. Verify a completed request and then a useful application result; paid adoption also needs an understood charge.

### What should I share when troubleshooting?

Share request time, identifier, model, status and redacted payload details. Never share the API key.

## Sources reviewed

_Article last reviewed 2026-09-29_

1. [KeepRouter quickstart](https://keeprouter.com/docs/quickstart)
2. [KeepRouter free model](https://keeprouter.com/models/free)
3. [KeepRouter error reference](https://keeprouter.com/docs/errors)
4. [OpenAI Python SDK](https://github.com/openai/openai-python)

## Related guides

- [free](https://keeprouter.com/models/free.md)
- [quickstart](https://keeprouter.com/docs/quickstart.md)
- [errors](https://keeprouter.com/docs/errors.md)
- [api cost calculator](https://keeprouter.com/tools/api-cost-calculator)
- [DeepSeek API pricing: estimate cache hits without counting input twice](https://keeprouter.com/blog/deepseek-api-pricing-cache-estimation.md)
- [OpenRouter to KeepRouter migration: map URLs, model IDs and routing fields](https://keeprouter.com/blog/openrouter-to-keeprouter-migration.md)

## Try the setup with one small request

Follow the configuration steps, keep the key on your server, and check the returned answer and usage.

[Open the setup guide](https://keeprouter.com/docs/quickstart)

[Create a key to test the free model](https://keeprouter.com/login?returnTo=%2Fconsole%2Fkeys%3Fmodel%3Dfree)

The free test uses the free model. Other paid models require sufficient prepaid credit.

[All posts](https://keeprouter.com/blog.md) · [Models & pricing](https://keeprouter.com/models.md)