7 ステップで、最初のリクエストまで届きます。
API をはじめて使う方向けのガイドです。クライアントのインストールから、API キーの作成、CCSwitch への取り込み、Codex での「hi」の送信までを順に進めます。各ステップで「何が見えていれば正解か」を明記しています。
https://api.blue-ring.xyz/v1はじめる前に、用意するものは 3 つだけ
このガイドは CCSwitch + Codex の流れで書いています。API だけを呼ぶ開発者は、最後の任意セクションまで読み飛ばしてください。
コンソールへのログイン、キーの作成、利用量の確認に使います。
Codex + CCSwitch がおすすめです。開発者はターミナルや Python でも構いません。
コンソールから取り込むと、CCSwitch がこの Provider 設定を Codex に渡します。
この章を終えると：Codex で正常な返信が表示され、コンソールの利用量ページに今回のリクエストが残ります。
Codex と CCSwitch をインストールする
先にインストール、設定はそのあとです。Provider がない段階で Codex の既定設定を触らないでください。
- Codex をインストールお使いのシステムの手順でインストールします。この時点では複雑な設定を作らないでください。
- CCSwitch をインストールCCSwitch は Provider を保存・切り替えるツールで、Windows / macOS / Linux に対応しています。公式リリースページから、お使いの環境に合うパッケージをダウンロードします。CCSwitch をダウンロード
- 両方のアプリが開くウィンドウが表示されれば十分です。まだ API キーがないので、リクエストは送りません。
API だけを呼ぶ開発者はこの 2 つのツールは不要です。最後の「API を直接呼ぶ（任意）」へ進んでください。
Blue Ring に登録またはログインする
キーも利用量もコンソールで管理します。他人に「共通キー」を求めないでください。
左メニューまたはページ内に API Keys / API キー の入口が見えています。
API キーを作成し、その場で保存する
キーは呼び出しの権限そのものです。端末や用途ごとに分けて作ると、問題が起きたときにその 1 つだけを取り消せます。
- API Keys を開くコンソールで API Keys / API キーのページを開きます。
- キー作成をクリック名前は
codex-macや開発テストなど、判別しやすいものにします。 - グループを選ぶグループやモデルグループの指定がある場合は、使いたい機能に合わせて選びます。迷ったら既定値のままで構いません。
- 作成後に完全なキーをコピー作成直後に一度だけコピーし、CCSwitch の安全な設定に保存します。グループチャットには貼らないでください。
sk-••••••••••••••••••••••••非表示完全なキーをスクリーンショット、Git、公開 issue、チャット履歴に残さないでください。
キーをパスワードマネージャーまたはクライアントの安全な保存領域に入れ、どの端末用か分かっている状態です。
Provider を取り込む（モデルは手入力しない）
コンソールの「CC Switch にインポート」ボタンを優先してください。自動取り込みが使えないときだけ、下の項目を手で入力します。
CC Switch にインポート をクリックします。図の名前とキーはすべてマスク済みです。作成したキーを探し、「CC Switch にインポート」をクリックします（ボタンがある場合）。
ブラウザがアプリの起動を確認したら許可し、CCSwitch 側で取り込みをクリックします。
判別しやすい名前を入力して追加・保存し、最後に有効化をクリックします。
https://api.blue-ring.xyz/v1/v1 は残す。具体的なリクエストパスまで書かない作成したキー前後の引用符ごとコピーしない。他人のキーを使わないクライアントの案内に従う取り込み経路では通常、追加設定は不要CCSwitch で「有効化」をクリックする
ターミナルを開く必要も、先にモデル一覧を取得する必要もありません。CCSwitch の設定が済めば、Codex はこの Provider をそのまま使います。
CCSwitch の Provider 一覧で、いま取り込んだ設定を見つけます。
2 つ目の設定を新規作成せず、いまの 1 つを有効にします。
「使用中」または有効の表示が出れば、Codex に設定が渡っています。
CCSwitch の Blue Ring 設定が有効または使用中になっています。
Codex を開いて hi と入力する
CCSwitch の設定が済んでいれば、Codex は有効化した Provider をそのまま使います。
hi と入力し、送信します。正常な返信が来たら次へ進みます。Codex が hi に対して正常な内容を返しています。
コンソールで利用量を見る
Codex が正常に返信するようになったら、コンソールに戻ってリクエスト記録と消費を確認します。
クライアントの読み込み状態だけでなく、メッセージの中身を見ます。
コンソールの利用記録または利用量ページに戻ります。
先ほどのリクエストと消費が見えれば、経路全体がつながっています。
Blue Ring につながりました
モデルやクライアントを変えるときも、確認するのは Base URL、API Key、Model の 3 つだけです。
Codex が内容を返せば、クライアントは接続済みです。
コンソールの利用記録に今回のリクエストがあるはずです。
今回の呼び出しで Token または料金が発生していることを確認します。
API を直接呼び出しますか？
以下のモデル一覧、curl、Python は API 開発者向けです。CCSwitch + Codex で進めた方は読み飛ばしてください。
ここは Codex の必須ステップではありません。ターミナル、スクリプト、自作プログラムから Blue Ring を呼ぶ場合だけ続けてください。
export BLUE_RING_API_KEY="あなたの API キー"
curl "https://api.blue-ring.xyz/v1/models" \
-H "Authorization: Bearer $BLUE_RING_API_KEY"export BLUE_RING_API_KEY="あなたの API キー"
export BLUE_RING_MODEL="/v1/models が返したモデル ID"
curl "https://api.blue-ring.xyz/v1/responses" \
-H "Authorization: Bearer $BLUE_RING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$BLUE_RING_MODEL"'",
"input": "こんにちは。自己紹介を一文でお願いします。"
}'OpenAI SDK では base_url と api_key を差し替えるだけです。
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.blue-ring.xyz/v1",
)
response = client.responses.create(
model="YOUR_MODEL_ID",
input="Hello from Blue Ring",
)
print(response.output_text)よくある質問：まずステータスコードを見る
CCSwitch が有効かどうかを先に確認し、そのうえでキー、パス、上流のどれが原因かを切り分けます。
401API_KEY_REQUIRED / 認証エラー
有効なキーが付いていません。Authorization: Bearer ... があるか、環境変数が空でないか、キーを誤った項目に入れていないかを確認してください。
404chat/completions が見つからない
現在の公開入口の主なパスは /v1/responses です。クライアントが /v1/chat/completions しか送れない場合は、Responses API / OpenAI Responses モードに切り替えてください。
200応答はあるがモデルが使えない
CCSwitch 経由なら、まず Provider が有効か再確認します。API を直接呼ぶ場合は /v1/models を取得し、返ってきたモデル ID を使ってください。
—リクエストが止まる・タイムアウトする
まず最短のテキストで試します。余分なプロキシ、誤ったストリーミング設定、/v1 の重複がないかを確認してから、上流の一時的な混雑かを判断します。
↗取り込み後も Codex が反応しない
Provider が有効か、Base URL に /v1 が残っているかを再確認し、Codex を閉じて開き直して最新の設定を読ませてください。
API キーの安全管理：3 つの原則
API キーはアカウントの呼び出し権限そのものです。通常の設定ではなく、パスワードとして扱ってください。
チュートリアル、グループチャット、チケット、画面録画に完全なキーを出さないでください。
ローカルでは環境変数かクライアントの安全な保存領域を使い、リポジトリには書きません。
コンソールで古いキーを削除し、新しいキーを作ってクライアント設定を差し替えます。