Skip to content

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 (including stream_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-provider to see which served it, or pin providers with the provider field (pass it via extra_body in 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.