Uygulamanızı bağlama

Model Router uç noktası OpenAI uyumludur: herhangi bir OpenAI SDK'sını, çerçevesini veya BYOK destekli aracı Performance Hub temel URL'sine yönlendirin, API anahtarlarınızdan biriyle kimlik doğrulayın; hepsi bu kadar. Bu sayfa entegrasyon için hızlı başlangıç kılavuzudur.

Gerekenler

1. Bir API anahtarı. Anahtar oluşturmak için Organisation Administrator olmanız gerekir. Anahtarı Settings (dişli) → Service Access & API Keys → Create key altında oluşturun. Anahtarlar phk_ ile başlar ve gizli anahtar yalnızca bir kez gösterilir. Bkz. API anahtarları.
2. Temel URL. Aynı ayarlar sayfasındaki Connecting to the API kartında gösterilir:

Şekil 1: Connecting to the API: temel URL ve kopyalayıp yapıştırabileceğiniz örnek bir istek

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

Ortamınıza ait tam temel URL her zaman modülde gösterilir; bu sayfadan değil, oradan kopyalayın.

Kimlik doğrulama

Anahtarınızı her istekte bir bearer token olarak gönderin:

Authorization: Bearer phk_your_key_here

Anahtara parola gibi davranın. Sızarsa API anahtarları listesinden Rotate ile döndürün (yeni bir gizli anahtar oluşturulur ve eskisi hemen çalışmayı durdurur) veya Revoke ile iptal edin.

İlk isteğiniz

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

"Router'ın her istek için en iyi modeli seçmesini sağlamak amacıyla 'auto' modelini kullanın veya tesisiniz için etkinleştirilmiş herhangi bir model ID'sini belirtin."

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

Modelleri listeleme

GET /v1/models, tesisiniz için etkinleştirilmiş tüm modelleri döndürür (anahtar bazındaki model kısıtlamalarına uyarak). Model listeleme bakiyeniz sıfır olduğunda bile çalışır; böylece entegrasyonlar, hesaba bakiye yüklenmeden önce kataloğu keşfedebilir.

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

model alanında döndürülen herhangi bir model kimliğini kullanın veya Auto Router'ın her istek için en iyi modeli seçmesine izin vermek için auto kullanın.

Akış

Akış, standart OpenAI yöntemiyle çalışır: "stream": true ayarlayın ve sunucu tarafından gönderilen olay (server-sent event) parçalarını işleyin. Yukarıdaki SDK örnekleri, olağan akış API'leri aracılığıyla bunu destekler.

Model yedekleri

Birincil model başarısız olursa isteğin bir sonrakinde yeniden denenmesi için sıralı bir yedek zinciri belirtebilirsiniz:

• models: ["model-a", "model-b", "model-c"]: sıralı tam liste; ilk öğe birincil modeldir.
• veya model: "model-a" ile birlikte fallbacks: ["model-b", "model-c"]: birincil modelden sonra denenen yedekler.

Yedek adaylar, anahtarınızın kullanmasına izin verilen modellere göre filtrelenir.

Hata yanıtları

Hatalar standart OpenAI hata zarfını kullanır: { "error": { "message", "type", "code" } }.

Her iki 402 hatası da bir docsUrl alanı içerir ve mesajları Performance Hub belgelerine bir bağlantıyla biter.

Entegrasyonunuzda 402 hatasını düzgün bir şekilde işleyin: bu bir arıza değil, bir hesabın kredisi bittiğinde veya bir bütçeye ulaştığında beklenen sinyaldir.

İyi uygulamalar

• Her sistem için bir anahtar. Kullanımın Activity ve Logs bölümlerinde ilişkilendirilebilmesi ve bir sızıntıda yalnızca tek bir anahtarın döndürülmesinin yeterli olması için her entegrasyona etiketli kendi anahtarını verin.
• Her anahtarı sınırlandırın. Sisteme uygun anahtar bazında harcama üst sınırları ve hız sınırları belirleyin; bkz. API anahtarları.
• Belirli bir modele ihtiyacınız yoksa auto tercih edin: basit işler için hızlı ve ucuz modeller, yalnızca bir görev gerektirdiğinde en güçlü modeller kullanılır.
• Entegrasyon sırasında Logs sekmesini izleyin: her istek durumu, token'ları ve maliyetiyle birlikte görünür; bu da entegrasyon sorunlarının hızla ayıklanmasını sağlar. Bkz. Etkinlik ve günlükler.