OpenRouter BYOK

OpenRouter は、OpenRouter クレジットと Bring Your Own Key (BYOK) の両方に対応しています。OpenRouter クレジットを使用する場合、SambaNova のレート制限は OpenRouter によって管理されます。ご自身の SambaNova API キーを使用する場合は、SambaNova アカウントを通じてレート制限と請求を直接管理できます。プロバイダーキーはすべて安全に暗号化され、SambaNova にルーティングされるリクエストにのみ使用されます。

前提条件

作業を始める前に、以下の環境を準備してください。

SambaCloud アカウントと API キー。API キーをお持ちでない場合は、SambaCloud ポータルから取得してください。
OpenRouter アカウントと API キー。API キーは OpenRouter のキー管理ページで取得できます。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 に接続するには、以下の手順に従ってください。

BYOK 設定に移動

OpenRouter の BYOK 設定を開くか、OpenRouter ダッシュボードで 「Settings」>「BYOK」 に移動します。BYOK キーは OpenRouter のワークスペース単位で管理されており、このリンクはデフォルトのワークスペースを開きます。

BYOK が選択された OpenRouter の Settings サイドバーと、利用可能なプロバイダーの一覧

プロバイダーとして SambaNova を選択

プロバイダーリストで SambaNova を検索し、選択します。

SambaNova が選択された OpenRouter BYOK のプロバイダー検索

SambaCloud API キーの追加

「Key」 フィールドに SambaCloud の API キーを入力し、「Enabled」 はオンのままにして、「Save」 をクリックします。保存する前に 「Test」 をクリックしてください。OpenRouter がそのキーで SambaNova を呼び出して結果を報告するため、後からアプリケーション側でデバッグすることなく、キーが有効かどうかをその場で確認できます。

Key フィールド、Enabled トグル、Always use for this provider トグルが表示された Enable SambaNova Key ダイアログ

OpenRouter キャパシティへのフォールバック可否の選択

「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 プロバイダーページでご確認ください。コンテキスト長と対応モダリティについては、SambaCloud モデルをご参照ください。

SambaNova が OpenRouter 上で提供するすべてのモデルが sambanova プロバイダースラッグを使用しているわけではありません。たとえば meta-llama/llama-3.3-70b-instruct は、別のスラッグである sambanova-turbo から提供されています。provider.only に指定したスラッグは、そのプロバイダーおよび / 付きサフィックスのエンドポイントバリアントにマッチするため、only: ["sambanova"] では sambanova-turbo は選択されず、リクエストには利用可能な SambaNova エンドポイントがない状態になります。上の表のスラッグを使用するか、固定する前にモデルのページでプロバイダースラッグをご確認ください。

Python SDK の利用

OpenRouter SDK をインストールします。

pip install "openrouter>=1.1,<2"

以下のサンプルコードで読み取れるよう、OpenRouter API キーをエクスポートします。

export OPENROUTER_API_KEY="your-openrouter-api-key"

SambaCloud のキーを環境変数に設定する必要はありません。OpenRouter がキーを保管し、SambaNova へのリクエストに自動的に付与します。以下のコードで、OpenRouter 経由で SambaNova モデルにリクエストを送信します。provider={"only": ["sambanova"]} を設定するとルーティングが SambaNova に固定され、OpenRouter は共有の SambaNova キャパシティより先に 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"]},
    )

print(response.choices[0].message.content)

成功時のレスポンスは ChatResult であり、response.choices[0].message.content に生成されたテキストが格納されます。

ご自身のキーが使用されたことの確認

レスポンスが成功しただけでは、OpenRouter が自身の共有キャパシティではなく、ご自身の SambaCloud キーを使用したことの証明にはなりません。ルーターメタデータを有効にして 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" は X-OpenRouter-Metadata: enabled ヘッダーを送信し、レスポンスに openrouter_metadata オブジェクトを追加します。is_byok は、リクエストがご自身のプロバイダーキーで処理された場合に True、OpenRouter の共有キャパシティで処理された場合に False になります。

エラー処理

キーの拒否やクォータの枯渇が、トレースバックではなく読みやすいメッセージとして表示されるよう、呼び出しをラップします。

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 の料金ページをご参照ください。

トラブルシューティング

SambaNova に対する 401 Unauthorized

SambaCloud のキーが無効か、失効しているか、前後に空白が付いた状態で貼り付けられています。SambaCloud ポータルでキーを再生成し、BYOK 設定で更新したうえで、再試行の前に 「Test」 をクリックして確認してください。

SambaNova に対する 429 Too Many Requests

SambaCloud アカウントのレート制限に達しています。アカウントの制限値はレート制限でご確認のうえ、バックオフを入れて再試行してください。

利用可能なプロバイダーがなくリクエストが失敗する

リクエストしたモデルに sambanova エンドポイントがないため、provider={"only": ["sambanova"]} ではルーティング先がなくなります。対応モデルのスラッグを使用してください。

成功レスポンスで is_byok が False になる

キーが無効化されているか、レート制限を受けたか、拒否されたため、リクエストが OpenRouter の共有 SambaNova キャパシティにフォールバックしています。キーを修正したうえで、「Always use for this provider」 をオンにするとフォールバックを止められます。

pip install が失敗する、または想定外のバージョンが解決される

openrouter パッケージには Python 3.10 以上が必要です。python3 --version で確認し、対応バージョンのインタープリターで作成した仮想環境にインストールしてください。

OpenRouter が試行した各プロバイダーの上流ステータスコードを確認するには、Activity ページを開き、該当の生成結果をクリックして 「View Raw Metadata」 を選択し、provider_responses フィールドをご確認ください。

概要

開発者ツール

フレームワーク

インターフェースとローコード

データとインフラ

マルチモーダル

評価とモニタリング

前提条件

セットアップ

対応モデル

Python SDK の利用

ご自身のキーが使用されたことの確認

エラー処理

請求

トラブルシューティング

参考情報

​前提条件

​セットアップ

​対応モデル

​Python SDK の利用

​ご自身のキーが使用されたことの確認

​エラー処理

​請求

​トラブルシューティング

​参考情報

前提条件

セットアップ

対応モデル

Python SDK の利用

ご自身のキーが使用されたことの確認

エラー処理

請求

トラブルシューティング

参考情報