Kết nối ứng dụng của bạn

Endpoint Model Router tương thích với OpenAI — chỉ cần trỏ bất kỳ SDK, framework hoặc công cụ hỗ trợ BYOK nào của OpenAI đến URL cơ sở của Performance Hub, xác thực bằng một trong các khóa API của bạn, và mọi thứ sẽ hoạt động. Trang này là hướng dẫn nhanh về tích hợp.

Những gì bạn cần

1. Một khóa API. Bạn cần là Organisation Administrator để tạo khóa. Tạo khóa trong Settings (bánh răng) → Service Access & API Keys → Create key. Khóa bắt đầu bằng phk_ và khóa bí mật chỉ được hiển thị một lần. Xem Khóa API.
2. URL cơ sở. Được hiển thị trong thẻ Connecting to the API trên cùng trang cài đặt:

Hình 1: Connecting to the API: URL cơ sở và một yêu cầu mẫu để sao chép và dán

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

URL cơ sở chính xác cho môi trường của bạn luôn được hiển thị trong mô-đun — hãy sao chép từ đó thay vì từ trang này.

Xác thực

Gửi khóa của bạn dưới dạng bearer token trong mọi yêu cầu:

Authorization: Bearer phk_your_key_here

Hãy bảo vệ khóa như mật khẩu. Nếu khóa bị rò rỉ, hãy Rotate khóa (khóa bí mật mới được cấp và khóa cũ ngừng hoạt động ngay lập tức) hoặc Revoke khóa từ danh sách khóa API.

Yêu cầu đầu tiên của bạn

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

"Sử dụng model 'auto' để bộ định tuyến tự động chọn model tốt nhất cho mỗi yêu cầu, hoặc bất kỳ ID model nào đã được bật cho cơ sở của bạn."

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

Liệt kê mô hình

GET /v1/models trả về mọi mô hình đã được bật cho cơ sở của bạn (tuân theo mọi giới hạn mô hình theo từng khóa). Việc liệt kê mô hình vẫn hoạt động ngay cả khi số dư của bạn bằng 0, nhờ đó các tích hợp có thể khám phá danh mục trước khi tài khoản được nạp tiền.

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

Sử dụng bất kỳ ID mô hình nào được trả về trong trường model, hoặc dùng auto để Auto Router chọn mô hình tốt nhất cho mỗi yêu cầu.

Truyền phát

Truyền phát hoạt động theo cách tiêu chuẩn của OpenAI — đặt "stream": true và xử lý các đoạn sự kiện do máy chủ gửi. Các ví dụ SDK ở trên hỗ trợ truyền phát thông qua các API truyền phát thông thường của chúng.

Mô hình dự phòng

Bạn có thể cung cấp chuỗi dự phòng theo thứ tự để nếu mô hình chính gặp lỗi, yêu cầu sẽ được thử lại trên mô hình tiếp theo:

• models: ["model-a", "model-b", "model-c"] — danh sách đầy đủ theo thứ tự; mục đầu tiên là mô hình chính.
• hoặc model: "model-a" cùng fallbacks: ["model-b", "model-c"] — các mô hình dự phòng được thử sau mô hình chính.

Các mô hình dự phòng được lọc theo những mô hình mà khóa của bạn được phép sử dụng.

Phản hồi lỗi

Lỗi sử dụng cấu trúc lỗi tiêu chuẩn của OpenAI: { "error": { "message", "type", "code" } }.

Cả hai lỗi 402 đều có trường docsUrl, và thông báo của chúng kết thúc bằng liên kết đến tài liệu Performance Hub.

Hãy xử lý lỗi 402 một cách hợp lý trong tích hợp của bạn — đây là tín hiệu dự kiến khi tài khoản hết tín dụng hoặc đạt ngân sách, không phải là lỗi hệ thống.

Thực tiễn tốt

• Mỗi hệ thống một khóa. Cấp cho mỗi tích hợp một khóa có nhãn riêng để mức sử dụng có thể được phân bổ trong Activity và Logs, và khi rò rỉ chỉ cần xoay vòng một khóa.
• Giới hạn từng khóa. Đặt mức trần chi tiêu và giới hạn tốc độ theo từng khóa phù hợp với hệ thống; xem Khóa API.
• Ưu tiên auto trừ khi bạn cần một mô hình cụ thể — bạn sẽ có các mô hình nhanh, rẻ cho công việc đơn giản và chỉ dùng các mô hình mạnh nhất khi tác vụ cần đến.
• Theo dõi tab Logs trong quá trình tích hợp — mọi yêu cầu đều xuất hiện kèm trạng thái, token và chi phí, giúp gỡ lỗi tích hợp nhanh chóng. Xem Hoạt động và nhật ký.