> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Azure OpenAI (gateway)

> Route Azure OpenAI code through the Respan gateway by switching to the OpenAI client.

To route Azure OpenAI through the Respan gateway, switch from the `AzureOpenAI` client to the standard `OpenAI` client. It is a small, mechanical change: the request and response shapes are identical (both classes live in the same `openai` package), so only the constructor changes.

> **Warning**
>
> The stock `AzureOpenAI` client **cannot** point at the Respan gateway. It always rewrites the path to `.../deployments/{model}/chat/completions`, which the gateway's OpenAI-compatible endpoint (`/api/chat/completions`) does not serve, so every request 404s. Use the `OpenAI` client instead, as shown below.

## Migrate from `AzureOpenAI` to `OpenAI`

#### Install the SDK

Already installed if you use the Azure client — it is the same package.

```bash
# Python
pip install openai

# TypeScript
npm install openai
```

#### Set environment variables

```bash
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export RESPAN_BASE_URL="https://api.respan.ai/api"
export RESPAN_MODEL="YOUR_MODEL_OR_DEPLOYMENT_SLUG"
```

Configure your Azure OpenAI provider credentials and deployments in Respan first. Your raw Azure key stays in Respan; the app only holds `RESPAN_API_KEY`.

#### Swap the client

Change the constructor. Everything after it — `chat.completions.create`, messages, streaming, tools, response parsing — stays the same.

**`Before — Azure client`**

```python title="Before — Azure client"
from openai import AzureOpenAI

client = AzureOpenAI(
    azure_endpoint="https://YOUR_RESOURCE.openai.azure.com",
    api_key="YOUR_AZURE_OPENAI_API_KEY",
    api_version="2024-10-21",
)

response = client.chat.completions.create(
    model="your-azure-deployment",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
```

**`After — OpenAI client through Respan`**

```python title="After — OpenAI client through Respan"
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["RESPAN_BASE_URL"],
    api_key=os.environ["RESPAN_API_KEY"],
)

response = client.chat.completions.create(
    model=os.environ["RESPAN_MODEL"],  # model/deployment slug configured in Respan
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
```

TypeScript is the same swap:

**`Before — Azure client`**

```typescript title="Before — Azure client"
import { AzureOpenAI } from "openai";

const client = new AzureOpenAI({
  endpoint: "https://YOUR_RESOURCE.openai.azure.com",
  apiKey: process.env.AZURE_OPENAI_API_KEY,
  apiVersion: "2024-10-21",
});
```

**`After — OpenAI client through Respan`**

```typescript title="After — OpenAI client through Respan"
import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: process.env.RESPAN_BASE_URL ?? "https://api.respan.ai/api",
  apiKey: process.env.RESPAN_API_KEY,
});
```

## What changes

| `AzureOpenAI` client                          | `OpenAI` client through Respan         |
| --------------------------------------------- | -------------------------------------- |
| `AzureOpenAI(...)`                            | `OpenAI(...)`                          |
| `azure_endpoint="https://….openai.azure.com"` | `base_url="https://api.respan.ai/api"` |
| `api_key=<Azure key>`                         | `api_key=<Respan key>`                 |
| `api_version="…"`                             | not needed — remove it                 |
| `azure_deployment="…"`                        | not needed — set `model` per request   |
| `model="<deployment name>"`                   | `model="<model or slug in Respan>"`    |

Nothing else in your call sites changes.

## Fallback to another provider

The gateway can fail over automatically. This is the common Azure-primary, Claude-fallback setup:

```python
response = client.chat.completions.create(
    model=os.environ["RESPAN_MODEL"],
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
    extra_body={"fallback_models": ["anthropic/claude-opus-5-5"]},
)
```

## Switch models

Change `model` to another Azure deployment or to any other model configured for your Respan gateway account.

```python
client.chat.completions.create(model="YOUR_MODEL_OR_DEPLOYMENT_SLUG", messages=messages)
client.chat.completions.create(model="openai/gpt-6-sol", messages=messages)
client.chat.completions.create(model="anthropic/claude-opus-5-5", messages=messages)
```

See the [full model list](https://platform.respan.ai/platform/models).

## Escape hatch: keep the `AzureOpenAI` client

> **Warning**
>
> Prefer the migration above. Use this only if you genuinely cannot change your `AzureOpenAI(...)` call sites. It overrides a private method of the `openai` SDK (`_build_request` / `buildRequest`), so it is **fragile across SDK versions** — pin your `openai` version and re-test after any major upgrade.

Subclass the Azure client to skip its `/deployments/{model}` path rewrite, and send auth as a bearer token (the endpoint does not accept the Azure `api-key` header):

**`Python`**

```python title="Python"
import os
from openai import AzureOpenAI, OpenAI

class RespanAzureOpenAI(AzureOpenAI):
    def _build_request(self, options, *, retries_taken=0):
        return OpenAI._build_request(self, options, retries_taken=retries_taken)

respan_api_key = os.environ["RESPAN_API_KEY"]

client = RespanAzureOpenAI(
    base_url=os.environ["RESPAN_BASE_URL"],
    api_key=respan_api_key,
    api_version="2024-10-21",  # required by the client; ignored by the gateway
    default_headers={"Authorization": f"Bearer {respan_api_key}"},
)
```

**`TypeScript`**

```typescript title="TypeScript"
import { AzureOpenAI, OpenAI } from "openai";

class RespanAzureOpenAI extends AzureOpenAI {
  async buildRequest(options: any, props?: any) {
    return OpenAI.prototype.buildRequest.call(this, options, props);
  }
}

const respanApiKey = process.env.RESPAN_API_KEY!;

const client = new RespanAzureOpenAI({
  baseURL: process.env.RESPAN_BASE_URL ?? "https://api.respan.ai/api",
  apiKey: respanApiKey,
  apiVersion: "2024-10-21",
  defaultHeaders: { Authorization: `Bearer ${respanApiKey}` },
});
```