0
# Core Client & Configuration
1

2
Primary client classes and configuration utilities for initializing and managing Portkey connections with comprehensive provider support and advanced routing capabilities.
3

4
## Capabilities
5

6
### Main Client Classes
7

8
Core synchronous and asynchronous client classes that provide the primary interface to Portkey's AI gateway and observability features.
9

10
```python { .api }
11
class Portkey:
12
    """
13
    Primary synchronous client for Portkey AI API.
14
    
15
    Provides unified interface to 40+ AI providers with built-in fallbacks,
16
    load balancing, caching, and comprehensive observability.
17
    """
18
    def __init__(
19
        self,
20
        *,
21
        api_key: Optional[str] = None,
22
        base_url: Optional[str] = None,
23
        virtual_key: Optional[str] = None,
24
        websocket_base_url: Optional[Union[str, httpx.URL]] = None,
25
        config: Optional[Union[Mapping, str]] = None,
26
        provider: Optional[str] = None,
27
        trace_id: Optional[str] = None,
28
        metadata: Union[Optional[dict[str, str]], str] = None,
29
        cache_namespace: Optional[str] = None,
30
        debug: Optional[bool] = None,
31
        cache_force_refresh: Optional[bool] = None,
32
        custom_host: Optional[str] = None,
33
        forward_headers: Optional[List[str]] = None,
34
        instrumentation: Optional[bool] = None,
35
        openai_project: Optional[str] = None,
36
        openai_organization: Optional[str] = None,
37
        aws_secret_access_key: Optional[str] = None,
38
        aws_access_key_id: Optional[str] = None,
39
        aws_session_token: Optional[str] = None,
40
        aws_region: Optional[str] = None,
41
        vertex_project_id: Optional[str] = None,
42
        vertex_region: Optional[str] = None,
43
        workers_ai_account_id: Optional[str] = None,
44
        azure_resource_name: Optional[str] = None,
45
        azure_deployment_id: Optional[str] = None,
46
        azure_api_version: Optional[str] = None,
47
        azure_endpoint_name: Optional[str] = None,
48
        huggingface_base_url: Optional[str] = None,
49
        http_client: Optional[httpx.Client] = None,
50
        request_timeout: Optional[int] = None,
51
        strict_open_ai_compliance: Optional[bool] = False,
52
        anthropic_beta: Optional[str] = None,
53
        anthropic_version: Optional[str] = None,
54
        mistral_fim_completion: Optional[str] = None,
55
        vertex_storage_bucket_name: Optional[str] = None,
56
        provider_file_name: Optional[str] = None,
57
        provider_model: Optional[str] = None,
58
        aws_s3_bucket: Optional[str] = None,
59
        aws_s3_object_key: Optional[str] = None,
60
        aws_bedrock_model: Optional[str] = None,
61
        fireworks_account_id: Optional[str] = None,
62
        calculate_audio_duration: Optional[bool] = True,
63
        **kwargs
64
    ) -> None: ...
65

66
class AsyncPortkey:
67
    """
68
    Asynchronous client for Portkey AI API.
69
    
70
    Async version of Portkey client with identical API surface
71
    supporting concurrent operations and async/await patterns.
72
    """
73
    def __init__(self, **kwargs) -> None: ...
74
```
75

76
### Usage Examples
77

78
```python
79
# Basic initialization
80
from portkey_ai import Portkey
81

82
portkey = Portkey(
83
    api_key="PORTKEY_API_KEY",
84
    virtual_key="VIRTUAL_KEY"
85
)
86

87
# Advanced configuration with provider-specific settings
88
portkey = Portkey(
89
    api_key="PORTKEY_API_KEY",
90
    config={
91
        "strategy": {
92
            "mode": "fallback"
93
        },
94
        "targets": [
95
            {
96
                "provider": "openai",
97
                "api_key": "OPENAI_API_KEY"
98
            },
99
            {
100
                "provider": "anthropic", 
101
                "api_key": "ANTHROPIC_API_KEY"
102
            }
103
        ]
104
    },
105
    metadata={
106
        "environment": "production",
107
        "user_id": "user123"
108
    },
109
    trace_id="trace-abc-123",
110
    debug=True
111
)
112

113
# Async client usage
114
import asyncio
115
from portkey_ai import AsyncPortkey
116

117
async def main():
118
    portkey = AsyncPortkey(
119
        api_key="PORTKEY_API_KEY",
120
        virtual_key="VIRTUAL_KEY"
121
    )
122
    
123
    response = await portkey.chat.completions.create(
124
        messages=[{"role": "user", "content": "Hello"}],
125
        model="gpt-4"
126
    )
127
    
128
    print(response)
129

130
asyncio.run(main())
131
```
132

133
### Header Creation Utilities
134

135
Utility functions for creating and managing Portkey-specific request headers.
136

