0
# Chat Completions
1

2
OpenAI-compatible chat completion API with support for all major providers, streaming, function calling, and advanced Portkey features like fallbacks and load balancing.
3

4
## Capabilities
5

6
### Chat Completion Creation
7

8
Primary method for generating chat completions with support for multi-turn conversations, function calling, and streaming responses.
9

10
```python { .api }
11
class ChatCompletion:
12
    """Synchronous chat completion API"""
13
    completions: Completions
14

15
class Completions:
16
    """Chat completions endpoint"""
17
    
18
    def create(
19
        self,
20
        *,
21
        messages: Iterable[dict],
22
        model: Optional[str] = "portkey-default",
23
        stream: Optional[bool] = None,
24
        temperature: Optional[float] = None,
25
        max_tokens: Optional[int] = None,
26
        top_p: Optional[float] = None,
27
        audio: Optional[Any] = None,
28
        max_completion_tokens: Optional[int] = None,
29
        metadata: Optional[Dict[str, str]] = None,
30
        modalities: Optional[List[Any]] = None,
31
        prediction: Optional[Any] = None,
32
        reasoning_effort: Optional[Any] = None,
33
        store: Optional[bool] = None,
34
        **kwargs
35
    ) -> Union[ChatCompletions, Iterator[ChatCompletionChunk]]:
36
        """
37
        Create a chat completion.
38
        
39
        Parameters:
40
        - messages: List of message objects with 'role' and 'content'
41
        - model: Model identifier (defaults to 'portkey-default')
42
        - max_tokens: Maximum tokens to generate
43
        - temperature: Sampling temperature
44
        - stream: Enable streaming responses
45
        - top_p: Nucleus sampling parameter
46
        - audio: Audio configuration for multimodal models
47
        - max_completion_tokens: Maximum completion tokens
48
        - metadata: Custom metadata for request
49
        - modalities: Supported modalities (text, audio, etc.)
50
        - prediction: Prediction configuration
51
        - reasoning_effort: Reasoning effort level
52
        - store: Whether to store the conversation
53
        
54
        Returns:
55
        ChatCompletions object or Iterator of ChatCompletionChunk for streaming
56
        """
57
    
58
    messages: ChatCompletionsMessages
59

60
class AsyncChatCompletion:
61
    """Asynchronous chat completion API"""
62
    completions: AsyncCompletions
63

64
class AsyncCompletions:
65
    """Async chat completions endpoint"""
66
    
67
    async def create(
68
        self,
69
        *,
70
        messages: Iterable[dict],
71
        model: Optional[str] = "portkey-default",
72
        **kwargs
73
    ) -> Union[ChatCompletions, AsyncIterator[ChatCompletionChunk]]:
74
        """Async version of chat completion creation"""
75
```
76

77
### Message Management
78

79
Handle multi-turn conversations with proper message formatting and conversation context management.
80

81
```python { .api }
82
class ChatCompletionsMessages:
83
    """Message handling utilities for chat completions"""
84
    
85
    def create(self, **kwargs): ...
86
    def list(self, **kwargs): ...
87
    def retrieve(self, **kwargs): ...
88
    def update(self, **kwargs): ...
89
    def delete(self, **kwargs): ...
90

91
class AsyncChatCompletionsMessages:
92
    """Async message handling utilities"""
93
    
94
    async def create(self, **kwargs): ...
95
    async def list(self, **kwargs): ...
96
    async def retrieve(self, **kwargs): ...
97
    async def update(self, **kwargs): ...
98
    async def delete(self, **kwargs): ...
99
```
100

101
## Usage Examples
102

103
### Basic Chat Completion
104

105
```python
106
from portkey_ai import Portkey
107

108
portkey = Portkey(
109
    api_key="PORTKEY_API_KEY",
110
    virtual_key="VIRTUAL_KEY"
111
)
112

113
# Simple chat completion
114
response = portkey.chat.completions.create(
115
    messages=[
116
        {"role": "user", "content": "What is machine learning?"}
117
    ],
118
    model="gpt-4"
119
)
120

121
print(response.choices[0].message.content)
122
```
123

124
### Multi-turn Conversation
125

126
```python
127
# Multi-turn conversation
128
messages = [
129
    {"role": "system", "content": "You are a helpful assistant."},
130
    {"role": "user", "content": "Explain quantum computing"},
131
    {"role": "assistant", "content": "Quantum computing is..."},
132
    {"role": "user", "content": "What are its main applications?"}
133
]
134

135
response = portkey.chat.completions.create(
136
    messages=messages,
137
    model="gpt-4",
138
    max_tokens=500,
139
    temperature=0.7
140
)
141

142
print(response.choices[0].message.content)
143
```
144

145
### Streaming Response
146

147
```python
148
# Streaming chat completion
149
stream = portkey.chat.completions.create(
150
    messages=[
151
        {"role": "user", "content": "Write a story about AI"}
152
    ],
153
    model="gpt-4",
154
    stream=True
155
)
156

157
for chunk in stream:
158
    if chunk.choices[0].delta.content:
159
        print(chunk.choices[0].delta.content, end="")
160
```
161

162
### Function Calling
163

