DEV Community

Cover image for Access 40+ AI Providers with One API Key: Building with the Onlist SDK
alan
alan

Posted on

Access 40+ AI Providers with One API Key: Building with the Onlist SDK

#openai #typescript #python #ai

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
Enter fullscreen mode Exit fullscreen mode 
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)
Enter fullscreen mode Exit fullscreen mode

TypeScript:

npm install @onlist/sdk
Enter fullscreen mode Exit fullscreen mode 
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);
Enter fullscreen mode Exit fullscreen mode

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",
)
Enter fullscreen mode Exit fullscreen mode

The SDK adds three things on top of that:

  1. Default configuration. No base_url to remember. The ONLIST_API_KEY env var just works.
  2. Marketplace API. A .marketplace namespace for browsing models and providers programmatically.
  3. 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-...")
Enter fullscreen mode Exit fullscreen mode

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
        }
    },
)
Enter fullscreen mode Exit fullscreen mode

You can also pin to a specific provider if you've found one you trust:

extra_body={"provider": {"only": ["alice-ai"]}}
Enter fullscreen mode Exit fullscreen mode

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}")
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

Vercel AI SDK

If you're using the Vercel AI SDK, we also have a provider package:

npm install @onlist/ai-sdk-provider ai
Enter fullscreen mode Exit fullscreen mode 
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.",
});
Enter fullscreen mode Exit fullscreen mode

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.

Links

Top comments (0)