# How to Configure Azure OpenAI Client with API Version, Endpoint, and Deployment

> Learn to configure your Azure OpenAI client using the create_azure_openai_client utility function or AzureOpenAI directly. Set your api_version, endpoint, and deployment for seamless integration.

- Repository: [Microsoft/generative-ai-for-beginners](https://github.com/microsoft/generative-ai-for-beginners)
- Tags: how-to-guide
- Published: 2026-02-26

---

**Use the `create_azure_openai_client` utility function from [`shared/python/api_utils.py`](https://github.com/microsoft/generative-ai-for-beginners/blob/main/shared/python/api_utils.py) or instantiate `AzureOpenAI` directly with `azure_endpoint`, `api_version`, and `api_key` parameters while loading credentials from environment variables.**

The `microsoft/generative-ai-for-beginners` repository provides production-ready patterns for configuring the Azure OpenAI client. Proper configuration requires setting the API version, endpoint URL, and deployment name while keeping sensitive credentials out of source code.

## Using the Utility Function (Recommended)

The repository includes a centralized helper that standardizes client creation across all lessons.

### Implementation Details in api_utils.py

Located in [`shared/python/api_utils.py`](https://github.com/microsoft/generative-ai-for-beginners/blob/main/shared/python/api_utils.py), the `create_azure_openai_client` function handles credential validation and client instantiation. The implementation spans lines 100-104 for the function signature and lines 48-52 for the return statement:

```python
def create_azure_openai_client(
    endpoint: Optional[str] = None,
    api_key: Optional[str] = None,
    api_version: str = "2024-02-01"
) -> Any:
    ...
    return AzureOpenAI(
        azure_endpoint=_endpoint,
        api_key=_api_key,
        api_version=api_version
    )

```

The function reads `AZURE_OPENAI_ENDPOINT` and `AZURE_OPENAI_API_KEY` from environment variables when arguments are omitted, raising a `ValueError` if either is missing. You can override the default API version (`2024-02-01`) with any supported preview or GA version.

```python
from shared.python.api_utils import create_azure_openai_client
from dotenv import load_dotenv
import os

load_dotenv()

client = create_azure_openai_client(
    api_version="2023-12-01-preview"
)

deployment = os.getenv("AZURE_OPENAI_DEPLOYMENT")
response = client.chat.completions.create(
    model=deployment,
    messages=[{"role": "user", "content": "Explain quantum computing"}]
)

```

## Direct Client Instantiation

For learning exercises or quick prototypes, you can instantiate the client directly without the utility wrapper.

### Example from aoai-app.py

The file [`06-text-generation-apps/python/aoai-app.py`](https://github.com/microsoft/generative-ai-for-beginners/blob/main/06-text-generation-apps/python/aoai-app.py) demonstrates minimal configuration in lines 10-14:

```python
from openai import AzureOpenAI
import os
from dotenv import load_dotenv

load_dotenv()

client = AzureOpenAI(
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    api_version="2024-02-01"
)

```

The deployment name is loaded separately from `AZURE_OPENAI_DEPLOYMENT` and passed to the `chat.completions.create` method (line 23), keeping the client configuration decoupled from model selection.

## Managing Environment Variables and Deployment Names

The repository uses a `.env` file template (`.env.copy`) to define required variables:

- `AZURE_OPENAI_ENDPOINT` – Your Azure OpenAI resource URL (e.g., `https://my-resource.openai.azure.com/`)
- `AZURE_OPENAI_API_KEY` – Your access key from the Azure portal
- `AZURE_OPENAI_DEPLOYMENT` – The deployment name you assigned to your model in Azure AI Studio

The `python-dotenv` package loads these into `os.environ` before client instantiation, ensuring credentials never appear in committed code.

When calling chat completions, specify the deployment via the `model` parameter:

```python
deployment = os.getenv("AZURE_OPENAI_DEPLOYMENT")
response = client.chat.completions.create(
    model=deployment,
    messages=[{"role": "user", "content": "Hello"}]
)

```

## Summary

- Use `create_azure_openai_client` from [`shared/python/api_utils.py`](https://github.com/microsoft/generative-ai-for-beginners/blob/main/shared/python/api_utils.py) for reusable, validated client configuration across multiple lessons.
- Pass `azure_endpoint`, `api_key`, and `api_version` directly to `AzureOpenAI()` for simple scripts or learning exercises.
- Store credentials in a `.env` file and load them with `python-dotenv` to keep secrets out of source control.
- Specify the model deployment name separately when calling `chat.completions.create`, not during client initialization.

## Frequently Asked Questions

### What is the default API version used in the repository?

The default API version is `2024-02-01`, defined in the `create_azure_openai_client` function signature in [`shared/python/api_utils.py`](https://github.com/microsoft/generative-ai-for-beginners/blob/main/shared/python/api_utils.py). You can override this with any supported Azure OpenAI API version, such as `2023-12-01-preview` for early access to new features.

### How does the repository handle missing environment variables?

The `create_azure_openai_client` utility validates that both `AZURE_OPENAI_ENDPOINT` and `AZURE_OPENAI_API_KEY` are present, either as function arguments or environment variables. If either is missing, the function raises a `ValueError` with a descriptive message before attempting to instantiate the client.

### Where should I store my Azure OpenAI credentials?

According to the repository patterns, credentials should be stored in a `.env` file at the project root (using the provided `.env.copy` template). The `python-dotenv` library loads these variables into the process environment at runtime, ensuring that sensitive keys and endpoints never appear in committed source code.

### How do I specify the model deployment in API calls?

The deployment name (the identifier you assigned when deploying the model in Azure AI Studio) is passed to the `model` parameter of `client.chat.completions.create()`, not during client initialization. Retrieve this value from the `AZURE_OPENAI_DEPLOYMENT` environment variable and pass it at request time to switch between different models without recreating the client.