# How aisuite's Unified Chat Completions API Handles Provider-Specific Parameter Mapping

> Learn how aisuite's unified Chat Completions API maps provider parameters. Discover how it uses provider classes and custom parameters for seamless integration.

- Repository: [Andrew Ng/aisuite](https://github.com/andrewyng/aisuite)
- Tags: internals
- Published: 2026-08-03

---

**aisuite maps provider-specific parameters by routing unified requests through provider classes that translate standard fields into vendor-native payloads, using namespaced `custom_parameters` for vendor-only options.**

The `andrewyng/aisuite` library simplifies multi-provider AI development by exposing a single, provider-agnostic **Chat Completions API**. When you call this unified endpoint, aisuite handles the complexity of translating your request into the exact format each vendor requires—OpenAI, Anthropic, Google, and others. This article explains how the **provider-specific parameter mapping** works under the hood, using actual source paths and implementation patterns from the codebase.

## The Unified Request Flow

Every call to the Chat Completions API follows a six-step pipeline that preserves consistency while accommodating vendor differences.

### Step 1: Parse the Unified Schema

Requests enter the system as a `ChatCompletionRequest` object defined in [`aisuite/framework/message.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/message.py). This dataclass standardizes common fields across all providers: `model`, `messages`, `temperature`, `max_tokens`, and `custom_parameters`.

### Step 2: Route to the Correct Provider

The dispatcher in [`aisuite/provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py) looks up the provider name (e.g., `"openai"`, `"anthropic"`) and instantiates the matching provider class—`OpenAIProvider`, `AnthropicProvider`, or similar.

### Step 3: Map Parameters to Vendor Format

Each provider implements a **parameter-conversion routine** (conventionally named `_map_chat_params`) that builds the vendor's native payload. The mapper:

- Copies **common fields** directly (`model`, `messages`, `temperature`, `max_tokens`)
- Injects **vendor-specific extensions** only when present (e.g., OpenAI's `logprobs`, Anthropic's `max_tokens_to_sample`)

Here's the pattern from [`aisuite/providers/openai_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/openai_provider.py):

```python
def _map_chat_params(self, request):
    payload = {
        "model": request.model,
        "messages": request.messages,
        "temperature": request.temperature,
        "max_tokens": request.max_tokens,
    }
    # Apply any custom OpenAI-only fields

    ParameterMapper._apply_custom_parameters(
        payload, request.custom_parameters, provider="openai"
    )
    return payload

```

### Step 4: Enforce Custom Parameter Namespacing

Vendor-only options are passed through `custom_parameters` as a **namespaced dictionary**. The shared utility `ParameterMapper._apply_custom_parameters` in [`aisuite/framework/parameter_mapper.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/parameter_mapper.py) (lines 202-224) enforces this rule: only keys nested under the correct provider name are merged.

```python
class ParameterMapper:
    @classmethod
    def _apply_custom_parameters(cls, params, custom_params, provider):
        if not custom_params:
            return
        if provider in custom_params:
            params.update(custom_params[provider])  # strict namespacing

```

This prevents accidental parameter leakage—an OpenAI-specific setting won't contaminate an Anthropic request.

### Step 5: Execute the HTTP Request

The fully-converted payload is sent via the provider's `request` method using its native HTTP client (e.g., `self.session.post(...)` for OpenAI).

### Step 6: Normalize the Response

Regardless of vendor format, the response is converted back to a unified `ChatCompletionResponse` defined in [`aisuite/framework/chat_completion_response.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/chat_completion_response.py). Your downstream code remains provider-agnostic.

## Using Provider-Specific Parameters in Practice

To access vendor-only features, nest them under the provider key in `custom_parameters`:

```python
from aisuite.client import AISuiteClient

client = AISuiteClient(provider="openai", api_key="...")
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Explain quantum tunnelling"}],
    temperature=0.7,
    # OpenAI-specific: request log probabilities

    custom_parameters={"openai": {"logprobs": 5, "top_logprobs": 3}}
)

print(resp.choices[0].message.content)

```

Compare with Anthropic's equivalent:

```python
client = AISuiteClient(provider="anthropic", api_key="...")
resp = client.chat.completions.create(
    model="claude-3-sonnet-20240229",
    messages=[{"role": "user", "content": "Explain quantum tunnelling"}],
    temperature=0.7,
    # Anthropic-specific: different parameter name for token limit

    custom_parameters={"anthropic": {"max_tokens_to_sample": 1024}}
)

```

## Key Mapping Rules

| Rule | Implementation |
|------|----------------|
| **Direct copy** | Common fields with identical names pass through unchanged |
| **Conditional injection** | Vendor extensions added only if the unified request contains matching attributes |
| **Strict namespacing** | `custom_parameters` keys filtered by provider name in `ParameterMapper._apply_custom_parameters` |
| **Response normalization** | All providers return `ChatCompletionResponse` instances |

## Critical Source Files

| File | Role |
|------|------|
| [`aisuite/framework/message.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/message.py) | `ChatCompletionRequest` dataclass—unified input schema |
| [`aisuite/provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/provider.py) | Provider selection and dispatch logic |
| [`aisuite/framework/parameter_mapper.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/parameter_mapper.py) | Shared `ParameterMapper` class for namespaced parameter merging |
| [`aisuite/providers/openai_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/openai_provider.py) | OpenAI-specific mapping implementation (`_map_chat_params`) |
| [`aisuite/providers/anthropic_provider.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/providers/anthropic_provider.py) | Anthropic-specific mapping (same pattern) |
| [`aisuite/framework/chat_completion_response.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/chat_completion_response.py) | Normalized output schema |

## Summary

- aisuite's **unified Chat Completions API** accepts provider-agnostic requests through `ChatCompletionRequest` in [`aisuite/framework/message.py`](https://github.com/andrewyng/aisuite/blob/main/aisuite/framework/message.py)
- **Provider classes** in `aisuite/providers/` handle vendor-specific translation via `_map_chat_params` methods
- **Namespaced `custom_parameters`** let you access vendor-only features safely; `ParameterMapper._apply_custom_parameters` enforces isolation
- All responses normalize to `ChatCompletionResponse`, keeping downstream code decoupled from provider specifics

## Frequently Asked Questions

### What happens if I put a custom parameter in the wrong namespace?

The parameter is **ignored**. `ParameterMapper._apply_custom_parameters` only merges keys that match the active provider name. An `{"openai": {...}}` block has no effect when using `provider="anthropic"`, preventing silent errors from parameter misrouting.

### Can I use the same `custom_parameters` dict for multiple providers in one call?

No—**each call targets one provider**. The `AISuiteClient` is initialized with a specific provider, and `custom_parameters` is evaluated per-request against that provider's namespace. For multi-provider workflows, create separate client instances or change the provider between calls.

### Does aisuite validate that provider-specific parameters are valid for the vendor?

**No pre-flight validation occurs aisuite-side.** The library faithfully passes your namespaced parameters to the vendor's API. Invalid parameters will surface as errors from the provider's HTTP endpoint (e.g., 400 Bad Request from OpenAI). This design keeps aisuite lightweight and avoids maintaining per-vendor validation schemas.

### How do I discover which custom parameters a provider supports?

Consult the **vendor's official API documentation** directly. aisuite does not wrap or restrict provider-specific options—anything valid in the native API can be passed through the corresponding namespace in `custom_parameters`. For OpenAI, check the [OpenAI API reference](https://platform.openai.com/docs/api-reference/chat); for Anthropic, see the [Anthropic Messages API](https://docs.anthropic.com/en/api/messages).