Connecter votre application

Le point de terminaison Model Router est compatible OpenAI : pointez n'importe quel SDK OpenAI, framework ou outil compatible BYOK vers l'URL de base de Performance Hub, authentifiez-vous avec l'une de vos clés API, et tout fonctionne. Cette page est le guide de démarrage rapide de l'intégration.

Ce dont vous avez besoin

1. Une clé API. Vous devez être Organisation Administrator pour en créer une. Créez-la sous Settings (roue dentée) → Service Access & API Keys → Create key. Les clés commencent par phk_ et le secret n'est affiché qu'une seule fois. Consultez Clés API.
2. L'URL de base. Elle est affichée dans la carte Connecting to the API de la même page de paramètres :

Figure 1 : Connecting to the API : l'URL de base et un exemple de requête à copier-coller

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

L'URL de base exacte de votre environnement est toujours affichée dans le module : copiez-la depuis le module plutôt que depuis cette page.

Authentification

Envoyez votre clé sous forme de jeton bearer avec chaque requête :

Authorization: Bearer phk_your_key_here

Traitez la clé comme un mot de passe. En cas de fuite, utilisez Rotate (un nouveau secret est émis et l'ancien cesse immédiatement de fonctionner) ou Revoke depuis la liste des clés API.

Votre première requête

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"}]}'

"Utilisez le modèle 'auto' pour laisser le routeur choisir le meilleur modèle pour chaque requête, ou n'importe quel ID de modèle activé pour votre installation."

Python (SDK OpenAI)

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 (SDK OpenAI)

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);

Lister les modèles

GET /v1/models renvoie chaque modèle activé pour votre installation (en tenant compte de toute restriction de modèles par clé). La liste des modèles fonctionne même lorsque votre solde est à zéro, de sorte que les intégrations peuvent découvrir le catalogue avant que le compte ne soit approvisionné.

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

Utilisez n'importe quel ID de modèle renvoyé dans le champ model, ou utilisez auto pour laisser l'Auto Router choisir le meilleur modèle pour chaque requête.

Streaming

Le streaming fonctionne de la manière standard d'OpenAI : définissez "stream": true et consommez les fragments d'événements envoyés par le serveur (server-sent events). Les exemples de SDK ci-dessus le prennent en charge via leurs API de streaming habituelles.

Modèles de repli

Vous pouvez fournir une chaîne de repli ordonnée afin que, si le modèle principal échoue, la requête soit relancée sur le suivant :

• models: ["model-a", "model-b", "model-c"] : une liste ordonnée complète ; la première entrée est le modèle principal.
• ou model: "model-a" avec fallbacks: ["model-b", "model-c"] : des modèles de secours essayés après le modèle principal.

Les candidats de repli sont filtrés selon les modèles que votre clé est autorisée à utiliser.

Réponses d'erreur

Les erreurs utilisent l'enveloppe d'erreur OpenAI standard : { "error": { "message", "type", "code" } }.

Les deux erreurs 402 comportent un champ docsUrl, et leur message se termine par un lien vers la documentation Performance Hub.

Gérez correctement les erreurs 402 dans votre intégration : il s'agit du signal attendu lorsqu'un compte n'a plus de crédit ou atteint un budget, et non d'une panne.

Bonnes pratiques

• Une clé par système. Attribuez à chaque intégration sa propre clé avec un libellé afin que l'utilisation soit attribuable dans Activity et Logs, et qu'une fuite ne nécessite la rotation que d'une seule clé.
• Encadrez chaque clé. Définissez des plafonds de dépenses et des limites de débit par clé adaptés au système ; consultez Clés API.
• Privilégiez auto sauf si vous avez besoin d'un modèle précis : vous bénéficiez de modèles rapides et économiques pour les tâches simples, et des modèles les plus puissants uniquement lorsqu'une tâche l'exige.
• Surveillez l'onglet Logs pendant l'intégration : chaque requête y apparaît avec son état, ses tokens et son coût, ce qui accélère le débogage des problèmes d'intégration. Consultez Activité et journaux.