Je applicatie verbinden

Op deze pagina

Het endpoint van Model Router is OpenAI-compatibel: laat een OpenAI-SDK, framework of tool met BYOK-ondersteuning naar de basis-URL van Performance Hub verwijzen, authenticeer met een van je API-sleutels en het werkt gewoon. Deze pagina is de snelstart voor integratie.

Wat je nodig hebt

Een API-sleutel. Je moet Organisation Administrator zijn om er een aan te maken. Maak de sleutel aan onder Settings (tandwiel) → Service Access & API Keys → Create key. Sleutels beginnen met phk_ en het geheim wordt maar één keer getoond. Zie API-sleutels.
De basis-URL. Deze staat op de kaart Connecting to the API op dezelfde instellingenpagina:

De kaart Connecting to the API

Afbeelding 1: Connecting to the API: de basis-URL en een voorbeeldaanvraag om te kopiëren en te plakken

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

De exacte basis-URL voor je omgeving wordt altijd in de module getoond. Kopieer hem daar en niet van deze pagina.

Authenticatie

Stuur je sleutel bij elke aanvraag mee als bearer-token:

Authorization: Bearer phk_your_key_here

Behandel de sleutel als een wachtwoord. Als hij uitlekt, gebruik dan Rotate (er wordt een nieuw geheim uitgegeven en het oude werkt meteen niet meer) of Revoke in de lijst met API-sleutels.

Je eerste aanvraag

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

"Gebruik model 'auto' om de router per verzoek het beste model te laten kiezen, of een model-ID die is ingeschakeld voor je faciliteit."

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

Modellen opvragen

GET /v1/models geeft elk model terug dat voor je faciliteit is ingeschakeld (met inachtneming van een eventuele modelbeperking per sleutel). Modellen opvragen werkt ook wanneer je saldo nul is, zodat integraties de catalogus kunnen verkennen voordat het account van tegoed is voorzien.

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

Gebruik een van de teruggegeven model-ID's in het veld model, of gebruik auto om de Auto Router per aanvraag het beste model te laten kiezen.

Streaming

Streaming werkt op de standaardmanier van OpenAI: stel "stream": true in en verwerk de server-sent event-chunks. De SDK-voorbeelden hierboven ondersteunen dit via hun gebruikelijke streaming-API's.

Terugvalmodellen

Je kunt een geordende reeks terugvalmodellen opgeven, zodat de aanvraag bij een mislukking van het primaire model opnieuw wordt geprobeerd met het volgende model:

models: ["model-a", "model-b", "model-c"]: een volledige geordende lijst; het eerste item is het primaire model.
of model: "model-a" plus fallbacks: ["model-b", "model-c"]: reservemodellen die na het primaire model worden geprobeerd.

Terugvalkandidaten worden gefilterd op de modellen die je sleutel mag gebruiken.

Foutreacties

Fouten gebruiken de standaardfoutstructuur van OpenAI: { "error": { "message", "type", "code" } }.

HTTP	`type`	`code`	Betekenis	Wat je doet
401	`invalid_request_error`	`invalid_api_key`	Ontbrekende API-sleutel of ongeldige inloggegevens van een verbonden service.	Controleer de header `Authorization: Bearer`.
401	`invalid_request_error`	—	Onbekende of ingetrokken API-sleutel ("Invalid API key").	Activeer de sleutel opnieuw of maak een nieuwe aan.
402	`insufficient_quota`	`insufficient_credits`	Prepaid saldo op (of, bij verbonden services, de faciliteit is niet ingeschakeld).	Vul aan (of schakel automatisch aanvullen in).
402	`insufficient_quota`	`budget_exceeded`	Een uitgavenlimiet is bereikt: voor de hele faciliteit, of op deze sleutel of verbonden service. De melding vermeldt om welke periode het gaat en, bij limieten per dag/maand, precies wanneer die wordt gereset in de tijdzone van de faciliteit. De body bevat ook de velden `window`, `resetsAt`, `timezone` en `docsUrl`.	Wacht op de reset, verhoog de limiet of reset de harde limiet.
403	`invalid_request_error`	—	"Model Router is not enabled for this facility" (API-sleutels), of "Facility has no provisioned inference key" (de sleutel heeft geen onderliggende inferentiesleutel).	Schakel Model Router in voor de faciliteit (zie Aan de slag). Is de module al ingeschakeld, roteer dan de sleutel of maak een nieuwe aan.
403	`invalid_request_error`	`content_policy_violation`	"Request blocked by content policy": een inhoudsfilter in de blokkeermodus of het schild tegen promptinjectie kwam overeen met de prompt.	Controleer de instellingen van Guardrails.
429	—	—	Snelheidslimiet overschreden (aanvragen/min of tokens/min ingesteld op je sleutel).	Wacht even en probeer het opnieuw; verhoog zo nodig de snelheidslimieten van de sleutel.
502	`server_error`	—	De onderliggende inferentieservice is tijdelijk niet beschikbaar.	Probeer het opnieuw met een oplopende wachttijd.

Beide 402-fouten bevatten een veld docsUrl, en hun melding eindigt met een link naar de documentatie van Performance Hub.

Handel 402 netjes af in je integratie: het is het verwachte signaal wanneer een account geen tegoed meer heeft of een budget bereikt, geen storing.

Goede werkwijzen

Eén sleutel per systeem. Geef elke integratie een eigen sleutel met een label, zodat het gebruik in Activity en Logs kan worden toegewezen en je bij een lek maar één sleutel hoeft te roteren.
Begrens elke sleutel. Stel uitgavenlimieten en snelheidslimieten per sleutel in die bij het systeem passen; zie API-sleutels.
Kies bij voorkeur auto, tenzij je een specifiek model nodig hebt: je krijgt snelle, goedkope modellen voor eenvoudig werk en de sterkste modellen alleen wanneer een taak daarom vraagt.
Houd het tabblad Logs in de gaten tijdens de integratie: elke aanvraag verschijnt met de status, tokens en kosten, waardoor je integratieproblemen snel kunt opsporen. Zie Activiteit en logboeken.