Como conectar o seu aplicativo

O endpoint do Model Router é compatível com a OpenAI — aponte qualquer SDK, framework ou ferramenta com suporte a BYOK da OpenAI para o URL base do Performance Hub, autentique-se com uma das suas chaves de API e pronto, tudo funciona. Esta página é o guia de início rápido da integração.

O que você precisa

1. Uma chave de API. Você precisa ser um Organisation Administrator para criar uma. Crie-a em Settings (engrenagem) → Service Access & API Keys → Create key. As chaves começam com phk_, e o segredo é exibido somente uma vez. Consulte Chaves de API.
2. O URL base. Exibido no cartão Connecting to the API, na mesma página de configurações:

Figura 1: Connecting to the API: o URL base e um exemplo de solicitação para copiar e colar

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

O URL base exato do seu ambiente é sempre exibido no módulo — copie-o de lá, e não desta página.

Autenticação

Envie a sua chave como um token bearer em todas as solicitações:

Authorization: Bearer phk_your_key_here

Trate a chave como uma senha. Se ela vazar, use Rotate (um novo segredo é emitido e o antigo deixa de funcionar imediatamente) ou Revoke na lista de chaves de API.

A sua primeira solicitação

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

"Use o model 'auto' para permitir que o roteador escolha o melhor model por solicitação, ou qualquer ID de model habilitado para a sua Instalação."

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

Listando modelos

GET /v1/models retorna todos os modelos habilitados na sua instalação (respeitando eventuais restrições de modelos por chave). A listagem de modelos funciona mesmo quando o seu saldo é zero, para que as integrações possam descobrir o catálogo antes de a conta receber fundos.

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

Use qualquer ID de modelo retornado no campo model ou use auto para deixar o Auto Router escolher o melhor modelo para cada solicitação.

Streaming

O streaming funciona da forma padrão da OpenAI — defina "stream": true e consuma os blocos de server-sent events. Os exemplos de SDK acima oferecem suporte a isso por meio das APIs de streaming habituais.

Modelos de fallback

Você pode fornecer uma cadeia ordenada de fallback para que, se o modelo principal falhar, a solicitação seja repetida no próximo:

• models: ["model-a", "model-b", "model-c"] — uma lista ordenada completa; a primeira entrada é o modelo principal.
• ou model: "model-a" mais fallbacks: ["model-b", "model-c"] — modelos de reserva tentados depois do principal.

Os candidatos de fallback são filtrados de acordo com os modelos que a sua chave tem permissão para usar.

Respostas de erro

Os erros usam o envelope de erro padrão da OpenAI: { "error": { "message", "type", "code" } }.

Os dois erros 402 incluem um campo docsUrl, e a mensagem deles termina com um link para a documentação do Performance Hub.

Trate o erro 402 de forma adequada na sua integração — ele é o sinal esperado quando uma conta fica sem crédito ou atinge um orçamento, não uma falha.

Boas práticas

• Uma chave por sistema. Dê a cada integração a sua própria chave com rótulo, para que o uso possa ser atribuído em Activity e Logs e um vazamento exija rotacionar somente uma chave.
• Limite cada chave. Defina tetos de gasto e limites de taxa por chave adequados ao sistema; consulte Chaves de API.
• Prefira auto, a menos que você precise de um modelo específico — você obtém modelos rápidos e baratos para tarefas simples e os modelos mais avançados somente quando uma tarefa precisa deles.
• Acompanhe a guia Logs durante a integração — cada solicitação aparece com o seu status, os tokens e o custo, o que torna rápida a depuração de problemas de integração. Consulte Atividade e logs.