Use Your Own AI API Keys Without Losing a Safety Net

Bringing your own provider key can help you use existing credits, company agreements, and provider-side controls. But an expired key, a quota limit, or a temporary provider problem can interrupt an otherwise working application.

NanoGPT's Prefer BYOK for API requests setting tries your saved key first for eligible Chat Completions API requests. If that route cannot safely complete the request, NanoGPT can continue through normal credit-based routing.

That means one missing or temporarily unavailable key does not have to stop your app.

The backup route may use a different provider from the one associated with your saved key. If the exact provider or its data-handling policy is a firm requirement, keep the request fail-fast instead.

What BYOK means here

BYOK stands for “bring your own key.” You save an API key from a supported AI provider in NanoGPT, then use NanoGPT's OpenAI-compatible Chat Completions endpoint as usual.

When a request successfully uses BYOK:

• The AI provider bills the model usage to your provider account.
• NanoGPT charges a 5% BYOK fee based on NanoGPT's normal at-cost API rate for that model.
• NanoGPT still acts as the proxy: it decrypts the saved key on the server and forwards the request to the provider.

Saved keys are encrypted at rest and are not returned after they are stored. BYOK does not bypass NanoGPT and is not end-to-end encryption.

What the automatic preference changes

Without the account preference, BYOK is something you request explicitly for each API call. That is useful when your application must use a particular provider account.

Turn on Prefer BYOK for API requests in BYOK settings, and eligible requests follow this path:

1. NanoGPT checks whether the requested model supports BYOK and matches a saved provider key.
2. If there is a suitable key, NanoGPT tries it first.
3. If no matching key is available, normal NanoGPT routing continues.
4. If the BYOK attempt fails with an error that can safely be retried, NanoGPT tries the request through normal credit-based routing.

This is an account-level API preference, so an existing integration does not need to add BYOK instructions to every request. You can still override it for individual calls.

It currently applies to the OpenAI-compatible /api/v1/chat/completions endpoint. Saved-key mode in the NanoGPT web chat is separate and must be selected in the chat settings.

Fallback is selective, not automatic for every error

Credit fallback is meant to keep a valid request running when the BYOK route has a retryable provider, authentication, quota, rate-limit, or temporary upstream problem.

Fallback does not retry structural problems. If the prompt is too long, the request body is malformed, an option is unsupported, or another request-wide validation fails, NanoGPT returns the error rather than sending the same request again.

NanoGPT also avoids a retry when an add-on could run or be charged twice. Streaming requests can only fall back when the failure is known before output has begun.

What gets billed when fallback happens

The billing path changes with the route that succeeds:

Outcome	Billing
BYOK succeeds	The provider bills model usage; NanoGPT charges the 5% BYOK fee
No matching saved key	NanoGPT uses normal credit-based billing
BYOK fails and credit fallback succeeds	NanoGPT uses normal credit-based billing for the successful retry

Keep enough NanoGPT credit available for the fallback path. The NanoGPT API key making the request must also use a billing mode that permits balance spending; a key set to Subscription only cannot spend credits for the retry.

Your NanoGPT API-key limits still apply. If you use separate keys and spending limits for production, development, and experiments, the fallback stays inside those existing guardrails.

When NanoGPT returns a successful response after using credits as the fallback, the response includes the header:

x-nanogpt-byok-fallback: credits

Log this header to track how often fallback was used. If it appears regularly, check whether your saved key has a low quota, an expired credential, or a model mismatch.

Choose the behavior per request

BYOK first, credits as a safety net

Enable Prefer BYOK for API requests and send ordinary Chat Completions requests. This suits applications that want to use their own provider account when possible without failing whenever that route is temporarily unavailable.

Skip BYOK for one request

Some calls may need normal NanoGPT routing from the start. Leave the account preference on and opt out for only that request with either:

• Header: x-use-byok: false
• Request body: byok.enabled: false

This is useful for a model that does not match your saved keys, a request that needs platform-only behavior, or a one-off comparison of billing routes.

Require fail-fast behavior

For audits, compliance controls, provider-specific testing, or a workload that must never spend NanoGPT credits, disable credit fallback for the request:

• Header: x-byok-fallback-to-credits: false
• Request body: byok.fallbackToCredits: false

The request will then return the BYOK error instead of moving to credit-based routing.

If you explicitly request BYOK with x-use-byok: true or byok.enabled: true, fail-fast is the default. You can opt into the safety net for that explicit request with x-byok-fallback-to-credits: true or byok.fallbackToCredits: true.

When automatic BYOK is a good fit

The preference is particularly useful when:

• You already have provider credits or a company agreement you want to use first.
• Your application needs one OpenAI-compatible endpoint across several supported model routes.
• Occasional provider quotas or outages should not interrupt user-facing work.
• You want a gradual BYOK rollout without rewriting every API request.
• You can monitor fallback usage and maintain a NanoGPT credit balance for continuity.

It is a poor fit when a request must use one exact provider account, when falling back would violate a cost or data-handling policy, or when an unexpected NanoGPT credit charge is less acceptable than a failed request. Use explicit, fail-fast BYOK for those workloads.

A practical setup

1. Add and test your provider keys in BYOK settings.
2. Enable Prefer BYOK for API requests.
3. Confirm that the models your application uses are supported by the saved keys.
4. Keep a small NanoGPT balance available if continuity matters.
5. Set per-key spending limits so fallback cannot create open-ended spend.
6. Log the x-nanogpt-byok-fallback response header.
7. Use fail-fast requests for workloads with strict routing, billing, or data-handling requirements.

Start by adding one saved key, enabling the preference, and watching the fallback header in your normal usage. Manage your saved keys and BYOK preference.