Appearance
Migrating from the OpenAI SDK
Change two things: the base URL and the key.
ts
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.usefully.info/v1",
apiKey: process.env.USEFULLY_API_KEY,
});python
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.usefully.info/v1", api_key=os.environ["USEFULLY_API_KEY"])Then use model IDs from the catalog (GET /v1/models). Today that's Anthropic's Claude models; OpenAI's models aren't offered yet. Your existing OpenAI SDK code works unchanged apart from the model name:
ts
await client.chat.completions.create({ model: "anthropic/claude-sonnet-5-5", messages });
await client.chat.completions.create({ model: "google/gemini-2.5-flash", messages });What works
chat.completions.create, streaming (includingstream_options.include_usage), tools and tool-call streaming, JSON mode, vision inputs where the model supports them.embeddings.create, including the SDK's default base64 encoding.models.list.- Other OpenAI parameters (
seed,logit_bias, …) are passed through to OpenAI-compatible providers.
What's different
- Requests can fall back to another provider; check
x-usefully-providerto see which served it, or pin providers with theproviderfield (pass it viaextra_bodyin Python, or directly in TypeScript). - Errors use Usefully's error format, which the OpenAI SDK maps onto its own exception classes by HTTP status.
- Endpoints Usefully doesn't serve (Assistants, Files, Fine-tuning, Images, Audio) return 404.