BYOK (Bring Your Own Key)

コード管理の credential preset を選び、検証済みプロバイダー API キーでルーティングします。

BYOK（Bring Your Own Key）は、プロバイダーの従量課金 API アカウントで発行されたキーを暗号化して保存し、そのキーでリクエストをルーティングする機能です。モデル料金はプロバイダーへ直接支払い、無料枠超過後は PleumRouter のサービス手数料だけをクレジットで支払います。

BYOK はメール申請やアカウント単位の審査制度ではありません。運用状態が有効なら、すべての認証済みユーザーが live・approved・公式無課金検証対応のプリセットを接続できます。運用停止時も、新規接続と再検証だけが止まり、状態・カタログ・過去利用量・既存キー一覧は確認でき、既存キーの解除も可能です。

状態と利用量#

GET/v1/byok/status

GET/v1/byok/usage

GET /v1/byok/status は運用状態、無料枠超過後の手数料率、月間無料トークン枠を返します。GET /v1/byok/usage は UTC 基準の今月の BYOK トークン、残り枠、請求クレジット、プロバイダー別内訳を返します。毎月1日 00:00 UTC にリセットされます。

GET /v1/byok/status · 200 OK

{
  "enabled": true,
  "fee_percent": 1.0,
  "free_monthly_tokens": 1000000000,
  "market": "kr"
}

GET /v1/byok/usage · 200 OK

{
  "month_tokens": 1240000,
  "free_monthly_tokens": 1000000000,
  "free_remaining_tokens": 998760000,
  "fee_charged_krw": 0,
  "by_provider": [
    {"provider": "openai", "tokens": 1240000, "fee_krw": 0}
  ]
}

プリセットカタログ#

GET/v1/byok/catalog

GET /v1/byok/catalog はサーバー管理の不変プリセットを返します。接続できるのは availability=live、contract_status=approved、connection_enabled=true で公式無課金検証を持つ PAYG プリセットだけです。endpoint・protocol・auth_scheme は固定され、ユーザーは変更できません。

info_only のトークンプラン・コーディングプラン・コンシューマー向けサブスクリプションは、情報と関心登録だけを提供します。ChatGPT・Claude・Gemini などのサブスクリプションに従量制 API 利用は含まれず、BYOK 資格情報には使えません。別途請求される API アカウントが必要です。

200 OK

{
  "data": [
    {
      "preset_id": "openai.payg.default",
      "provider": "openai",
      "kind": "payg",
      "display_name_key": "byok.preset.openai.payg",
      "display_name_en": "OpenAI PAYG API",
      "availability": "live",
      "contract_status": "approved",
      "endpoint": "https://api.openai.com/v1/chat/completions",
      "region": "global",
      "protocol": "openai_chat",
      "auth_scheme": "bearer",
      "supported_protocols": ["openai_chat"],
      "official_price_equivalent_ref": "model_catalog.provider:openai",
      "validation": {"kind": "openai_models", "zero_cost": true},
      "allowed_use_key": "byok.provider_api_key_only",
      "allowed_use_en": "Use an API key issued for this provider's metered API account.",
      "connection_enabled": true,
      "referral_enabled": false
    },
    {
      "preset_id": "openai.chatgpt-subscription",
      "provider": "openai",
      "kind": "consumer_subscription",
      "display_name_key": "byok.preset.openai.chatgpt-subscription",
      "display_name_en": "ChatGPT Consumer Subscription",
      "availability": "info_only",
      "contract_status": "not_api_compatible",
      "endpoint": null,
      "region": "global",
      "protocol": "openai_chat",
      "auth_scheme": "bearer",
      "supported_protocols": ["openai_chat"],
      "official_price_equivalent_ref": null,
      "validation": {"kind": "none", "zero_cost": false},
      "allowed_use_key": "byok.separate_api_billing_required",
      "allowed_use_en": "ChatGPT subscriptions do not include metered API usage; use a separately billed API key.",
      "connection_enabled": false,
      "referral_enabled": false
    }
  ]
}

キーの接続と検証#

POST/v1/byok/keys