137
```python { .api }
138
def createHeaders(
139
    api_key: Optional[str] = None,
140
    provider: Optional[str] = None,
141
    trace_id: Optional[str] = None,
142
    metadata: Optional[dict] = None,
143
    config: Optional[Union[str, dict]] = None,
144
    cache_namespace: Optional[str] = None,
145
    cache_force_refresh: Optional[bool] = None,
146
    virtual_key: Optional[str] = None,
147
    custom_host: Optional[str] = None,
148
    forward_headers: Optional[List[str]] = None,
149
    openai_project: Optional[str] = None,
150
    openai_organization: Optional[str] = None,
151
    aws_secret_access_key: Optional[str] = None,
152
    aws_access_key_id: Optional[str] = None,
153
    aws_session_token: Optional[str] = None,
154
    aws_region: Optional[str] = None,
155
    vertex_project_id: Optional[str] = None,
156
    vertex_region: Optional[str] = None,
157
    workers_ai_account_id: Optional[str] = None,
158
    azure_resource_name: Optional[str] = None,
159
    azure_deployment_id: Optional[str] = None,
160
    azure_api_version: Optional[str] = None,
161
    azure_endpoint_name: Optional[str] = None,
162
    anthropic_beta: Optional[str] = None,
163
    anthropic_version: Optional[str] = None,
164
    **kwargs
165
) -> dict:
166
    """
167
    Create Portkey-specific headers for API requests.
168
    
169
    Returns:
170
    Dictionary of headers for HTTP requests
171
    """
172
```
173

174
### Global Configuration Variables
175

176
Module-level configuration variables for default settings.
177

178
```python { .api }
179
api_key: Optional[str]
180
"""Global API key from environment variable PORTKEY_API_KEY"""
181

182
base_url: Optional[str] 
183
"""Global base URL from environment variable PORTKEY_PROXY_ENV or default"""
184

185
config: Optional[Union[Mapping, str]]
186
"""Global configuration object"""
187

188
mode: Optional[Union[Modes, ModesLiteral]]
189
"""Global mode setting"""
190
```
191

192
### Constants
193

194
```python { .api }
195
PORTKEY_BASE_URL: str
196
"""Default Portkey API base URL"""
197

198
PORTKEY_API_KEY_ENV: str
199
"""Environment variable name for API key"""
200

201
PORTKEY_PROXY_ENV: str
202
"""Environment variable name for proxy URL"""
203

204
PORTKEY_GATEWAY_URL: str
205
"""Gateway URL constant"""
206
```
207

208
## Configuration Parameters
209

210
### Core Parameters
211

212
- **api_key**: Portkey API key for authentication
213
- **base_url**: Base URL for API requests (defaults to Portkey gateway)
214
- **virtual_key**: Virtual key for secure credential management
215
- **config**: Configuration object for routing, fallbacks, and provider settings
216
- **provider**: Specific AI provider to use
217
- **trace_id**: Request tracing identifier for observability
218
- **metadata**: Custom metadata for request categorization and analytics
219

220
### Caching Parameters
221

222
- **cache_namespace**: Namespace for cache isolation
223
- **cache_force_refresh**: Force cache refresh for requests
224

225
### Observability Parameters
226

227
- **debug**: Enable debug mode for detailed logging
228
- **instrumentation**: Enable request instrumentation
229
- **forward_headers**: List of headers to forward to providers
230

231
### Provider-Specific Parameters
232

233
#### OpenAI
234
- **openai_project**: OpenAI project ID
235
- **openai_organization**: OpenAI organization ID
236

237
#### AWS/Bedrock
238
- **aws_secret_access_key**: AWS secret access key
239
- **aws_access_key_id**: AWS access key ID
240
- **aws_session_token**: AWS session token
241
- **aws_region**: AWS region
242
- **aws_s3_bucket**: S3 bucket for file operations
243
- **aws_s3_object_key**: S3 object key
244
- **aws_bedrock_model**: Bedrock model identifier
245

246
#### Google Vertex AI
247
- **vertex_project_id**: Vertex AI project ID
248
- **vertex_region**: Vertex AI region
249
- **vertex_storage_bucket_name**: Storage bucket name
250

251
#### Azure OpenAI
252
- **azure_resource_name**: Azure resource name
253
- **azure_deployment_id**: Azure deployment ID
254
- **azure_api_version**: Azure API version
255
- **azure_endpoint_name**: Azure endpoint name
256

257
#### Anthropic
258
- **anthropic_beta**: Anthropic beta features
259
- **anthropic_version**: Anthropic API version
260

261
#### Other Providers
262
- **workers_ai_account_id**: Cloudflare Workers AI account ID
263
- **huggingface_base_url**: HuggingFace API base URL
264
- **fireworks_account_id**: Fireworks AI account ID
265
- **mistral_fim_completion**: Mistral fill-in-middle completion setting
266

267
### HTTP Configuration
268

269
- **http_client**: Custom HTTP client instance
270
- **request_timeout**: Request timeout in seconds
271
- **websocket_base_url**: WebSocket base URL for real-time features
272
- **custom_host**: Custom host override
273
- **strict_open_ai_compliance**: Enforce strict OpenAI API compliance