In brief
- Use the OpenAI SDK with a different base URL instead of maintaining provider-specific clients.
- Discover model IDs from the live models endpoint rather than hard-coding a stale catalog.
- Keep provider choice in configuration so a model change does not become an application rewrite.
Why one interface changes the engineering work
Teams often begin with one model and eventually need a second: a faster model for interactive work, a stronger reasoner for difficult tasks, or a different provider for resilience. The expensive part is rarely the first API call. It is the provider-specific authentication, request shapes, streaming behavior, observability, and billing that accumulate around it.
An OpenAI-compatible interface keeps the application boundary stable. Your product still needs model-aware evaluation, but it no longer needs a separate transport layer for every provider family.
Compatibility reduces integration work; it does not make different models behave identically. Evaluate outputs before changing production defaults.
Create the client
Install the official OpenAI SDK, keep the setup key in an environment variable, and point the client at Xpersona's versioned API base. The rest of the request uses the familiar chat completions shape.
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.XPERSONA_API_KEY,
baseURL: "https://www.xpersona.co/v1",
});
const response = await client.chat.completions.create({
model: "gpt-5.6-terra",
messages: [{ role: "user", content: "Review this pull request." }],
});
console.log(response.choices[0]?.message.content);Discover the live catalog before choosing a default
Model catalogs change. Query the public models endpoint during setup or through your deployment tooling, then validate that the configured model exists before serving traffic.
- Choose a stable alias when continuity matters.
- Choose a versioned ID when exact behavior matters more than automatic upgrades.
- Record the resolved model ID with each response for reproducibility.
curl https://www.xpersona.co/v1/models \
-H "Authorization: Bearer $XPERSONA_API_KEY"The production checklist
A successful local request is the beginning, not the end. Production integrations need timeouts, bounded retries, usage visibility, and an explicit fallback policy.
| Control | Minimum behavior | Why it matters |
|---|---|---|
| Timeout | Bound every request | Prevents stalled workers |
| Retry | Retry transient failures only | Avoids duplicate cost and traffic storms |
| Logging | Model, latency, tokens, status | Makes comparisons and incidents explainable |
| Fallback | Named and tested | Prevents silent behavior changes |
Make model choice an evaluation decision
Once transport is shared, compare candidates against the same task set. Score quality, latency, and cost separately. The cheapest model is not economical if it creates rework; the strongest model is not efficient if a smaller one already clears the quality bar.
Frequently asked
Questions, answered plainly.
Can I use the official OpenAI SDK with Xpersona?+
Yes. Set the Xpersona base URL and use your Xpersona setup key; requests keep the OpenAI-compatible shape.
Do GPT, Claude, and Gemini use the same model ID?+
No. The request shape is shared, while each catalog model keeps its own ID. Query the live models endpoint for current IDs.
Should I automatically fall back between providers?+
Only with an explicit, evaluated policy. A transport fallback can change output behavior, so record it and test it against your quality requirements.
Sources and next paths