If you've worked with multiple AI APIs, you know the pain: different auth flows, different SDKs, different billing dashboards, different rate limits. You end up with a providers/ folder full of wrapper code just to normalize the responses.
Onlist solves this by putting 40+ AI providers behind a single OpenAI-compatible endpoint. One API key, one billing account, same chat.completions.create() call you already know. We just shipped official SDKs for Python and JavaScript/TypeScript, so I wanted to walk through what they look like in practice.
The 30-Second Setup
Python:
pip install onlist
from onlist import Onlist
client = Onlist() # reads ONLIST_API_KEY from env
response = client.chat.completions.create(
model="openai/chatgpt-5.5",
messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)
TypeScript:
npm install @onlist/sdk
import { Onlist } from "@onlist/sdk";
const client = new Onlist();
const response = await client.chat.completions.create({
model: "openai/chatgpt-5.5",
messages: [{ role: "user", content: "Hello!" }],
});
console.log(response.choices[0].message.content);
That's it. No base URL to configure, no special headers to set. If you've used the openai package before, you already know how to use this.
Why Not Just Use the OpenAI SDK Directly?
You absolutely can. Onlist is fully OpenAI-compatible, so this works fine:
from openai import OpenAI
client = OpenAI(
base_url="https://onlist.io/v1",
api_key="your-key",
)
The SDK adds three things on top of that:
Default configuration. Nobase_urlto remember. TheONLIST_API_KEYenv var just works.
Marketplace API. A.marketplacenamespace for browsing models and providers programmatically.
Proper User-Agent. Helps us debug issues when you reach out for support.
If you're already using OpenAI or OpenRouter, switching takes one line:
- from openai import OpenAI
+ from onlist import Onlist
- client = OpenAI(api_key="sk-...")
+ client = Onlist(api_key="sk-...")
Every method call stays exactly the same.
Provider Routing
This is where things get interesting. When you call openai/chatgpt-5.5 on Onlist, there might be multiple upstream providers serving that model at different prices. You can control which one handles your request:
response = client.chat.completions.create(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "Summarize this document"}],
extra_body={
"provider": {
"sort": "price", # cheapest provider first
"allow_fallbacks": True, # try another if the first fails
}
},
)
You can also pin to a specific provider if you've found one you trust:
extra_body={"provider": {"only": ["alice-ai"]}}
This is passed through the standard OpenAI extra_body parameter, so no special SDK features needed.
Browsing the Marketplace
The .marketplace namespace lets you explore what's available:
# What models are out there?
models = client.marketplace.models.list(limit=5)
for m in models.data:
print(m.id)
# Who's selling ChatGPT 5.5?
detail = client.marketplace.models.get("openai/chatgpt-5.5")
for offer in detail.providers:
print(f" {offer.name}")
The same API is available in the TypeScript SDK with identical method names.
Streaming
Works exactly like the OpenAI SDK:
stream = client.chat.completions.create(
model="openai/chatgpt-5.5",
messages=[{"role": "user", "content": "Write a haiku about code"}],
stream=True,
)
for chunk in stream:
content = chunk.choices[0].delta.content
if content:
print(content, end="", flush=True)
Vercel AI SDK
If you're using the Vercel AI SDK, we also have a provider package:
npm install @onlist/ai-sdk-provider ai
import { createOnlist } from "@onlist/ai-sdk-provider";
import { generateText } from "ai";
const onlist = createOnlist();
const { text } = await generateText({
model: onlist("openai/chatgpt-5.5"),
prompt: "Explain quantum computing briefly.",
});
It's built on top of @ai-sdk/openai-compatible, so all the AI SDK features (streaming, tool calling, structured outputs) work out of the box.
What Onlist Actually Is
Onlist is an open marketplace where independent API providers list their services. Think of it like a comparison shopping site for AI APIs. Providers compete on price and reliability, buyers get transparent pricing and the ability to switch providers without changing code.
The SDKs are all MIT licensed and available on GitHub.