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

alan — Sat, 20 Jun 2026 12:15:29 +0000

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. No base_url to remember. The ONLIST_API_KEY env var just works.
Marketplace API. A .marketplace namespace 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.

DEV Community: alan