连接您的应用程序
本页内容
Model Router 端点兼容 OpenAI：将任何 OpenAI SDK、框架或支持 BYOK 的工具指向 Performance Hub 基础 URL，并使用您的某个 API 密钥进行身份验证，即可直接使用。本页是集成快速入门。
您需要准备什么
- **API 密钥。**您必须是 Organisation Administrator 才能创建密钥。在 Settings（齿轮）→ Service Access & API Keys → Create key 下创建。密钥以
phk_开头，且只显示一次。请参阅 API 密钥。 - **基础 URL。**显示在同一设置页面的 Connecting to the API 卡片中：
图 1：Connecting to the API：基础 URL 和可直接复制粘贴的示例请求
https://app.performancehub.co/ai/v1
适用于您环境的确切基础 URL 始终显示在模块中，请从模块中复制，而不要从本页复制。
身份验证
在每个请求中将您的密钥作为 bearer 令牌发送：
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"}]}'
"Use model 'auto' to let the router pick the best model per request, or any model ID enabled for your facility."（使用模型 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"
在 model 字段中使用返回的任何模型 ID，或使用 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" } }。
| HTTP | type | code | 含义 | 处理方法 |
|---|---|---|---|---|
| 401 | invalid_request_error | invalid_api_key | 缺少 API 密钥，或已连接服务的凭据无效。 | 检查 Authorization: Bearer 标头。 |
| 401 | invalid_request_error | — | 未知或已吊销的 API 密钥（"Invalid API key"）。 | 重新激活该密钥或创建新密钥。 |
| 402 | insufficient_quota | insufficient_credits | 预付余额已耗尽（对于已连接服务，也可能是设施未启用该模块）。 | 充值（或启用自动充值）。 |
| 402 | insufficient_quota | budget_exceeded | 已达到支出限额：可能是设施范围的限额，也可能是此密钥或已连接服务的限额。消息会说明是哪个时间窗口，对于每日/每月限额，还会注明按设施时区计算的确切重置时间。响应正文还包含 window、resetsAt、timezone 和 docsUrl 字段。 | 等待重置、提高限额或重置硬性上限。 |
| 403 | invalid_request_error | — | "Model Router is not enabled for this facility"（API 密钥），或 "Facility has no provisioned inference key"（该密钥没有对应的推理密钥）。 | 为该设施启用 Model Router（请参阅入门）。如果已经启用，请轮换该密钥或创建新密钥。 |
| 403 | invalid_request_error | content_policy_violation | "Request blocked by content policy"：阻止模式的内容过滤器或提示注入防护与提示匹配。 | 检查 Guardrails 设置。 |
| 429 | — | — | 超出速率限制（密钥上设置的每分钟请求数/每分钟令牌数）。 | 退避后重试；如有需要，提高密钥的速率限制。 |
| 502 | server_error | — | 上游推理服务暂时不可用。 | 使用退避策略重试。 |
两种 402 错误都包含 docsUrl 字段，其消息末尾附有指向 Performance Hub 文档的链接。
请在您的集成中妥善处理 402：它是账户额度耗尽或达到预算时的预期信号，而不是故障。