アプリケーションの接続

モデルルーターのエンドポイントは OpenAI 互換 です。OpenAI SDK、フレームワーク、BYOK に対応したツールの接続先を Performance Hub のベース URL に設定し、API キーのいずれかで認証するだけで、そのまま動作します。このページは、連携のためのクイックスタートです。

必要なもの

1. API キー。 キーを作成するには、組織管理者である必要があります。Settings（歯車）→ Service Access & API Keys → Create key で作成します。キーは phk_ で始まり、シークレットは一度だけ表示されます。詳しくは、API キー を参照してください。
2. ベース URL。 同じ設定ページの Connecting to the API カードに表示されます。

図 1：Connecting to the API：ベース URL と、コピーして貼り付けられるリクエストの例

https://app.performancehub.co/ai/v1

環境に応じた正確なベース URL は、常にモジュール内に表示されます。このページからではなく、モジュールからコピーしてください。

認証

すべてのリクエストで、キーをベアラートークンとして送信します。

Authorization: Bearer phk_your_key_here

キーはパスワードと同様に扱ってください。漏洩した場合は、API キーの一覧からキーを Rotate（新しいシークレットが発行され、古いシークレットはすぐに使用できなくなります）するか、Revoke してください。

最初のリクエスト

curl

curl https://app.performancehub.co/ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Hello"}]}'

"モデル 'auto' を使用すると、リクエストごとにルーターが最適なモデルを自動選択するか、施設で有効になっている任意のモデルIDを使用できます。"

Python（OpenAI SDK）

from openai import OpenAI

client = OpenAI(
    base_url="https://app.performancehub.co/ai/v1",
    api_key="YOUR_API_KEY",
)

response = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

TypeScript / Node（OpenAI SDK）

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://app.performancehub.co/ai/v1',
  apiKey: process.env.PH_API_KEY,
});

const response = await client.chat.completions.create({
  model: 'auto',
  messages: [{ role: 'user', content: 'Hello' }],
});
console.log(response.choices[0].message.content);

モデルの一覧の取得

GET /v1/models は、施設で有効になっているすべてのモデルを返します（キーごとのモデルの制限も反映されます）。モデルの一覧は残高がゼロでも取得できるため、アカウントに入金する前に、連携先でカタログを確認できます。

curl https://app.performancehub.co/ai/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

返されたモデル ID のいずれかを model フィールドに指定するか、auto を指定して Auto Router にリクエストごとに最適なモデルを選択させます。

ストリーミング

ストリーミングは、OpenAI の標準的な方法で動作します。"stream": true を設定し、サーバー送信イベントのチャンクを受信します。上記の SDK の例でも、通常のストリーミング API を使って対応できます。

モデルのフォールバック

順序付きのフォールバックチェーンを指定すると、プライマリモデルが失敗した場合に、次のモデルでリクエストが再試行されます。

• models: ["model-a", "model-b", "model-c"]：順序付きの完全なリストです。最初の項目がプライマリになります。
• または model: "model-a" と fallbacks: ["model-b", "model-c"]：プライマリの後に試行されるバックアップです。

フォールバックの候補は、キーで使用が許可されているモデルに絞り込まれます。

エラーレスポンス

エラーには、OpenAI の標準的なエラーエンベロープ { "error": { "message", "type", "code" } } が使用されます。

どちらの 402 エラーにも docsUrl フィールドが含まれ、メッセージの末尾には Performance Hub のドキュメントへのリンクが記載されます。

連携では 402 を適切に処理してください。402 は障害ではなく、アカウントのクレジットがなくなったときや予算の上限に達したときに想定されるシグナルです。

推奨される方法

• システムごとに 1 つのキーを使う。 連携ごとにラベル付きの専用キーを用意すると、Activity と Logs で使用状況を識別でき、漏洩した場合も 1 つのキーをローテーションするだけで済みます。
• 各キーを制限する。 システムに応じて、キーごとの支出の上限とレート制限を設定します。詳しくは、API キー を参照してください。
• auto を優先する。 特定のモデルが必要な場合を除き、auto を使用してください。簡単な処理には高速で低価格なモデルが使われ、最も高性能なモデルはタスクで必要な場合にのみ使われます。
• Logs タブを確認する。 連携の作業中は Logs タブを確認してください。すべてのリクエストがステータス、トークン、コストとともに表示されるため、連携の問題をすばやくデバッグできます。詳しくは、アクティビティとログ を参照してください。