Conectar tu aplicación

El endpoint de Model Router es compatible con OpenAI: dirige cualquier SDK de OpenAI, framework o herramienta compatible con BYOK a la URL base de Performance Hub, autentícate con una de tus claves de API y funcionará sin más. Esta página es la guía de inicio rápido de la integración.

Lo que necesitas

1. Una clave de API. Para crearla, debes ser Organisation Administrator. Créala en Settings (engranaje) → Service Access & API Keys → Create key. Las claves empiezan por phk_ y el secreto se muestra una sola vez. Consulta Claves de API.
2. La URL base. Aparece en la tarjeta Connecting to the API de la misma página de configuración:

Figura 1: Connecting to the API: la URL base y una solicitud de ejemplo lista para copiar y pegar

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

La URL base exacta de tu entorno siempre se muestra en el módulo: cópiala desde allí y no desde esta página.

Autenticación

Envía tu clave como token de portador en cada solicitud:

Authorization: Bearer phk_your_key_here

Trata la clave como una contraseña. Si se filtra, usa Rotate (se emite un nuevo secreto y el anterior deja de funcionar de inmediato) o Revoke desde la lista de claves de API.

Tu primera solicitud

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

"Utiliza el modelo 'auto' para permitir que el enrutador elija el mejor modelo por solicitud, o cualquier ID de modelo habilitado para tu instalación."

Python (SDK de OpenAI)

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 (SDK de OpenAI)

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

Listar los modelos

GET /v1/models devuelve todos los modelos habilitados para tu instalación (respetando cualquier restricción de modelos por clave). La lista de modelos funciona incluso cuando tu saldo es cero, para que las integraciones puedan descubrir el catálogo antes de que la cuenta tenga fondos.

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

Usa cualquier ID de modelo devuelto en el campo model, o usa auto para que el Auto Router elija el mejor modelo para cada solicitud.

Streaming

El streaming funciona de la forma estándar de OpenAI: establece "stream": true y consume los fragmentos de eventos enviados por el servidor. Los ejemplos de SDK anteriores lo admiten mediante sus API de streaming habituales.

Modelos de respaldo

Puedes indicar una cadena ordenada de modelos de respaldo para que, si falla el modelo principal, la solicitud se reintente con el siguiente:

• models: ["model-a", "model-b", "model-c"]: una lista ordenada completa; la primera entrada es el modelo principal.
• o model: "model-a" junto con fallbacks: ["model-b", "model-c"]: modelos de respaldo que se prueban después del principal.

Los candidatos de respaldo se filtran según los modelos que tu clave tiene permitido usar.

Respuestas de error

Los errores usan el formato de error estándar de OpenAI: { "error": { "message", "type", "code" } }.

Ambos errores 402 incluyen un campo docsUrl, y su mensaje termina con un enlace a la documentación de Performance Hub.

Gestiona el error 402 de forma controlada en tu integración: es la señal esperada cuando una cuenta se queda sin crédito o alcanza un presupuesto, no una falla.

Prácticas recomendadas

• Una clave por sistema. Asigna a cada integración su propia clave con etiqueta para que el uso se pueda atribuir en Activity y Logs, y para que una filtración solo obligue a rotar una clave.
• Acota cada clave. Establece topes de gasto y límites de frecuencia por clave adecuados para el sistema; consulta Claves de API.
• Prefiere auto, salvo que necesites un modelo específico: obtienes modelos rápidos y económicos para el trabajo sencillo, y los modelos más potentes solo cuando una tarea los necesita.
• Revisa la pestaña Logs durante la integración: cada solicitud aparece con su estado, sus tokens y su costo, lo que agiliza la depuración de problemas de integración. Consulta Actividad y registros.