애플리케이션 연결

이 페이지의 내용

Model Router 엔드포인트는 OpenAI 호환입니다. OpenAI SDK, 프레임워크 또는 BYOK를 지원하는 도구가 Performance Hub 기본 URL을 가리키도록 설정하고 API 키 중 하나로 인증하면 바로 작동합니다. 이 페이지는 통합 빠른 시작 가이드입니다.

필요한 항목

API 키. 키를 생성하려면 Organisation Administrator여야 합니다. Settings(톱니바퀴) → Service Access & API Keys → Create key에서 생성합니다. 키는 phk_로 시작하며 비밀 키는 한 번만 표시됩니다. API 키를 참조하십시오.
기본 URL. 같은 설정 페이지의 Connecting to the API 카드에 표시됩니다.

Connecting to the API 카드

그림 1: Connecting to the API: 기본 URL과 복사하여 붙여 넣을 수 있는 예제 요청

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

사용 환경의 정확한 기본 URL은 항상 모듈에 표시됩니다. 이 페이지가 아닌 모듈에서 복사하십시오.

인증

모든 요청에 키를 bearer 토큰으로 보냅니다.

Authorization: Bearer phk_your_key_here

키를 비밀번호처럼 취급하십시오. 키가 유출된 경우 API 키 목록에서 키를 Rotate하거나(새 비밀 키가 발급되고 이전 비밀 키는 즉시 작동을 멈춤) Revoke하십시오.

첫 번째 요청

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

"'auto' 모델을 사용하여 라우터가 요청당 가장 적절한 모델을 선택하도록 하거나, 시설에서 활성화된 모델 ID를 사용하세요."

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

모델 목록 조회

GET /v1/models는 시설에서 활성화된 모든 모델을 반환합니다(키별 모델 제한이 있으면 이를 따름). 모델 목록 조회는 잔액이 0일 때도 작동하므로, 계정에 자금이 충전되기 전에도 통합에서 카탈로그를 확인할 수 있습니다.

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

반환된 모델 ID를 model 필드에 사용하거나, auto를 사용하여 Auto Router가 요청별로 가장 적합한 모델을 선택하도록 하십시오.

스트리밍

스트리밍은 표준 OpenAI 방식으로 작동합니다. "stream": true를 설정하고 서버 전송 이벤트 청크를 처리하십시오. 위의 SDK 예제는 일반적인 스트리밍 API를 통해 이를 지원합니다.

모델 대체

기본 모델이 실패하면 다음 모델로 요청을 재시도하도록 순서가 지정된 대체 체인을 제공할 수 있습니다.

models: ["model-a", "model-b", "model-c"]: 순서가 지정된 전체 목록이며, 첫 번째 항목이 기본 모델입니다.
또는 model: "model-a"와 fallbacks: ["model-b", "model-c"]: 기본 모델 다음에 시도하는 백업 모델입니다.

대체 후보는 키에 사용이 허용된 모델로 필터링됩니다.

오류 응답

오류는 표준 OpenAI 오류 형식을 사용합니다: { "error": { "message", "type", "code" } }.

HTTP	`type`	`code`	의미	조치
401	`invalid_request_error`	`invalid_api_key`	API 키가 없거나 연결된 서비스 자격 증명이 잘못되었습니다.	`Authorization: Bearer` 헤더를 확인하십시오.
401	`invalid_request_error`	—	알 수 없거나 해지된 API 키입니다("Invalid API key").	키를 다시 활성화하거나 새 키를 생성하십시오.
402	`insufficient_quota`	`insufficient_credits`	선불 잔액이 소진되었습니다(연결된 서비스의 경우 시설이 활성화되지 않음).	충전하십시오(또는 자동 충전을 활성화하십시오).
402	`insufficient_quota`	`budget_exceeded`	시설 전체 또는 이 키나 연결된 서비스의 지출 한도에 도달했습니다. 메시지에 어떤 기간인지, 그리고 일별/월별 한도의 경우 시설 시간대 기준으로 정확히 언제 초기화되는지 표시됩니다. 본문에는 `window`, `resetsAt`, `timezone`, `docsUrl` 필드도 포함됩니다.	초기화를 기다리거나, 한도를 높이거나, 하드 캡을 초기화하십시오.
403	`invalid_request_error`	—	"Model Router is not enabled for this facility"(API 키) 또는 "Facility has no provisioned inference key"(키에 연결된 추론 키가 없음)입니다.	시설에서 Model Router를 활성화하십시오(시작하기 참조). 이미 활성화되어 있다면 키를 순환하거나 새 키를 생성하십시오.
403	`invalid_request_error`	`content_policy_violation`	"Request blocked by content policy": 차단 모드 콘텐츠 필터 또는 프롬프트 인젝션 차단이 프롬프트와 일치했습니다.	Guardrails 설정을 검토하십시오.
429	—	—	속도 제한(키에 설정된 분당 요청 수 또는 분당 토큰 수)을 초과했습니다.	잠시 기다렸다가 재시도하십시오. 필요하면 키의 속도 제한을 높이십시오.
502	`server_error`	—	업스트림 추론 서비스를 일시적으로 사용할 수 없습니다.	백오프를 적용하여 재시도하십시오.

두 402 오류 모두 docsUrl 필드를 포함하며, 메시지 끝에 Performance Hub 문서 링크가 있습니다.

통합에서 402를 적절히 처리하십시오. 402는 오류가 아니라 계정의 크레딧이 소진되었거나 예산에 도달했을 때 예상되는 신호입니다.

권장 사항

시스템당 키 하나. 각 통합에 레이블이 지정된 고유한 키를 부여하면 Activity와 Logs에서 사용량을 구분할 수 있고, 유출 시 키 하나만 순환하면 됩니다.
각 키 제한. 시스템에 맞는 키별 지출 한도와 속도 제한을 설정하십시오. API 키를 참조하십시오.
특정 모델이 필요하지 않다면 auto 사용을 권장합니다. 간단한 작업에는 빠르고 저렴한 모델이, 작업에 필요할 때만 가장 강력한 모델이 사용됩니다.
통합 중에는 Logs 탭을 확인하십시오. 모든 요청이 상태, 토큰, 비용과 함께 표시되므로 통합 문제를 빠르게 디버깅할 수 있습니다. 활동 및 로그를 참조하십시오.