Подключение приложения

Конечная точка Model Router совместима с OpenAI — укажите базовый URL Performance Hub в любом SDK OpenAI, фреймворке или инструменте с поддержкой BYOK, пройдите аутентификацию с одним из своих ключей API, и всё заработает. На этой странице приведено краткое руководство по интеграции.

Что вам понадобится

1. Ключ API. Чтобы создать его, необходимо быть Organisation Administrator. Создайте ключ в разделе «Настройки» (значок шестеренки) → 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 для вашей среды всегда отображается в модуле — копируйте его оттуда, а не с этой страницы.

Аутентификация

Передавайте ключ как токен bearer в каждом запросе:

Authorization: Bearer phk_your_key_here

Относитесь к ключу как к паролю. В случае утечки выполните Rotate (будет выпущен новый секрет, а старый сразу перестанет работать) или Revoke в списке ключей API.

Ваш первый запрос

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“, чтобы маршрутизатор выбирал лучшую модель для каждого запроса, или идентификатор любой модели, включенной для вашего объекта.»

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 или используйте 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 в своей интеграции — это ожидаемый сигнал о том, что у учетной записи закончились кредиты или достигнут бюджет, а не сбой.

Рекомендации

• Один ключ на систему. Выделите каждой интеграции отдельный ключ с меткой, чтобы использование можно было отследить в Activity и Logs, а при утечке достаточно было заменить только один ключ.
• Ограничивайте каждый ключ. Задайте для каждого ключа лимиты расходов и ограничения частоты, соответствующие системе; см. Ключи API.
• Предпочитайте auto, если вам не нужна конкретная модель: простые задачи будут выполнять быстрые и недорогие модели, а самые мощные модели будут использоваться только тогда, когда этого требует задача.
• Следите за вкладкой Logs во время интеграции — каждый запрос отображается со статусом, токенами и стоимостью, что позволяет быстро устранять проблемы интеграции. См. Активность и журналы.