> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenRouter BYOK integration guide
[OpenRouter](https://openrouter.ai/) supports both OpenRouter credits and Bring Your Own Key (BYOK). When using OpenRouter credits, rate limits for SambaNova are managed by OpenRouter. When using your own SambaNova API key, you retain direct control over rate limits and billing through your SambaNova account. All provider keys are securely encrypted and used exclusively for requests routed to SambaNova.
## Prerequisites
Before starting, ensure you have:
* A [SambaCloud](https://cloud.sambanova.ai/?utm_source=openrouter\&utm_medium=external\&utm_campaign=cloud_signup) account and API key. If you do not have your API key, get it from the [SambaCloud portal](https://cloud.sambanova.ai/apis).
* An [OpenRouter](https://openrouter.ai/) account and API key, available from the [OpenRouter keys page](https://openrouter.ai/keys). The Python example reads it from the `OPENROUTER_API_KEY` environment variable.
* Credits on your OpenRouter account. BYOK requests still incur an OpenRouter platform fee that is charged to your OpenRouter credit balance, not to your SambaCloud account. See [Billing](#billing).
* Python 3.10 or higher. The `openrouter` package declares `requires_python >=3.10`, so `pip install` fails on Python 3.9 and earlier.
## Setup
Follow the steps below to connect your SambaNova API key to OpenRouter using the BYOK feature:
Go to your [OpenRouter BYOK settings](https://openrouter.ai/workspaces/default/byok), or open **Settings > BYOK** in the OpenRouter dashboard. BYOK keys are scoped to an OpenRouter workspace, and this link opens your default workspace.
Search for SambaNova in the provider list and select it.
Enter your SambaCloud API key in the **Key** field, leave **Enabled** turned on, and click **Save**.
Click **Test** before you save. OpenRouter calls SambaNova with the key and reports the result, so you find out immediately whether the key is valid instead of debugging it from your application later.
**Always use for this provider** is turned off by default. While it is off, OpenRouter falls back to its own shared SambaNova capacity whenever your key is rate limited or rejected, and bills those requests to your OpenRouter credits instead of your SambaCloud account.
Turn it on if every SambaNova request must go through your own key. You then receive rate limit errors rather than a silent fallback.
## Supported models
OpenRouter addresses models by its own slugs rather than by SambaCloud model IDs. The following SambaNova-hosted models are served by the `sambanova` provider on OpenRouter, which is the provider your BYOK key is registered against:
| SambaCloud model ID | OpenRouter model slug |
| :- | :- |
| `gpt-oss-120b` | `openai/gpt-oss-120b` |
| `MiniMax-M3` | `minimax/minimax-m3` |
| `DeepSeek-V3.2` | `deepseek/deepseek-v3.2` |
| `gemma-4-31B-it` | `google/gemma-4-31b-it` |
For the current list, click **View SambaNova supported models** in the BYOK dialog or open the [SambaNova provider page](https://openrouter.ai/provider/sambanova) on OpenRouter. For context lengths and supported modalities, see [SambaCloud models](/docs/en/models/sambacloud-models).
Not every model that SambaNova serves on OpenRouter uses the `sambanova` provider slug. For example, `meta-llama/llama-3.3-70b-instruct` is served by a separate slug, `sambanova-turbo`. A slug in `provider.only` matches that provider and its `/`-suffixed endpoint variants, so `only: ["sambanova"]` does not select `sambanova-turbo` and the request is left with no eligible SambaNova endpoint. Use one of the slugs in the table above, or check the provider slug on the model's page before you pin it.
## Using the Python SDK
Install the OpenRouter SDK:
```bash theme={}
pip install "openrouter>=1.1,<2"
```
Export your OpenRouter API key so the examples below can read it:
```bash theme={}
export OPENROUTER_API_KEY="your-openrouter-api-key"
```
Your SambaCloud key does not belong in your environment. OpenRouter holds it and attaches it to SambaNova requests on your behalf.
Use the following code to send a request to a SambaNova model via OpenRouter. Setting `provider={"only": ["sambanova"]}` pins routing to SambaNova, and OpenRouter tries your BYOK key before any shared SambaNova capacity.
```python theme={}
import os
from openrouter import OpenRouter
with OpenRouter(api_key=os.getenv("OPENROUTER_API_KEY")) as client:
response = client.chat.send(
model="openai/gpt-oss-120b",
messages=[{"role": "user", "content": "Explain quantum computing"}],
provider={"only": ["sambanova"]},
)
print(response.choices[0].message.content)
```
A successful response is a `ChatResult`, so `response.choices[0].message.content` holds the generated text.
### Confirm the request used your key
A successful response alone does not prove that OpenRouter used your SambaCloud key rather than its own shared capacity. Opt in to router metadata and read `is_byok`:
```python theme={}
import os
from openrouter import OpenRouter
with OpenRouter(api_key=os.getenv("OPENROUTER_API_KEY")) as client:
response = client.chat.send(
model="openai/gpt-oss-120b",
messages=[{"role": "user", "content": "Explain quantum computing"}],
provider={"only": ["sambanova"]},
x_open_router_metadata="enabled",
)
metadata = response.openrouter_metadata
if metadata is None:
print("Router metadata was not returned.")
else:
print(f"Served by your SambaCloud key: {metadata.is_byok}")
print(response.choices[0].message.content)
```
`x_open_router_metadata="enabled"` sends the `X-OpenRouter-Metadata: enabled` header, which adds an `openrouter_metadata` object to the response. `is_byok` is `True` when the request was served with your own provider key and `False` when it was served by OpenRouter's shared capacity.
### Handle errors
Wrap the call so that a rejected key or an exhausted quota surfaces as a readable message instead of a traceback:
```python theme={}
import os
from openrouter import OpenRouter
from openrouter.errors import OpenRouterError
with OpenRouter(api_key=os.getenv("OPENROUTER_API_KEY")) as client:
try:
response = client.chat.send(
model="openai/gpt-oss-120b",
messages=[{"role": "user", "content": "Explain quantum computing"}],
provider={"only": ["sambanova"]},
)
except OpenRouterError as error:
print(f"OpenRouter returned {error.status_code}: {error.message}")
else:
print(response.choices[0].message.content)
```
`OpenRouterError` is the base class for every HTTP error the SDK raises and exposes `status_code`, `message`, and `body`. Catch a subclass such as `UnauthorizedResponseError` (401) or `TooManyRequestsResponseError` (429) when you need to branch on a specific status.
## Billing
When you use BYOK (Bring Your Own Key) on OpenRouter:
* You pay SambaNova directly for inference using your own SambaCloud API key.
* OpenRouter charges a 5% platform fee based on what the same model and provider would cost at OpenRouter's standard pricing.
* The fee is deducted from your OpenRouter credits, not your SambaCloud account.
* Each plan includes a free monthly BYOK allowance, measured by list-price inference cost rather than by request count. Pay-as-you-go includes $25,000 per month and Enterprise includes $200,000. See the [OpenRouter pricing page](https://openrouter.ai/pricing) for details.
## Troubleshooting
Your SambaCloud key is invalid, revoked, or was pasted with surrounding whitespace. Regenerate it in the [SambaCloud portal](https://cloud.sambanova.ai/apis), update it in your [BYOK settings](https://openrouter.ai/workspaces/default/byok), and click **Test** to confirm before retrying.
You reached the rate limit on your SambaCloud account. See [Rate limits](/docs/en/models/rate-limits) for your account's limits, then retry with backoff.
The model you requested has no `sambanova` endpoint, so `provider={"only": ["sambanova"]}` leaves nothing to route to. Use a slug from [Supported models](#supported-models).
The request fell back to OpenRouter's shared SambaNova capacity because your key was disabled, rate limited, or rejected. Fix the key, then turn on **Always use for this provider** to stop the fallback.
The `openrouter` package requires Python 3.10 or higher. Check with `python3 --version` and install into a virtual environment created by a supported interpreter.
To see the upstream status code for every provider OpenRouter attempted, open the [Activity page](https://openrouter.ai/activity), click the generation, choose **View Raw Metadata**, and read the `provider_responses` field.
## Additional resources
* [OpenRouter BYOK documentation](https://openrouter.ai/docs/guides/overview/auth/byok)
* [OpenRouter provider routing](https://openrouter.ai/docs/guides/routing/provider-selection)
* [OpenRouter Python SDK](https://github.com/OpenRouterTeam/python-sdk)
* [SambaCloud models](/docs/en/models/sambacloud-models)
* [SambaCloud API reference](/docs/en/api-reference/overview)