# Handling Provider-Specific Parameters with extra_param_mode in aisuite

> Master extra_param_mode in aisuite to expertly manage provider-specific transcription parameters. Learn strict, warn, and permissive modes for better control and error handling.

- Repository: [Andrew Ng/aisuite](https://github.com/andrewyng/aisuite)
- Tags: how-to-guide
- Published: 2026-06-15

---

**aisuite uses the `extra_param_mode` parameter to control how unknown transcription arguments are handled, offering three behaviors: `"strict"` (raise an error), `"warn"` (emit a warning but continue), or `"permissive"` (silently forward the parameters).**

The `aisuite` library normalizes audio transcription requests across multiple AI providers through a centralized validation system. When you call `client.audio.transcriptions.create()`, your arguments pass through the **`ParamValidator`** class in [`aisuite/framework/asr_params.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/asr_params.py) before reaching the provider's API. This validator automatically maps common parameters to provider-specific names and uses **`extra_param_mode`** to govern how it treats unrecognized keys.

## How aisuite Categorizes Transcription Parameters

The validation logic in [`aisuite/framework/asr_params.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/asr_params.py) organizes incoming parameters into three distinct groups. This classification determines whether a parameter is transformed, passed through directly, or flagged as unknown.

### Common Parameters and Automatic Mapping

**Common parameters** follow OpenAI's naming convention (e.g., `language`, `prompt`, `temperature`) and are automatically translated to provider-specific equivalents. The `COMMON_PARAMS` table defined at lines 19-38 maps these standardized names to each provider's internal schema.

For example, when you pass `language="en"` to Google, the validator's `_transform_value` method (lines 58-61) converts it to `language_code="en-US"`. This ensures cross-provider compatibility without requiring you to memorize different naming conventions for each service.

### Provider-Specific Parameter Whitelists

Each provider defines a whitelist of supported arguments in the `PROVIDER_PARAMS` dictionary (lines 43-129). **Provider-specific parameters** appearing in this set bypass the common mapping logic and pass directly to the API unchanged.

If you use Deepgram-specific features like `punctuate=True` or `diarize=True`, the validator recognizes these as valid provider parameters and forwards them without transformation or warnings.

## Controlling Unknown Parameters with extra_param_mode

When the validator encounters a parameter that exists in neither the common set nor the provider whitelist, it triggers the **`extra_param_mode`** logic implemented in the `_handle_unknown` method (lines 74-97). You set this mode when constructing a `Client` instance, and it propagates to the validator via `self.param_validator = ParamValidator(extra_param_mode)`.

The three supported modes behave as follows:

- **`"strict"`** – Raises a `ValueError` immediately with a descriptive message (lines 90-92). Use this in production environments to catch typos or unsupported arguments before they reach the provider.
- **`"warn"`** – Emits a `UserWarning` but continues execution (lines 93-96). This is the default behavior, providing visibility into potential issues without breaking the request.
- **`"permissive"`** – Silently passes unknown keys through to the provider (lines 33-36). Use this when testing beta features or provider-specific arguments not yet whitelisted in aisuite.

### Configuring Strict Mode for Parameter Validation

In strict mode, any unrecognized parameter triggers an exception. This is enforced in [`aisuite/client.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/client.py) at line 528 where the validator is invoked.

```python
from aisuite import Client

# Initialize client with strict validation

client = Client(
    provider_configs={"openai": {"api_key": "sk-test"}},
    extra_param_mode="strict",
)

# This raises ValueError because 'foobar' is not a recognized parameter

client.audio.transcriptions.create(
    model="openai:whisper-1",
    file=open("sample.wav", "rb"),
    language="en",
    foobar=True,  # Unknown parameter triggers exception

)

```

### Using Warn Mode to Surface Parameter Issues

Warn mode allows the request to proceed while alerting you to potential problems. The test suite verifies this behavior in [`tests/client/test_client.py`](https://github.com/andrewyng/aisuite/blob/main/tests/client/test_client.py) (lines 124-152).

```python
import warnings
from aisuite import Client

client = Client(extra_param_mode="warn")

# Capture the warning but still get results

with warnings.catch_warnings(record=True) as w:
    warnings.simplefilter("always")
    result = client.audio.transcriptions.create(
        model="openai:whisper-1",
        file=open("sample.wav", "rb"),
        language="en",
        foobar=True,  # Emits warning but request succeeds

    )
    

# w[-1] contains the UserWarning about 'foobar'

```

### Forwarding Experimental Parameters with Permissive Mode

Permissive mode bypasses validation entirely for unknown keys, forwarding them directly to the provider. This is useful for accessing beta features or provider-specific extensions not yet supported by the common interface.

```python
from aisuite import Client

client = Client(extra_param_mode="permissive")

# Unknown parameters are forwarded verbatim to the provider

result = client.audio.transcriptions.create(
    model="openai:whisper-1",
    file=open("sample.wav", "rb"),
    language="en",
    experimental_feature=True,  # Silently passed through

)

```

## Passing Provider-Specific Arguments Safely

Provider-specific parameters are not treated as "unknown" when they appear in the whitelist. According to the test `test_provider_specific_params_passthrough` (lines 221-246 in [`tests/client/test_client.py`](https://github.com/andrewyng/aisuite/blob/main/tests/client/test_client.py)), these arguments flow directly to the provider without triggering `extra_param_mode` logic.

```python
from aisuite import Client

# Deepgram-specific parameters pass through regardless of extra_param_mode

client = Client(provider_configs={"deepgram": {"api_key": "dg-test"}})

result = client.audio.transcriptions.create(
    model="deepgram:nova-2",
    file=open("sample.wav", "rb"),
    punctuate=True,  # Deepgram-specific, validated against PROVIDER_PARAMS

    diarize=True,    # Also Deepgram-specific

)

```

## Summary

- **Parameter validation** in aisuite occurs in the `ParamValidator` class ([`aisuite/framework/asr_params.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/asr_params.py)), which distinguishes between common parameters, provider-specific whitelisted parameters, and unknown parameters.
- **`extra_param_mode`** controls how unknown parameters are handled, with options for `"strict"` (raise `ValueError`), `"warn"` (emit `UserWarning`), or `"permissive"` (silent forwarding).
- **Common parameters** are automatically mapped to provider-specific names using the `COMMON_PARAMS` table (lines 19-38), while **provider-specific parameters** listed in `PROVIDER_PARAMS` (lines 43-129) pass through unchanged.
- The validation is triggered at line 528 of [`aisuite/client.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/client.py), and behaviors are verified in [`tests/client/test_client.py`](https://github.com/andrewyng/aisuite/blob/main/tests/client/test_client.py) and [`tests/framework/test_asr_params.py`](https://github.com/andrewyng/aisuite/blob/main/tests/framework/test_asr_params.py).

## Frequently Asked Questions

### What happens if I pass a misspelled parameter to aisuite?

If you pass a parameter like `temperatur=0.5` instead of `temperature`, the validator treats it as an unknown parameter. Depending on your **`extra_param_mode`**, it will either raise a `ValueError` (strict), emit a warning but continue (warn), or forward it to the provider (permissive). The default mode is `"warn"`.

### Can I use provider-specific features not listed in the aisuite documentation?

Yes. If the feature is listed in the provider's `PROVIDER_PARAMS` whitelist (lines 43-129 of [`aisuite/framework/asr_params.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/asr_params.py)), you can use it directly. If it is a brand-new or experimental parameter not yet whitelisted, set **`extra_param_mode="permissive"`** to forward it directly to the provider's API without validation.

### Where is the extra_param_mode logic implemented in the source code?

The logic is implemented in the `_handle_unknown` method of the `ParamValidator` class, located at lines 74-97 of [`aisuite/framework/asr_params.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/asr_params.py). The mode is set when instantiating a `Client` and stored in the validator instance, which is then called at line 528 of [`aisuite/client.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/client.py) during transcription request processing.

### Does strict mode reject all parameters not in the OpenAI format?

No. **Strict mode** only rejects parameters that are neither in the `COMMON_PARAMS` mapping nor the provider's `PROVIDER_PARAMS` whitelist. Provider-specific parameters like Deepgram's `punctuate` or `diarize` are always allowed because they are explicitly whitelisted, regardless of whether they follow OpenAI's naming convention.