POST /v1/byok/keys に送るのは正確な preset_id と api_key だけです。ユーザー endpoint や交渉単価は受け付けません。サーバーは暗号化保存を先に確認し、プリセットの公式無課金エンドポイントで直ちに検証します。検証済み資格情報だけが有効になります。

パラメータ	型	必須	説明
preset_id	string	必須	GET /v1/byok/catalog から選んだ正確なプリセット ID。別名は非対応です。
api_key	string	必須	そのプロバイダーの従量制 API アカウント発行キー。前後空白除去後 8〜500 文字で、平文は返しません。

request

curl -X POST https://apirouter.pleum.ai/v1/byok/keys \
  -H "Authorization: Bearer <session_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "preset_id": "openai.payg.default",
    "api_key": "sk-..."
  }'

応答には末尾4文字だけの key_hint とサーバー検証状態が入り、平文は含まれません。失敗した登録は inactive/failed として残ることがあり、限定されたエラーコードに秘密値は含まれません。

200 OK

{
  "id": "b1f2c3d4-...",
  "preset_id": "openai.payg.default",
  "provider": "openai",
  "kind": "payg",
  "key_hint": "••••a1b2",
  "is_active": true,
  "verification_status": "verified",
  "verification_attempted_at": "2026-08-12T09:00:00Z",
  "verified_at": "2026-08-12T09:00:00Z",
  "last_verification_error": null,
  "created_at": "2026-08-12T09:00:00Z"
}

GET/v1/byok/keys

POST/v1/byok/keys/{id}/verify

DELETE/v1/byok/keys/{id}

GET /v1/byok/keys で一覧、POST /v1/byok/keys/{id}/verify で再検証、DELETE /v1/byok/keys/{id} で解除します。運用停止中も一覧と解除は利用できますが、再検証は利用できません。旧方式のキーは verification_required となり、再検証前はルーティングされません。

課金とルーティング#

毎月最初の10億 BYOK トークンまで Pleum サービス手数料は 0% です。超過分にはプロバイダー公式定価換算額の 1% をユーザー市場通貨のクレジットで請求します。実際の status/usage 応答が権威です。プロバイダー料金とアカウント上限はユーザーが直接負担します。

登録済み資格情報が未検証・失敗・復号不能なら、同じプロバイダーの Pleum 管理キーへ暗黙に自動切替しません。通常のルーティングポリシーが別の利用可能な offering を選ぶ場合はあります。

プラン診断・関心・紹介#

POST/v1/byok/recommendations

POST /v1/byok/recommendations の本文で受け付けるのは、ツール・月間予想トークン・予算帯・必須モデル・ホスティングリージョンだけです。サーバーは認証済みユーザーの永続アカウントから権威ある市場を取得し、クライアント指定の market は受け付けません。提携キャンペーン・手数料・報酬額はスコアに影響しません。

request

curl -X POST https://apirouter.pleum.ai/v1/byok/recommendations \
  -H "Authorization: Bearer <session_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "coding",
    "monthly_tokens": 50000000,
    "budget": "low",
    "required_models": [],
    "region": "global"
  }'

POST/v1/byok/plans/{preset_id}/interest

POST /v1/byok/plans/{preset_id}/interest は同じユーザーとプリセットに対して冪等です。info_only 項目への関心登録で接続・申込・報酬が有効になることはありません。

外部紹介リンクは、運営者承認済みキャンペーンが live であり、キャンペーン API が確認した場合だけ表示します。提携・スポンサー関係は順位と分けて開示し、確認済みキャンペーンがなければ外部遷移 CTA はありません。現在、紹介ボーナスの精算・付与・取消経路もありません。

現在の対応範囲と責任#

BYOK は現在、非同期の動画・3D 生成ジョブをサポートせず、リクエストは 400 で拒否されます。ジョブ境界を越えて BYOK 状態を安全に保存・精算できるまで fail-closed で制限します。

キー権限・残高・支払方法・ローテーション・削除はプロバイダーコンソールで管理してください。PleumRouter は平文キーを再表示しません。