Build with OpenRouter BYOK - SambaNova Integration Guide

OpenRouter 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 account and API key. If you do not have your API key, get it from the SambaCloud portal.
An OpenRouter account and API key, available from the OpenRouter keys page. 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.
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:

Navigate to BYOK settings

Go to your OpenRouter BYOK settings, or open Settings > BYOK in the OpenRouter dashboard. BYOK keys are scoped to an OpenRouter workspace, and this link opens your default workspace.

OpenRouter Settings sidebar with BYOK selected, showing the list of available providers

Select SambaNova as your provider

Search for SambaNova in the provider list and select it.

OpenRouter BYOK provider search with SambaNova selected

Add your SambaCloud API key

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.

Enable SambaNova Key dialog showing the Key field, the Enabled toggle, and the Always use for this provider toggle

Choose whether to allow fallback to OpenRouter capacity

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-M2.7`	`minimax/minimax-m2.7`
`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 on OpenRouter. For context lengths and supported modalities, see 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:

pip install "openrouter>=1.1,<2"

Export your OpenRouter API key so the examples below can read it:

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.

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:

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:

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 for details.

Troubleshooting

401 Unauthorized reported against SambaNova

Your SambaCloud key is invalid, revoked, or was pasted with surrounding whitespace. Regenerate it in the SambaCloud portal, update it in your BYOK settings, and click Test to confirm before retrying.

429 Too Many Requests reported against SambaNova

You reached the rate limit on your SambaCloud account. See Rate limits for your account’s limits, then retry with backoff.

The request fails with no provider available

The model you requested has no sambanova endpoint, so provider={"only": ["sambanova"]} leaves nothing to route to. Use a slug from Supported models.

is_byok is False on a successful response

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.

pip install fails or resolves an unexpected version

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, click the generation, choose View Raw Metadata, and read the provider_responses field.

Overview

Developer tools

Frameworks

Interfaces and low-code

Data and infrastructure

Multimodal

Evaluation and monitoring

OpenRouter BYOK integration guide

Prerequisites

Setup

Supported models

Using the Python SDK

Confirm the request used your key

Handle errors

Billing

Troubleshooting

Additional resources

​Prerequisites

​Setup

​Supported models

​Using the Python SDK

​Confirm the request used your key

​Handle errors

​Billing

​Troubleshooting

​Additional resources

Prerequisites

Setup

Supported models

Using the Python SDK

Confirm the request used your key

Handle errors

Billing

Troubleshooting

Additional resources