> ## 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
[OpenRouter](https://openrouter.ai/) は、OpenRouter クレジットと Bring Your Own Key (BYOK) の両方に対応しています。OpenRouter クレジットを使用する場合、SambaNova のレート制限は OpenRouter によって管理されます。ご自身の SambaNova API キーを使用する場合は、SambaNova アカウントを通じてレート制限と請求を直接管理できます。プロバイダーキーはすべて安全に暗号化され、SambaNova にルーティングされるリクエストにのみ使用されます。
## 前提条件
作業を始める前に、以下の環境を準備してください。
* [SambaCloud](https://cloud.sambanova.ai/?utm_source=openrouter\&utm_medium=external\&utm_campaign=cloud_signup) アカウントと API キー。API キーをお持ちでない場合は、[SambaCloud ポータル](https://cloud.sambanova.ai/apis) から取得してください。
* [OpenRouter](https://openrouter.ai/) アカウントと API キー。API キーは [OpenRouter のキー管理ページ](https://openrouter.ai/keys) で取得できます。Python のサンプルコードは、これを環境変数 `OPENROUTER_API_KEY` から読み取ります。
* OpenRouter アカウントのクレジット。BYOK のリクエストにも OpenRouter のプラットフォーム手数料が発生し、SambaCloud アカウントではなく OpenRouter のクレジット残高に課金されます。詳細は [請求](#請求) をご参照ください。
* Python 3.10 以上。`openrouter` パッケージは `requires_python >=3.10` を宣言しているため、Python 3.9 以前では `pip install` が失敗します。
## セットアップ
BYOK 機能を使用して SambaNova API キーを OpenRouter に接続するには、以下の手順に従ってください。
[OpenRouter の BYOK 設定](https://openrouter.ai/workspaces/default/byok) を開くか、OpenRouter ダッシュボードで **「Settings」>「BYOK」** に移動します。BYOK キーは OpenRouter のワークスペース単位で管理されており、このリンクはデフォルトのワークスペースを開きます。
プロバイダーリストで SambaNova を検索し、選択します。
**「Key」** フィールドに SambaCloud の API キーを入力し、**「Enabled」** はオンのままにして、**「Save」** をクリックします。
保存する前に **「Test」** をクリックしてください。OpenRouter がそのキーで SambaNova を呼び出して結果を報告するため、後からアプリケーション側でデバッグすることなく、キーが有効かどうかをその場で確認できます。
**「Always use for this provider」** はデフォルトでオフになっています。オフの間は、お使いのキーがレート制限を受けたり拒否されたりするたびに、OpenRouter は自身の共有 SambaNova キャパシティにフォールバックし、それらのリクエストを SambaCloud アカウントではなく OpenRouter クレジットに課金します。
すべての SambaNova リクエストを必ずご自身のキー経由にしたい場合は、オンにしてください。その場合、暗黙のフォールバックは行われず、レート制限エラーが返されます。
## 対応モデル
OpenRouter では、SambaCloud のモデル ID ではなく、OpenRouter 独自のスラッグ (slug) でモデルを指定します。以下の SambaNova ホストのモデルは、OpenRouter 上の `sambanova` プロバイダー (BYOK キーの登録先となるプロバイダー) から提供されています。
| SambaCloud モデル ID | OpenRouter モデルスラッグ |
| :- | :- |
| `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` |
最新のリストは、BYOK ダイアログの **「View SambaNova supported models」** をクリックするか、OpenRouter の [SambaNova プロバイダーページ](https://openrouter.ai/provider/sambanova) でご確認ください。コンテキスト長と対応モダリティについては、[SambaCloud モデル](/docs/ja/models/sambacloud-models) をご参照ください。
SambaNova が OpenRouter 上で提供するすべてのモデルが `sambanova` プロバイダースラッグを使用しているわけではありません。たとえば `meta-llama/llama-3.3-70b-instruct` は、別のスラッグである `sambanova-turbo` から提供されています。`provider.only` に指定したスラッグは、そのプロバイダーおよび `/` 付きサフィックスのエンドポイントバリアントにマッチするため、`only: ["sambanova"]` では `sambanova-turbo` は選択されず、リクエストには利用可能な SambaNova エンドポイントがない状態になります。上の表のスラッグを使用するか、固定する前にモデルのページでプロバイダースラッグをご確認ください。
## Python SDK の利用
OpenRouter SDK をインストールします。
```bash theme={}
pip install "openrouter>=1.1,<2"
```
以下のサンプルコードで読み取れるよう、OpenRouter API キーをエクスポートします。
```bash theme={}
export OPENROUTER_API_KEY="your-openrouter-api-key"
```
SambaCloud のキーを環境変数に設定する必要はありません。OpenRouter がキーを保管し、SambaNova へのリクエストに自動的に付与します。
以下のコードで、OpenRouter 経由で SambaNova モデルにリクエストを送信します。`provider={"only": ["sambanova"]}` を設定するとルーティングが SambaNova に固定され、OpenRouter は共有の SambaNova キャパシティより先に 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"]},
)
print(response.choices[0].message.content)
```
成功時のレスポンスは `ChatResult` であり、`response.choices[0].message.content` に生成されたテキストが格納されます。
### ご自身のキーが使用されたことの確認
レスポンスが成功しただけでは、OpenRouter が自身の共有キャパシティではなく、ご自身の SambaCloud キーを使用したことの証明にはなりません。ルーターメタデータを有効にして `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"` は `X-OpenRouter-Metadata: enabled` ヘッダーを送信し、レスポンスに `openrouter_metadata` オブジェクトを追加します。`is_byok` は、リクエストがご自身のプロバイダーキーで処理された場合に `True`、OpenRouter の共有キャパシティで処理された場合に `False` になります。
### エラー処理
キーの拒否やクォータの枯渇が、トレースバックではなく読みやすいメッセージとして表示されるよう、呼び出しをラップします。
```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` は SDK が送出するすべての HTTP エラーの基底クラスで、`status_code`、`message`、`body` を公開しています。特定のステータスで処理を分岐したい場合は、`UnauthorizedResponseError` (401) や `TooManyRequestsResponseError` (429) などのサブクラスを捕捉してください。
## 請求
OpenRouter で BYOK (Bring Your Own Key) を使用する場合は、以下の点にご注意ください。
* 推論の料金は、ご自身の SambaCloud API キーを使用して SambaNova に直接支払います。
* OpenRouter は、同じモデルとプロバイダーを OpenRouter の標準料金で利用した場合の金額に基づいて、5% のプラットフォーム手数料を請求します。
* 手数料は、SambaCloud アカウントではなく OpenRouter クレジットから差し引かれます。
* 各プランには、リクエスト数ではなく定価ベースの推論コストで測定される、毎月の BYOK 無料枠が含まれます。Pay-as-you-go プランは月 25,000 ドル分、Enterprise プランは月 200,000 ドル分です。詳細は [OpenRouter の料金ページ](https://openrouter.ai/pricing) をご参照ください。
## トラブルシューティング
SambaCloud のキーが無効か、失効しているか、前後に空白が付いた状態で貼り付けられています。[SambaCloud ポータル](https://cloud.sambanova.ai/apis) でキーを再生成し、[BYOK 設定](https://openrouter.ai/workspaces/default/byok) で更新したうえで、再試行の前に **「Test」** をクリックして確認してください。
SambaCloud アカウントのレート制限に達しています。アカウントの制限値は [レート制限](/docs/ja/models/rate-limits) でご確認のうえ、バックオフを入れて再試行してください。
リクエストしたモデルに `sambanova` エンドポイントがないため、`provider={"only": ["sambanova"]}` ではルーティング先がなくなります。[対応モデル](#対応モデル) のスラッグを使用してください。
キーが無効化されているか、レート制限を受けたか、拒否されたため、リクエストが OpenRouter の共有 SambaNova キャパシティにフォールバックしています。キーを修正したうえで、**「Always use for this provider」** をオンにするとフォールバックを止められます。
`openrouter` パッケージには Python 3.10 以上が必要です。`python3 --version` で確認し、対応バージョンのインタープリターで作成した仮想環境にインストールしてください。
OpenRouter が試行した各プロバイダーの上流ステータスコードを確認するには、[Activity ページ](https://openrouter.ai/activity) を開き、該当の生成結果をクリックして **「View Raw Metadata」** を選択し、`provider_responses` フィールドをご確認ください。
## 参考情報
* [OpenRouter BYOK ドキュメント](https://openrouter.ai/docs/guides/overview/auth/byok)
* [OpenRouter プロバイダールーティング](https://openrouter.ai/docs/guides/routing/provider-selection)
* [OpenRouter Python SDK](https://github.com/OpenRouterTeam/python-sdk)
* [SambaCloud モデル](/docs/ja/models/sambacloud-models)
* [SambaCloud API リファレンス](/docs/ja/api-reference/overview)