Connettere la tua applicazione

L'endpoint di Model Router è compatibile con OpenAI: indirizza qualsiasi SDK OpenAI, framework o strumento compatibile con BYOK all'URL di base del Performance Hub, autenticati con una delle tue chiavi API e tutto funziona. Questa pagina è la guida rapida all'integrazione.

Cosa ti serve

1. Una chiave API. Per crearne una devi essere un Organisation Administrator. Creala in Settings (ingranaggio) → Service Access & API Keys → Create key. Le chiavi iniziano con phk_ e il segreto viene mostrato una sola volta. Vedi Chiavi API.
2. L'URL di base. È mostrato nella scheda Connecting to the API nella stessa pagina delle impostazioni:

Figura 1: Connecting to the API: l'URL di base e una richiesta di esempio da copiare e incollare

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

L'URL di base esatto per il tuo ambiente è sempre mostrato nel modulo: copialo da lì anziché da questa pagina.

Autenticazione

Invia la tua chiave come token bearer in ogni richiesta:

Authorization: Bearer phk_your_key_here

Tratta la chiave come una password. Se trapela, usa Rotate (viene emesso un nuovo segreto e quello vecchio smette di funzionare immediatamente) oppure Revoke dall'elenco delle chiavi API.

La tua prima richiesta

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

"Usa il model 'auto' per consentire al router di scegliere il model migliore per richiesta, o qualsiasi ID model abilitato per la tua Struttura."

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

Elencare i modelli

GET /v1/models restituisce tutti i modelli attivati per la tua struttura (rispettando eventuali restrizioni sui modelli per chiave). L'elenco dei modelli funziona anche quando il saldo è zero, così le integrazioni possono scoprire il catalogo prima che l'account venga finanziato.

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

Usa qualsiasi ID di modello restituito nel campo model, oppure usa auto per lasciare che l'Auto Router scelga il modello migliore per ogni richiesta.

Streaming

Lo streaming funziona nel modo standard di OpenAI: imposta "stream": true e utilizza i blocchi di eventi inviati dal server. Gli esempi di SDK riportati sopra lo supportano tramite le consuete API di streaming.

Modelli di riserva

Puoi fornire una catena ordinata di modelli di riserva, in modo che, se il modello principale non riesce, la richiesta venga ritentata con il successivo:

• models: ["model-a", "model-b", "model-c"]: un elenco ordinato completo; la prima voce è il modello principale.
• oppure model: "model-a" più fallbacks: ["model-b", "model-c"]: modelli di riserva provati dopo quello principale.

I modelli di riserva candidati vengono filtrati in base ai modelli che la tua chiave è autorizzata a usare.

Risposte di errore

Gli errori usano la struttura di errore standard di OpenAI: { "error": { "message", "type", "code" } }.

Entrambi gli errori 402 includono un campo docsUrl e il loro messaggio termina con un link alla documentazione del Performance Hub.

Gestisci correttamente l'errore 402 nella tua integrazione: è il segnale previsto quando un account esaurisce il credito o raggiunge un budget, non un guasto.

Buone pratiche

• Una chiave per sistema. Assegna a ogni integrazione una propria chiave con etichetta, in modo che l'utilizzo sia attribuibile in Activity e Logs e che, in caso di fuga, sia necessario ruotare una sola chiave.
• Delimita ogni chiave. Imposta tetti di spesa e limiti di frequenza per chiave adeguati al sistema; vedi Chiavi API.
• Preferisci auto a meno che non ti serva un modello specifico: ottieni modelli veloci ed economici per il lavoro semplice e i modelli più potenti solo quando un'attività li richiede.
• Tieni d'occhio la scheda Logs durante l'integrazione: ogni richiesta compare con stato, token e costo, il che rende rapido il debug dei problemi di integrazione. Vedi Attività e log.