164
```python
165
# Function calling with tools
166
tools = [
167
    {
168
        "type": "function",
169
        "function": {
170
            "name": "get_weather",
171
            "description": "Get weather information for a location",
172
            "parameters": {
173
                "type": "object",
174
                "properties": {
175
                    "location": {
176
                        "type": "string",
177
                        "description": "City name"
178
                    },
179
                    "unit": {
180
                        "type": "string",
181
                        "enum": ["celsius", "fahrenheit"],
182
                        "description": "Temperature unit"
183
                    }
184
                },
185
                "required": ["location"]
186
            }
187
        }
188
    }
189
]
190

191
response = portkey.chat.completions.create(
192
    messages=[
193
        {"role": "user", "content": "What's the weather in San Francisco?"}
194
    ],
195
    model="gpt-4",
196
    tools=tools,
197
    tool_choice="auto"
198
)
199

200
# Handle function call
201
if response.choices[0].message.tool_calls:
202
    tool_call = response.choices[0].message.tool_calls[0]
203
    function_name = tool_call.function.name
204
    function_args = tool_call.function.arguments
205
    print(f"Function called: {function_name} with args: {function_args}")
206
```
207

208
### Async Usage
209

210
```python
211
import asyncio
212
from portkey_ai import AsyncPortkey
213

214
async def chat_example():
215
    portkey = AsyncPortkey(
216
        api_key="PORTKEY_API_KEY",
217
        virtual_key="VIRTUAL_KEY"
218
    )
219
    
220
    response = await portkey.chat.completions.create(
221
        messages=[
222
            {"role": "user", "content": "Hello, how are you?"}
223
        ],
224
        model="gpt-4"
225
    )
226
    
227
    print(response.choices[0].message.content)
228
    
229
    # Async streaming
230
    async for chunk in await portkey.chat.completions.create(
231
        messages=[{"role": "user", "content": "Count to 10"}],
232
        model="gpt-4",
233
        stream=True
234
    ):
235
        if chunk.choices[0].delta.content:
236
            print(chunk.choices[0].delta.content, end="")
237

238
asyncio.run(chat_example())
239
```
240

241
### Response Format Control
242

243
```python
244
# JSON response format
245
response = portkey.chat.completions.create(
246
    messages=[
247
        {"role": "user", "content": "List 3 colors in JSON format"}
248
    ],
249
    model="gpt-4",
250
    response_format={"type": "json_object"}
251
)
252

253
# Structured output with seed for reproducibility
254
response = portkey.chat.completions.create(
255
    messages=[
256
        {"role": "user", "content": "Generate a random number"}
257
    ],
258
    model="gpt-4",
259
    seed=12345,
260
    temperature=0
261
)
262
```
263

264
## Message Format
265

266
### Message Structure
267

268
```python
269
# Message object structure
270
message = {
271
    "role": "user" | "assistant" | "system" | "tool",
272
    "content": str | List[dict],  # Text or multimodal content
273
    "name": str,                  # Optional message name
274
    "tool_calls": List[dict],     # Tool calls (assistant messages)
275
    "tool_call_id": str          # Tool call ID (tool messages)
276
}
277
```
278

279
### Multimodal Content
280

281
```python
282
# Text and image message
283
message = {
284
    "role": "user",
285
    "content": [
286
        {
287
            "type": "text",
288
            "text": "What's in this image?"
289
        },
290
        {
291
            "type": "image_url",
292
            "image_url": {
293
                "url": "https://example.com/image.jpg",
294
                "detail": "high"
295
            }
296
        }
297
    ]
298
}
299
```
300

301
## Advanced Features
302

303
### Provider-Specific Parameters
304

305
Different providers support various additional parameters:
306

307
```python
308
# OpenAI-specific parameters
309
response = portkey.chat.completions.create(
310
    messages=messages,
311
    model="gpt-4",
312
    logprobs=True,
313
    top_logprobs=3,
314
    logit_bias={50256: -100}  # Reduce likelihood of specific tokens
315
)
316

317
# Anthropic-specific parameters  
318
response = portkey.chat.completions.create(
319
    messages=messages,
320
    model="claude-3-sonnet-20240229",
321
    max_tokens=1000,
322
    anthropic_version="2023-06-01"
323
)
324
```
325

326
### Portkey-Specific Features
327

328
```python
329
# Multiple providers with fallback
330
portkey = Portkey(
331
    api_key="PORTKEY_API_KEY",
332
    config={
333
        "strategy": {"mode": "fallback"},
334
        "targets": [
335
            {"provider": "openai", "api_key": "OPENAI_KEY"},
336
            {"provider": "anthropic", "api_key": "ANTHROPIC_KEY"}
337
        ]
338
    }
339
)
340

341
# Load balancing across providers
342
portkey = Portkey(
343
    api_key="PORTKEY_API_KEY", 
344
    config={
345
        "strategy": {"mode": "loadbalance"},
346
        "targets": [
347
            {"provider": "openai", "api_key": "OPENAI_KEY", "weight": 0.7},
348
            {"provider": "anthropic", "api_key": "ANTHROPIC_KEY", "weight": 0.3}
349
        ]
350
    }
351
)
352

353
# Request with custom metadata
354
response = portkey.chat.completions.create(
355
    messages=messages,
356
    model="gpt-4",
357
    metadata={
358
        "user_id": "user123",
359
        "session_id": "session456",
360
        "environment": "production"
361
    }
362
)
363
```