---
title: Providers
description: Configure providers, models, clients, and provider options.
type: guide
summary: Create models, configure credentials, use custom clients, list models, and check connections.
---

# Providers



Providers own credentials, base URLs, headers, clients, and adapter dispatch.
Models are lightweight references that point at a provider.

## Create a model

Use `ai.get_model` to create a model. If you omit the provider prefix, the model
will use AI Gateway as a provider:

```python
model = ai.get_model("anthropic/claude-sonnet-4")
```

You can also set `AI_SDK_DEFAULT_MODEL` and call `get_model` without arguments:

```bash
export AI_SDK_DEFAULT_MODEL="anthropic/claude-sonnet-4"
```

```python
model = ai.get_model()
```

Use a `provider:model` ID when you want to target a specific provider directly:

```python
model = ai.get_model("openai:gpt-5")
```

## Configure credentials

Providers read their provider-specific keys:

```bash title="Terminal"
export AI_GATEWAY_API_KEY="your_access_token_here"
export OPENAI_API_KEY="your_access_token_here"
export ANTHROPIC_API_KEY="your_access_token_here"
```

## Use an explicit provider

If your application requires a provider with custom configuration,
use `get_provider` to get a `Provider` instance:

```python
provider = ai.get_provider(
    "openai",
    base_url="http://localhost:1234/v1",
    api_key="your_access_token_here",
)

model = ai.Model(id="local-model", provider=provider)
```

You can pass an upstream client to the provider:

```python
import httpx
import ai


client = httpx.AsyncClient(timeout=30)
provider = ai.get_provider(
    "openai",
    base_url="http://localhost:1234/v1",
    api_key="your_access_token_here",
    client=client,
)
model = ai.Model(id="local-model", provider=provider)
```

Close explicit providers when your app shuts down:

```python
await provider.aclose()
```

## List models

Use the provider API when you need model IDs from the remote service:

```python
provider = ai.get_provider("anthropic")
models = await provider.list_models()
print(models[:5])
```

## Check a connection

Use `ai.probe` to check credentials and model availability without generating
tokens:

```python
model = ai.get_model("gateway:anthropic/claude-sonnet-4")

try:
    await ai.probe(model)
except ai.ProviderError as exc:
    print(f"Provider is unavailable: {exc}")
```

## Provider-specific params

Pass request-scoped provider options with `params`:

```python
params = ai.InferenceRequestParams(
    extra_body={
        "providerOptions": {
            "gateway": {"sort": "cost"},
            "anthropic": {"speed": "fast"},
        }
    }
)

async with ai.stream(model, messages, params=params) as stream:
    async for event in stream:
        if isinstance(event, ai.events.TextDelta):
            print(event.chunk, end="", flush=True)
```

Provider options pass through to the selected provider. Check the provider
documentation for supported fields.

## Add a provider

Custom providers subclass `ai.Provider`. A provider owns configuration,
clients, model listing, connection checks, and wire translation through its
protocol:

```python
class AcmeProvider(ai.Provider[AcmeClient]):
    handles = ("acme",)

    async def list_models(self) -> list[str]:
        ...

    async def probe(self, model: ai.Model) -> None:
        ...
```

Most applications only need `ai.get_provider` and `ai.Model`. Add a provider
when you need a new upstream API or custom wire protocol.


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)