docs
0
# OpenAI Python Library
1
2
The official Python client library for the OpenAI API, providing comprehensive access to OpenAI's suite of AI models including GPT-4, DALL-E, Whisper, and Embeddings. The library features both synchronous and asynchronous implementations, complete type definitions, streaming support, structured output parsing, and integration with OpenAI's latest features including the Assistants API, Realtime API, and advanced capabilities like function calling and vision inputs.
3
4
## Package Information
5
6
- **Package Name**: openai
7
- **Language**: Python
8
- **Installation**: `pip install openai`
9
- **Python Version**: 3.9+
10
- **Official Documentation**: https://platform.openai.com/docs/api-reference
11
12
## Core Imports
13
14
```python
15
from openai import OpenAI, AsyncOpenAI
16
```
17
18
For Azure OpenAI:
19
20
```python
21
from openai import AzureOpenAI, AsyncAzureOpenAI
22
```
23
24
Common types and utilities:
25
26
```python
27
from typing import Callable, Iterable, Awaitable, Mapping, Literal, AsyncGenerator
28
import httpx
29
from openai import (
30
Stream, AsyncStream, Client, AsyncClient,
31
NOT_GIVEN, NotGiven, not_given, FileTypes, Omit, omit,
32
AssistantEventHandler, AsyncAssistantEventHandler,
33
HttpxBinaryResponseContent, RequestOptions, Timeout,
34
APIResponse, AsyncAPIResponse, WebsocketConnectionOptions
35
)
36
from openai.types.chat import (
37
ChatCompletion,
38
ChatCompletionMessage,
39
ChatCompletionMessageParam,
40
ChatCompletionToolUnionParam,
41
ChatCompletionToolChoiceOptionParam,
42
completion_create_params,
43
)
44
from openai.pagination import (
45
SyncPage, AsyncPage,
46
SyncCursorPage, AsyncCursorPage,
47
SyncConversationCursorPage, AsyncConversationCursorPage
48
)
49
50
# Helpers for audio recording and playback
51
from openai.helpers import Microphone, LocalAudioPlayer
52
53
# Access all type definitions
54
from openai import types
55
# Examples: types.ChatCompletion, types.Embedding, types.FileObject
56
# Use types.chat.ChatCompletionMessageParam for nested types
57
```
58
59
## Basic Usage
60
61
```python
62
from openai import OpenAI
63
64
# Initialize the client
65
client = OpenAI(api_key="your-api-key")
66
67
# Create a chat completion
68
response = client.chat.completions.create(
69
model="gpt-4",
70
messages=[
71
{"role": "system", "content": "You are a helpful assistant."},
72
{"role": "user", "content": "Hello!"}
73
]
74
)
75
76
print(response.choices[0].message.content)
77
78
# Async usage
79
import asyncio
80
from openai import AsyncOpenAI
81
82
async def main():
83
client = AsyncOpenAI(api_key="your-api-key")
84
response = await client.chat.completions.create(
85
model="gpt-4",
86
messages=[{"role": "user", "content": "Hello!"}]
87
)
88
print(response.choices[0].message.content)
89
90
asyncio.run(main())
91
```
92
93
## Module-Level Configuration
94
95
The library supports a legacy module-level configuration pattern for backward compatibility. You can configure the default client by setting module-level variables:
96
97
```python
98
import openai
99
100
# API Configuration
101
openai.api_key = "your-api-key"
102
openai.organization = "org-xxx"
103
openai.project = "proj-xxx"
104
openai.webhook_secret = "whsec_xxx"
105
106
# Network Configuration
107
openai.base_url = "https://api.openai.com/v1"
108
openai.timeout = 60.0 # seconds
109
openai.max_retries = 3
110
openai.default_headers = {"Custom-Header": "value"}
111
openai.default_query = {"custom_param": "value"}
112
openai.http_client = custom_httpx_client
113
114
# Azure OpenAI Configuration
115
openai.api_type = "azure" # "openai" or "azure"
116
openai.api_version = "2024-02-01"
117
openai.azure_endpoint = "https://your-resource.openai.azure.com"
118
openai.azure_ad_token = "your-ad-token"
119
openai.azure_ad_token_provider = lambda: get_token()
120
121
# After setting these, you can use module-level methods:
122
# (This pattern is deprecated; prefer explicit client instantiation)
123
```
124
125
**Note**: The module-level configuration pattern is legacy. For new code, prefer explicit client instantiation:
126
127
```python
128
from openai import OpenAI
129
130
client = OpenAI(
131
api_key="your-api-key",
132
organization="org-xxx",
133
timeout=60.0
134
)
135
```
136
137
## Architecture
138
139
The OpenAI Python library is structured around client-resource architecture:
140
141
- **Clients**: `OpenAI`, `AsyncOpenAI`, `AzureOpenAI`, `AsyncAzureOpenAI` - Entry points for API access with configuration
142
- **Resources**: Organized API endpoints (chat, audio, images, files, etc.) accessible as client attributes
143
- **Types**: Comprehensive Pydantic models for all requests and responses with full type safety
144
- **Streaming**: First-class streaming support via `Stream` and `AsyncStream` classes
145
- **Error Handling**: Structured exception hierarchy for different error types
146
147
The library provides both synchronous and asynchronous implementations for all operations, enabling integration into any Python application architecture.
148
149
## Capabilities
150
151
### Client Initialization
152
153
Initialize OpenAI clients with API credentials and configuration options for both OpenAI and Azure OpenAI services.
154
155
```python { .api }
156
class OpenAI:
157
"""Synchronous client for OpenAI API."""
158
def __init__(
159
self,
160
*,
161
api_key: str | None | Callable[[], str] = None,
162
organization: str | None = None,
163
project: str | None = None,
164
webhook_secret: str | None = None,
165
base_url: str | None = None,
166
websocket_base_url: str | httpx.URL | None = None,
167
timeout: float | httpx.Timeout | None | NotGiven = not_given,
168
max_retries: int = 2,
169
default_headers: Mapping[str, str] | None = None,
170
default_query: Mapping[str, object] | None = None,
171
http_client: httpx.Client | None = None,
172
): ...
173
174
class AsyncOpenAI:
175
"""Asynchronous client for OpenAI API."""
176
def __init__(
177
self,
178
*,
179
api_key: str | None | Callable[[], Awaitable[str]] = None,
180
organization: str | None = None,
181
project: str | None = None,
182
webhook_secret: str | None = None,
183
base_url: str | None = None,
184
websocket_base_url: str | httpx.URL | None = None,
185
timeout: float | httpx.Timeout | None | NotGiven = not_given,
186
max_retries: int = 2,
187
default_headers: Mapping[str, str] | None = None,
188
default_query: Mapping[str, object] | None = None,
189
http_client: httpx.AsyncClient | None = None,
190
): ...
191
192
class AzureOpenAI:
193
"""Synchronous client for Azure OpenAI Service."""
194
def __init__(
195
self,
196
*,
197
api_version: str | None = None,
198
azure_endpoint: str | None = None,
199
azure_deployment: str | None = None,
200
api_key: str | None | Callable[[], str] = None,
201
azure_ad_token: str | None = None,
202
azure_ad_token_provider: Callable[[], str] | None = None,
203
organization: str | None = None,
204
project: str | None = None,
205
webhook_secret: str | None = None,
206
base_url: str | None = None,
207
websocket_base_url: str | httpx.URL | None = None,
208
timeout: float | httpx.Timeout | None | NotGiven = not_given,
209
max_retries: int = 2,
210
default_headers: Mapping[str, str] | None = None,
211
default_query: Mapping[str, object] | None = None,
212
http_client: httpx.Client | None = None,
213
): ...
214
215
class AsyncAzureOpenAI:
216
"""Asynchronous client for Azure OpenAI Service."""
217
def __init__(
218
self,
219
*,
220
api_version: str | None = None,
221
azure_endpoint: str | None = None,
222
azure_deployment: str | None = None,
223
api_key: str | None | Callable[[], Awaitable[str]] = None,
224
azure_ad_token: str | None = None,
225
azure_ad_token_provider: Callable[[], Awaitable[str] | str] | None = None,
226
organization: str | None = None,
227
project: str | None = None,
228
webhook_secret: str | None = None,
229
base_url: str | None = None,
230
websocket_base_url: str | httpx.URL | None = None,
231
timeout: float | httpx.Timeout | None | NotGiven = not_given,
232
max_retries: int = 2,
233
default_headers: Mapping[str, str] | None = None,
234
default_query: Mapping[str, object] | None = None,
235
http_client: httpx.AsyncClient | None = None,
236
): ...
237
238
# Aliases for convenience
239
Client = OpenAI
240
AsyncClient = AsyncOpenAI
241
```
242
243
[Client Initialization](./client-initialization.md)
244
245
### Chat Completions
246
247
Create conversational responses using OpenAI's language models with support for text, function calling, vision inputs, audio, and structured output parsing.
248
249
```python { .api }
250
def create(
251
self,
252
*,
253
messages: Iterable[ChatCompletionMessageParam],
254
model: str | ChatModel,
255
audio: dict | Omit = omit,
256
frequency_penalty: float | Omit = omit,
257
function_call: str | dict | Omit = omit,
258
functions: Iterable[dict] | Omit = omit,
259
logit_bias: dict[str, int] | Omit = omit,
260
logprobs: bool | Omit = omit,
261
top_logprobs: int | Omit = omit,
262
max_completion_tokens: int | Omit = omit,
263
max_tokens: int | Omit = omit,
264
metadata: dict[str, str] | Omit = omit,
265
modalities: list[Literal["text", "audio"]] | Omit = omit,
266
n: int | Omit = omit,
267
parallel_tool_calls: bool | Omit = omit,
268
prediction: dict | Omit = omit,
269
presence_penalty: float | Omit = omit,
270
prompt_cache_key: str | Omit = omit,
271
prompt_cache_retention: Literal["in-memory", "24h"] | Omit = omit,
272
reasoning_effort: str | Omit = omit,
273
response_format: completion_create_params.ResponseFormat | Omit = omit,
274
safety_identifier: str | Omit = omit,
275
seed: int | Omit = omit,
276
service_tier: Literal["auto", "default", "flex", "scale", "priority"] | Omit = omit,
277
stop: str | list[str] | Omit = omit,
278
store: bool | Omit = omit,
279
stream: bool | Omit = omit,
280
stream_options: dict | Omit = omit,
281
temperature: float | Omit = omit,
282
tool_choice: ChatCompletionToolChoiceOptionParam | Omit = omit,
283
tools: Iterable[ChatCompletionToolUnionParam] | Omit = omit,
284
top_p: float | Omit = omit,
285
user: str | Omit = omit,
286
verbosity: Literal["low", "medium", "high"] | Omit = omit,
287
web_search_options: dict | Omit = omit,
288
extra_headers: dict[str, str] | None = None,
289
extra_query: dict[str, object] | None = None,
290
extra_body: dict[str, object] | None = None,
291
timeout: float | httpx.Timeout | None | NotGiven = not_given,
292
) -> ChatCompletion | Stream[ChatCompletionChunk]: ...
293
294
def parse(
295
self,
296
*,
297
messages: Iterable[ChatCompletionMessageParam],
298
model: str | ChatModel,
299
response_format: Type[BaseModel],
300
**kwargs
301
) -> ParsedChatCompletion: ...
302
```
303
304
[Chat Completions](./chat-completions.md)
305
306
### Text Completions
307
308
Generate text completions using legacy completion models.
309
310
```python { .api }
311
def create(
312
self,
313
*,
314
model: str,
315
prompt: str | list[str] | list[int] | list[list[int]],
316
best_of: int | None = None,
317
echo: bool | None = None,
318
frequency_penalty: float | None = None,
319
logit_bias: dict[str, int] | None = None,
320
logprobs: int | None = None,
321
max_tokens: int | None = None,
322
n: int | None = None,
323
presence_penalty: float | None = None,
324
seed: int | None = None,
325
stop: str | list[str] | None = None,
326
stream_options: Optional[ChatCompletionStreamOptionsParam] | Omit = omit,
327
stream: bool | None = None,
328
suffix: str | None = None,
329
temperature: float | None = None,
330
top_p: float | None = None,
331
user: str | None = None,
332
extra_headers: dict[str, str] | None = None,
333
extra_query: dict[str, object] | None = None,
334
extra_body: dict[str, object] | None = None,
335
timeout: float | None = None,
336
) -> Completion | Stream[Completion]: ...
337
```
338
339
[Text Completions](./completions.md)
340
341
### Embeddings
342
343
Create vector embeddings for text inputs to use in semantic search, clustering, and other ML applications.
344
345
```python { .api }
346
def create(
347
self,
348
*,
349
input: str | list[str] | list[int] | list[list[int]],
350
model: str | EmbeddingModel,
351
dimensions: int | Omit = omit,
352
encoding_format: Literal["float", "base64"] | Omit = omit,
353
user: str | Omit = omit,
354
extra_headers: Mapping[str, str] | None = None,
355
extra_query: Mapping[str, object] | None = None,
356
extra_body: dict[str, object] | None = None,
357
timeout: float | httpx.Timeout | None | NotGiven = not_given,
358
) -> CreateEmbeddingResponse: ...
359
```
360
361
[Embeddings](./embeddings.md)
362
363
### Audio
364
365
Convert audio to text (transcription and translation) and text to speech using Whisper and TTS models.
366
367
```python { .api }
368
# Transcription
369
def create(
370
self,
371
*,
372
file: FileTypes,
373
model: str | AudioModel,
374
chunking_strategy: Optional[dict] | Omit = omit,
375
include: list[str] | Omit = omit,
376
language: str | None = None,
377
prompt: str | None = None,
378
response_format: str | None = None,
379
stream: bool | Omit = omit,
380
temperature: float | None = None,
381
timestamp_granularities: list[str] | None = None,
382
extra_headers: dict[str, str] | None = None,
383
extra_query: dict[str, object] | None = None,
384
extra_body: dict[str, object] | None = None,
385
timeout: float | None = None,
386
) -> Transcription | TranscriptionVerbose | TranscriptionDiarized: ...
387
388
# Translation
389
def create(
390
self,
391
*,
392
file: FileTypes,
393
model: str | AudioModel,
394
prompt: str | None = None,
395
response_format: str | None = None,
396
temperature: float | None = None,
397
extra_headers: dict[str, str] | None = None,
398
extra_query: dict[str, object] | None = None,
399
extra_body: dict[str, object] | None = None,
400
timeout: float | None = None,
401
) -> Translation | TranslationVerbose: ...
402
403
# Text-to-Speech
404
def create(
405
self,
406
*,
407
input: str,
408
model: str | SpeechModel,
409
voice: str,
410
instructions: str | Omit = omit,
411
response_format: str | None = None,
412
speed: float | None = None,
413
stream_format: Literal["sse", "audio"] | Omit = omit,
414
extra_headers: dict[str, str] | None = None,
415
extra_query: dict[str, object] | None = None,
416
extra_body: dict[str, object] | None = None,
417
timeout: float | None = None,
418
) -> HttpxBinaryResponseContent: ...
419
```
420
421
[Audio](./audio.md)
422
423
### Images
424
425
Generate, edit, and create variations of images using DALL-E models.
426
427
```python { .api }
428
def generate(
429
self,
430
*,
431
prompt: str,
432
background: Literal["transparent", "opaque", "auto"] | None | Omit = omit,
433
model: str | ImageModel | None = None,
434
moderation: Literal["low", "auto"] | None | Omit = omit,
435
n: int | None = None,
436
output_compression: int | None | Omit = omit,
437
output_format: Literal["png", "jpeg", "webp"] | None | Omit = omit,
438
partial_images: int | None | Omit = omit,
439
quality: str | None = None,
440
response_format: str | None = None,
441
size: str | None = None,
442
stream: bool | None | Omit = omit,
443
style: str | None = None,
444
user: str | None = None,
445
extra_headers: dict[str, str] | None = None,
446
extra_query: dict[str, object] | None = None,
447
extra_body: dict[str, object] | None = None,
448
timeout: float | None = None,
449
) -> ImagesResponse: ...
450
451
def edit(
452
self,
453
*,
454
image: FileTypes | list[FileTypes],
455
prompt: str,
456
background: Literal["transparent", "opaque", "auto"] | None | Omit = omit,
457
input_fidelity: Literal["high", "low"] | None | Omit = omit,
458
mask: FileTypes | None = None,
459
model: str | ImageModel | None = None,
460
n: int | None = None,
461
output_compression: int | None | Omit = omit,
462
output_format: Literal["png", "jpeg", "webp"] | None | Omit = omit,
463
partial_images: int | None | Omit = omit,
464
quality: Literal["standard", "low", "medium", "high", "auto"] | None | Omit = omit,
465
response_format: str | None = None,
466
size: str | None = None,
467
stream: bool | None | Omit = omit,
468
user: str | None = None,
469
extra_headers: dict[str, str] | None = None,
470
extra_query: dict[str, object] | None = None,
471
extra_body: dict[str, object] | None = None,
472
timeout: float | None = None,
473
) -> ImagesResponse: ...
474
475
def create_variation(
476
self,
477
*,
478
image: FileTypes,
479
model: str | ImageModel | None = None,
480
n: int | None = None,
481
response_format: str | None = None,
482
size: str | None = None,
483
user: str | None = None,
484
extra_headers: dict[str, str] | None = None,
485
extra_query: dict[str, object] | None = None,
486
extra_body: dict[str, object] | None = None,
487
timeout: float | None = None,
488
) -> ImagesResponse: ...
489
```
490
491
[Images](./images.md)
492
493
### Videos
494
495
Generate and manipulate videos using video generation models.
496
497
```python { .api }
498
def create(
499
self,
500
*,
501
prompt: str,
502
input_reference: FileTypes | Omit = omit,
503
model: VideoModel | Omit = omit,
504
seconds: VideoSeconds | Omit = omit,
505
size: VideoSize | Omit = omit,
506
extra_headers: dict[str, str] | None = None,
507
extra_query: dict[str, object] | None = None,
508
extra_body: dict[str, object] | None = None,
509
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
510
) -> Video: ...
511
512
def create_and_poll(
513
self,
514
*,
515
prompt: str,
516
input_reference: FileTypes | Omit = omit,
517
model: VideoModel | Omit = omit,
518
seconds: VideoSeconds | Omit = omit,
519
size: VideoSize | Omit = omit,
520
poll_interval_ms: int | Omit = omit,
521
extra_headers: dict[str, str] | None = None,
522
extra_query: dict[str, object] | None = None,
523
extra_body: dict[str, object] | None = None,
524
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
525
) -> Video: ...
526
527
def poll(
528
self,
529
video_id: str,
530
*,
531
poll_interval_ms: int | Omit = omit,
532
extra_headers: dict[str, str] | None = None,
533
extra_query: dict[str, object] | None = None,
534
extra_body: dict[str, object] | None = None,
535
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
536
) -> Video: ...
537
538
def retrieve(
539
self,
540
video_id: str,
541
*,
542
extra_headers: dict[str, str] | None = None,
543
extra_query: dict[str, object] | None = None,
544
extra_body: dict[str, object] | None = None,
545
timeout: float | None = None,
546
) -> Video: ...
547
548
def list(
549
self,
550
*,
551
after: str | Omit = omit,
552
limit: int | Omit = omit,
553
order: Literal["asc", "desc"] | Omit = omit,
554
extra_headers: dict[str, str] | None = None,
555
extra_query: dict[str, object] | None = None,
556
extra_body: dict[str, object] | None = None,
557
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
558
) -> SyncCursorPage[Video]: ...
559
560
def delete(
561
self,
562
video_id: str,
563
*,
564
extra_headers: dict[str, str] | None = None,
565
extra_query: dict[str, object] | None = None,
566
extra_body: dict[str, object] | None = None,
567
timeout: float | None = None,
568
) -> VideoDeleteResponse: ...
569
570
def download_content(
571
self,
572
video_id: str,
573
*,
574
extra_headers: dict[str, str] | None = None,
575
extra_query: dict[str, object] | None = None,
576
extra_body: dict[str, object] | None = None,
577
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
578
) -> HttpxBinaryResponseContent: ...
579
580
def remix(
581
self,
582
video_id: str,
583
*,
584
prompt: str,
585
seconds: VideoSeconds | Omit = omit,
586
extra_headers: dict[str, str] | None = None,
587
extra_query: dict[str, object] | None = None,
588
extra_body: dict[str, object] | None = None,
589
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
590
) -> Video: ...
591
```
592
593
[Videos](./videos.md)
594
595
### Files
596
597
Upload and manage files for use with various OpenAI features like Assistants, Fine-tuning, and Batch processing.
598
599
```python { .api }
600
def create(
601
self,
602
*,
603
file: FileTypes,
604
purpose: str | FilePurpose,
605
extra_headers: dict[str, str] | None = None,
606
extra_query: dict[str, object] | None = None,
607
extra_body: dict[str, object] | None = None,
608
timeout: float | None = None,
609
) -> FileObject: ...
610
611
def retrieve(
612
self,
613
file_id: str,
614
*,
615
extra_headers: dict[str, str] | None = None,
616
extra_query: dict[str, object] | None = None,
617
extra_body: dict[str, object] | None = None,
618
timeout: float | None = None,
619
) -> FileObject: ...
620
621
def list(
622
self,
623
*,
624
purpose: str | None = None,
625
limit: int | None = None,
626
order: str | None = None,
627
after: str | None = None,
628
extra_headers: dict[str, str] | None = None,
629
extra_query: dict[str, object] | None = None,
630
extra_body: dict[str, object] | None = None,
631
timeout: float | None = None,
632
) -> SyncPage[FileObject]: ...
633
634
def delete(
635
self,
636
file_id: str,
637
*,
638
extra_headers: dict[str, str] | None = None,
639
extra_query: dict[str, object] | None = None,
640
extra_body: dict[str, object] | None = None,
641
timeout: float | None = None,
642
) -> FileDeleted: ...
643
644
def content(
645
self,
646
file_id: str,
647
*,
648
extra_headers: dict[str, str] | None = None,
649
extra_query: dict[str, object] | None = None,
650
extra_body: dict[str, object] | None = None,
651
timeout: float | None = None,
652
) -> HttpxBinaryResponseContent: ...
653
654
def retrieve_content(
655
self,
656
file_id: str,
657
*,
658
extra_headers: dict[str, str] | None = None,
659
extra_query: dict[str, object] | None = None,
660
extra_body: dict[str, object] | None = None,
661
timeout: float | None = None,
662
) -> HttpxBinaryResponseContent: ...
663
664
def wait_for_processing(
665
self,
666
file_id: str,
667
*,
668
poll_interval: float = 5.0,
669
max_wait: float = 3600.0,
670
) -> FileObject: ...
671
```
672
673
[Files](./files.md)
674
675
### Uploads
676
677
Upload large files in chunks for use with Assistants and other features. Upload parts are managed through the `.parts` subresource.
678
679
```python { .api }
680
def create(
681
self,
682
*,
683
bytes: int,
684
filename: str,
685
mime_type: str,
686
purpose: FilePurpose,
687
expires_after: dict | Omit = omit,
688
extra_headers: dict[str, str] | None = None,
689
extra_query: dict[str, object] | None = None,
690
extra_body: dict[str, object] | None = None,
691
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
692
) -> Upload: ...
693
694
def complete(
695
self,
696
upload_id: str,
697
*,
698
part_ids: list[str],
699
md5: str | Omit = omit,
700
extra_headers: dict[str, str] | None = None,
701
extra_query: dict[str, object] | None = None,
702
extra_body: dict[str, object] | None = None,
703
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
704
) -> Upload: ...
705
706
def cancel(
707
self,
708
upload_id: str,
709
*,
710
extra_headers: dict[str, str] | None = None,
711
extra_query: dict[str, object] | None = None,
712
extra_body: dict[str, object] | None = None,
713
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
714
) -> Upload: ...
715
716
def upload_file_chunked(
717
self,
718
*,
719
file: str | os.PathLike | bytes,
720
mime_type: str,
721
purpose: FilePurpose,
722
filename: str | None = None,
723
bytes: int | None = None,
724
part_size: int | None = None,
725
md5: str | Omit = omit,
726
) -> Upload: ...
727
728
# Access via client.uploads.parts
729
def create(
730
self,
731
upload_id: str,
732
*,
733
data: FileTypes,
734
extra_headers: dict[str, str] | None = None,
735
extra_query: dict[str, object] | None = None,
736
extra_body: dict[str, object] | None = None,
737
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
738
) -> UploadPart: ...
739
```
740
741
[Uploads](./uploads.md)
742
743
### Models
744
745
Retrieve information about available models and manage fine-tuned models.
746
747
```python { .api }
748
def retrieve(
749
self,
750
model: str,
751
*,
752
extra_headers: dict[str, str] | None = None,
753
extra_query: dict[str, object] | None = None,
754
extra_body: dict[str, object] | None = None,
755
timeout: float | None = None,
756
) -> Model: ...
757
758
def list(
759
self,
760
*,
761
extra_headers: dict[str, str] | None = None,
762
extra_query: dict[str, object] | None = None,
763
extra_body: dict[str, object] | None = None,
764
timeout: float | None = None,
765
) -> SyncPage[Model]: ...
766
767
def delete(
768
self,
769
model: str,
770
*,
771
extra_headers: dict[str, str] | None = None,
772
extra_query: dict[str, object] | None = None,
773
extra_body: dict[str, object] | None = None,
774
timeout: float | None = None,
775
) -> ModelDeleted: ...
776
```
777
778
[Models](./models.md)
779
780
### Fine-tuning
781
782
Create and manage fine-tuning jobs to customize models on your own data. Fine-tuning operations are accessed through the `.jobs` and `.checkpoints` subresources.
783
784
```python { .api }
785
# Access via client.fine_tuning.jobs
786
def create(
787
self,
788
*,
789
model: str,
790
training_file: str,
791
hyperparameters: dict | None = None,
792
method: dict | None = None,
793
integrations: list[dict] | None = None,
794
seed: int | None = None,
795
suffix: str | None = None,
796
validation_file: str | None = None,
797
extra_headers: dict[str, str] | None = None,
798
extra_query: dict[str, object] | None = None,
799
extra_body: dict[str, object] | None = None,
800
timeout: float | None = None,
801
) -> FineTuningJob: ...
802
803
def retrieve(
804
self,
805
fine_tuning_job_id: str,
806
*,
807
extra_headers: dict[str, str] | None = None,
808
extra_query: dict[str, object] | None = None,
809
extra_body: dict[str, object] | None = None,
810
timeout: float | None = None,
811
) -> FineTuningJob: ...
812
813
def list(
814
self,
815
*,
816
after: str | None = None,
817
limit: int | None = None,
818
extra_headers: dict[str, str] | None = None,
819
extra_query: dict[str, object] | None = None,
820
extra_body: dict[str, object] | None = None,
821
timeout: float | None = None,
822
) -> SyncCursorPage[FineTuningJob]: ...
823
824
def cancel(
825
self,
826
fine_tuning_job_id: str,
827
*,
828
extra_headers: dict[str, str] | None = None,
829
extra_query: dict[str, object] | None = None,
830
extra_body: dict[str, object] | None = None,
831
timeout: float | None = None,
832
) -> FineTuningJob: ...
833
834
def pause(
835
self,
836
fine_tuning_job_id: str,
837
*,
838
extra_headers: dict[str, str] | None = None,
839
extra_query: dict[str, object] | None = None,
840
extra_body: dict[str, object] | None = None,
841
timeout: float | None = None,
842
) -> FineTuningJob: ...
843
844
def resume(
845
self,
846
fine_tuning_job_id: str,
847
*,
848
extra_headers: dict[str, str] | None = None,
849
extra_query: dict[str, object] | None = None,
850
extra_body: dict[str, object] | None = None,
851
timeout: float | None = None,
852
) -> FineTuningJob: ...
853
854
def list_events(
855
self,
856
fine_tuning_job_id: str,
857
*,
858
after: str | None = None,
859
limit: int | None = None,
860
extra_headers: dict[str, str] | None = None,
861
extra_query: dict[str, object] | None = None,
862
extra_body: dict[str, object] | None = None,
863
timeout: float | None = None,
864
) -> SyncCursorPage[FineTuningJobEvent]: ...
865
866
# Access via client.fine_tuning.checkpoints
867
def list(
868
self,
869
fine_tuning_job_id: str,
870
*,
871
after: str | None = None,
872
limit: int | None = None,
873
extra_headers: dict[str, str] | None = None,
874
extra_query: dict[str, object] | None = None,
875
extra_body: dict[str, object] | None = None,
876
timeout: float | None = None,
877
) -> SyncCursorPage[FineTuningJobCheckpoint]: ...
878
```
879
880
[Fine-tuning](./fine-tuning.md)
881
882
### Moderations
883
884
Check content against OpenAI's usage policies to detect potentially harmful content.
885
886
```python { .api }
887
def create(
888
self,
889
*,
890
input: str | list[str],
891
model: str | ModerationModel | None = None,
892
extra_headers: dict[str, str] | None = None,
893
extra_query: dict[str, object] | None = None,
894
extra_body: dict[str, object] | None = None,
895
timeout: float | None = None,
896
) -> ModerationCreateResponse: ...
897
```
898
899
[Moderations](./moderations.md)
900
901
### Batch Processing
902
903
Submit batch requests for asynchronous processing of multiple API calls.
904
905
```python { .api }
906
def create(
907
self,
908
*,
909
completion_window: str,
910
endpoint: str,
911
input_file_id: str,
912
metadata: dict[str, str] | None = None,
913
extra_headers: dict[str, str] | None = None,
914
extra_query: dict[str, object] | None = None,
915
extra_body: dict[str, object] | None = None,
916
timeout: float | None = None,
917
) -> Batch: ...
918
919
def retrieve(
920
self,
921
batch_id: str,
922
*,
923
extra_headers: dict[str, str] | None = None,
924
extra_query: dict[str, object] | None = None,
925
extra_body: dict[str, object] | None = None,
926
timeout: float | None = None,
927
) -> Batch: ...
928
929
def list(
930
self,
931
*,
932
after: str | None = None,
933
limit: int | None = None,
934
extra_headers: dict[str, str] | None = None,
935
extra_query: dict[str, object] | None = None,
936
extra_body: dict[str, object] | None = None,
937
timeout: float | None = None,
938
) -> SyncCursorPage[Batch]: ...
939
940
def cancel(
941
self,
942
batch_id: str,
943
*,
944
extra_headers: dict[str, str] | None = None,
945
extra_query: dict[str, object] | None = None,
946
extra_body: dict[str, object] | None = None,
947
timeout: float | None = None,
948
) -> Batch: ...
949
```
950
951
[Batch Processing](./batches.md)
952
953
### Vector Stores
954
955
Create and manage vector stores for semantic search and retrieval with the Assistants API. Vector store files are managed through the `.files` subresource, and file batches through the `.file_batches` subresource.
956
957
```python { .api }
958
def create(
959
self,
960
*,
961
file_ids: list[str] | None = None,
962
name: str | None = None,
963
expires_after: dict | None = None,
964
chunking_strategy: dict | None = None,
965
metadata: dict[str, str] | None = None,
966
extra_headers: dict[str, str] | None = None,
967
extra_query: dict[str, object] | None = None,
968
extra_body: dict[str, object] | None = None,
969
timeout: float | None = None,
970
) -> VectorStore: ...
971
972
def retrieve(
973
self,
974
vector_store_id: str,
975
*,
976
extra_headers: dict[str, str] | None = None,
977
extra_query: dict[str, object] | None = None,
978
extra_body: dict[str, object] | None = None,
979
timeout: float | None = None,
980
) -> VectorStore: ...
981
982
def update(
983
self,
984
vector_store_id: str,
985
*,
986
name: str | None = None,
987
expires_after: dict | None = None,
988
metadata: dict[str, str] | None = None,
989
extra_headers: dict[str, str] | None = None,
990
extra_query: dict[str, object] | None = None,
991
extra_body: dict[str, object] | None = None,
992
timeout: float | None = None,
993
) -> VectorStore: ...
994
995
def list(
996
self,
997
*,
998
after: str | None = None,
999
before: str | None = None,
1000
limit: int | None = None,
1001
order: str | None = None,
1002
extra_headers: dict[str, str] | None = None,
1003
extra_query: dict[str, object] | None = None,
1004
extra_body: dict[str, object] | None = None,
1005
timeout: float | None = None,
1006
) -> SyncCursorPage[VectorStore]: ...
1007
1008
def delete(
1009
self,
1010
vector_store_id: str,
1011
*,
1012
extra_headers: dict[str, str] | None = None,
1013
extra_query: dict[str, object] | None = None,
1014
extra_body: dict[str, object] | None = None,
1015
timeout: float | None = None,
1016
) -> VectorStoreDeleted: ...
1017
1018
def search(
1019
self,
1020
vector_store_id: str,
1021
*,
1022
query: str,
1023
limit: int | None = None,
1024
filter: dict | None = None,
1025
extra_headers: dict[str, str] | None = None,
1026
extra_query: dict[str, object] | None = None,
1027
extra_body: dict[str, object] | None = None,
1028
timeout: float | None = None,
1029
) -> VectorStoreSearchResponse: ...
1030
1031
# Access via client.vector_stores.files
1032
def create(
1033
self,
1034
vector_store_id: str,
1035
*,
1036
file_id: str,
1037
chunking_strategy: dict | None = None,
1038
extra_headers: dict[str, str] | None = None,
1039
extra_query: dict[str, object] | None = None,
1040
extra_body: dict[str, object] | None = None,
1041
timeout: float | None = None,
1042
) -> VectorStoreFile: ...
1043
1044
def retrieve(
1045
self,
1046
vector_store_id: str,
1047
file_id: str,
1048
*,
1049
extra_headers: dict[str, str] | None = None,
1050
extra_query: dict[str, object] | None = None,
1051
extra_body: dict[str, object] | None = None,
1052
timeout: float | None = None,
1053
) -> VectorStoreFile: ...
1054
1055
def list(
1056
self,
1057
vector_store_id: str,
1058
*,
1059
after: str | None = None,
1060
before: str | None = None,
1061
filter: str | None = None,
1062
limit: int | None = None,
1063
order: str | None = None,
1064
extra_headers: dict[str, str] | None = None,
1065
extra_query: dict[str, object] | None = None,
1066
extra_body: dict[str, object] | None = None,
1067
timeout: float | None = None,
1068
) -> SyncCursorPage[VectorStoreFile]: ...
1069
1070
def delete(
1071
self,
1072
vector_store_id: str,
1073
file_id: str,
1074
*,
1075
extra_headers: dict[str, str] | None = None,
1076
extra_query: dict[str, object] | None = None,
1077
extra_body: dict[str, object] | None = None,
1078
timeout: float | None = None,
1079
) -> VectorStoreFileDeleted: ...
1080
1081
# Access via client.vector_stores.file_batches
1082
def create(
1083
self,
1084
vector_store_id: str,
1085
*,
1086
file_ids: list[str],
1087
chunking_strategy: dict | None = None,
1088
extra_headers: dict[str, str] | None = None,
1089
extra_query: dict[str, object] | None = None,
1090
extra_body: dict[str, object] | None = None,
1091
timeout: float | None = None,
1092
) -> VectorStoreFileBatch: ...
1093
1094
def retrieve(
1095
self,
1096
vector_store_id: str,
1097
batch_id: str,
1098
*,
1099
extra_headers: dict[str, str] | None = None,
1100
extra_query: dict[str, object] | None = None,
1101
extra_body: dict[str, object] | None = None,
1102
timeout: float | None = None,
1103
) -> VectorStoreFileBatch: ...
1104
1105
def cancel(
1106
self,
1107
vector_store_id: str,
1108
batch_id: str,
1109
*,
1110
extra_headers: dict[str, str] | None = None,
1111
extra_query: dict[str, object] | None = None,
1112
extra_body: dict[str, object] | None = None,
1113
timeout: float | None = None,
1114
) -> VectorStoreFileBatch: ...
1115
1116
def list_files(
1117
self,
1118
vector_store_id: str,
1119
batch_id: str,
1120
*,
1121
after: str | None = None,
1122
before: str | None = None,
1123
filter: str | None = None,
1124
limit: int | None = None,
1125
order: str | None = None,
1126
extra_headers: dict[str, str] | None = None,
1127
extra_query: dict[str, object] | None = None,
1128
extra_body: dict[str, object] | None = None,
1129
timeout: float | None = None,
1130
) -> SyncCursorPage[VectorStoreFile]: ...
1131
```
1132
1133
[Vector Stores](./vector-stores.md)
1134
1135
### Assistants API (Beta)
1136
1137
Build AI assistants with advanced capabilities including code interpreter, file search, and function calling.
1138
1139
```python { .api }
1140
def create(
1141
self,
1142
*,
1143
model: str,
1144
description: str | None = None,
1145
instructions: str | None = None,
1146
metadata: dict[str, str] | None = None,
1147
name: str | None = None,
1148
response_format: dict | None = None,
1149
temperature: float | None = None,
1150
tool_resources: dict | None = None,
1151
tools: list[dict] | None = None,
1152
top_p: float | None = None,
1153
extra_headers: dict[str, str] | None = None,
1154
extra_query: dict[str, object] | None = None,
1155
extra_body: dict[str, object] | None = None,
1156
timeout: float | None = None,
1157
) -> Assistant: ...
1158
1159
def retrieve(
1160
self,
1161
assistant_id: str,
1162
*,
1163
extra_headers: dict[str, str] | None = None,
1164
extra_query: dict[str, object] | None = None,
1165
extra_body: dict[str, object] | None = None,
1166
timeout: float | None = None,
1167
) -> Assistant: ...
1168
1169
def update(
1170
self,
1171
assistant_id: str,
1172
*,
1173
description: str | None = None,
1174
instructions: str | None = None,
1175
metadata: dict[str, str] | None = None,
1176
model: str | None = None,
1177
name: str | None = None,
1178
response_format: dict | None = None,
1179
temperature: float | None = None,
1180
tool_resources: dict | None = None,
1181
tools: list[dict] | None = None,
1182
top_p: float | None = None,
1183
extra_headers: dict[str, str] | None = None,
1184
extra_query: dict[str, object] | None = None,
1185
extra_body: dict[str, object] | None = None,
1186
timeout: float | None = None,
1187
) -> Assistant: ...
1188
1189
def list(
1190
self,
1191
*,
1192
after: str | Omit = omit,
1193
before: str | Omit = omit,
1194
limit: int | Omit = omit,
1195
order: Literal["asc", "desc"] | Omit = omit,
1196
extra_headers: dict[str, str] | None = None,
1197
extra_query: dict[str, object] | None = None,
1198
extra_body: dict[str, object] | None = None,
1199
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1200
) -> SyncCursorPage[Assistant]: ...
1201
1202
def delete(
1203
self,
1204
assistant_id: str,
1205
*,
1206
extra_headers: dict[str, str] | None = None,
1207
extra_query: dict[str, object] | None = None,
1208
extra_body: dict[str, object] | None = None,
1209
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1210
) -> AssistantDeleted: ...
1211
```
1212
1213
[Assistants API](./assistants.md)
1214
1215
### Threads and Messages (Beta)
1216
1217
Create conversational threads and manage messages within the Assistants API.
1218
1219
```python { .api }
1220
# Threads
1221
def create(
1222
self,
1223
*,
1224
messages: list[dict] | None = None,
1225
metadata: dict[str, str] | None = None,
1226
tool_resources: dict | None = None,
1227
extra_headers: dict[str, str] | None = None,
1228
extra_query: dict[str, object] | None = None,
1229
extra_body: dict[str, object] | None = None,
1230
timeout: float | None = None,
1231
) -> Thread: ...
1232
1233
def retrieve(
1234
self,
1235
thread_id: str,
1236
*,
1237
extra_headers: dict[str, str] | None = None,
1238
extra_query: dict[str, object] | None = None,
1239
extra_body: dict[str, object] | None = None,
1240
timeout: float | None = None,
1241
) -> Thread: ...
1242
1243
def update(
1244
self,
1245
thread_id: str,
1246
*,
1247
metadata: dict[str, str] | None = None,
1248
tool_resources: dict | None = None,
1249
extra_headers: dict[str, str] | None = None,
1250
extra_query: dict[str, object] | None = None,
1251
extra_body: dict[str, object] | None = None,
1252
timeout: float | None = None,
1253
) -> Thread: ...
1254
1255
def delete(
1256
self,
1257
thread_id: str,
1258
*,
1259
extra_headers: dict[str, str] | None = None,
1260
extra_query: dict[str, object] | None = None,
1261
extra_body: dict[str, object] | None = None,
1262
timeout: float | None = None,
1263
) -> ThreadDeleted: ...
1264
1265
def create_and_run(
1266
self,
1267
*,
1268
assistant_id: str,
1269
instructions: str | None = None,
1270
metadata: dict[str, str] | None = None,
1271
model: str | None = None,
1272
thread: dict | None = None,
1273
tools: list[dict] | None = None,
1274
extra_headers: dict[str, str] | None = None,
1275
extra_query: dict[str, object] | None = None,
1276
extra_body: dict[str, object] | None = None,
1277
timeout: float | None = None,
1278
) -> Run: ...
1279
1280
def create_and_run_poll(
1281
self,
1282
*,
1283
assistant_id: str,
1284
poll_interval_ms: int | None = None,
1285
instructions: str | None = None,
1286
metadata: dict[str, str] | None = None,
1287
model: str | None = None,
1288
thread: dict | None = None,
1289
tools: list[dict] | None = None,
1290
extra_headers: dict[str, str] | None = None,
1291
extra_query: dict[str, object] | None = None,
1292
extra_body: dict[str, object] | None = None,
1293
timeout: float | None = None,
1294
) -> Run: ...
1295
1296
def create_and_run_stream(
1297
self,
1298
*,
1299
assistant_id: str,
1300
event_handler: AssistantEventHandler | None = None,
1301
instructions: str | None = None,
1302
metadata: dict[str, str] | None = None,
1303
model: str | None = None,
1304
thread: dict | None = None,
1305
tools: list[dict] | None = None,
1306
extra_headers: dict[str, str] | None = None,
1307
extra_query: dict[str, object] | None = None,
1308
extra_body: dict[str, object] | None = None,
1309
timeout: float | None = None,
1310
) -> AssistantStreamManager: ...
1311
1312
# Messages
1313
def create(
1314
self,
1315
thread_id: str,
1316
*,
1317
role: str,
1318
content: str | list[dict],
1319
attachments: list[dict] | None = None,
1320
metadata: dict[str, str] | None = None,
1321
extra_headers: dict[str, str] | None = None,
1322
extra_query: dict[str, object] | None = None,
1323
extra_body: dict[str, object] | None = None,
1324
timeout: float | None = None,
1325
) -> Message: ...
1326
1327
def retrieve(
1328
self,
1329
thread_id: str,
1330
message_id: str,
1331
*,
1332
extra_headers: dict[str, str] | None = None,
1333
extra_query: dict[str, object] | None = None,
1334
extra_body: dict[str, object] | None = None,
1335
timeout: float | None = None,
1336
) -> Message: ...
1337
1338
def update(
1339
self,
1340
thread_id: str,
1341
message_id: str,
1342
*,
1343
metadata: dict[str, str] | None = None,
1344
extra_headers: dict[str, str] | None = None,
1345
extra_query: dict[str, object] | None = None,
1346
extra_body: dict[str, object] | None = None,
1347
timeout: float | None = None,
1348
) -> Message: ...
1349
1350
def list(
1351
self,
1352
thread_id: str,
1353
*,
1354
after: str | None = None,
1355
before: str | None = None,
1356
limit: int | None = None,
1357
order: str | None = None,
1358
run_id: str | None = None,
1359
extra_headers: dict[str, str] | None = None,
1360
extra_query: dict[str, object] | None = None,
1361
extra_body: dict[str, object] | None = None,
1362
timeout: float | None = None,
1363
) -> SyncCursorPage[Message]: ...
1364
1365
def delete(
1366
self,
1367
thread_id: str,
1368
message_id: str,
1369
*,
1370
extra_headers: dict[str, str] | None = None,
1371
extra_query: dict[str, object] | None = None,
1372
extra_body: dict[str, object] | None = None,
1373
timeout: float | None = None,
1374
) -> MessageDeleted: ...
1375
```
1376
1377
[Threads and Messages](./threads-messages.md)
1378
1379
### Runs (Beta)
1380
1381
Execute assistants on threads and handle tool calls. Run steps are managed through the `.steps` subresource.
1382
1383
```python { .api }
1384
def create(
1385
self,
1386
thread_id: str,
1387
*,
1388
assistant_id: str,
1389
additional_instructions: str | None = None,
1390
additional_messages: list[dict] | None = None,
1391
instructions: str | None = None,
1392
max_completion_tokens: int | None = None,
1393
max_prompt_tokens: int | None = None,
1394
metadata: dict[str, str] | None = None,
1395
model: str | None = None,
1396
parallel_tool_calls: bool | None = None,
1397
response_format: dict | None = None,
1398
stream: bool | None = None,
1399
temperature: float | None = None,
1400
tool_choice: str | dict | None = None,
1401
tools: list[dict] | None = None,
1402
top_p: float | None = None,
1403
truncation_strategy: dict | None = None,
1404
extra_headers: dict[str, str] | None = None,
1405
extra_query: dict[str, object] | None = None,
1406
extra_body: dict[str, object] | None = None,
1407
timeout: float | None = None,
1408
) -> Run: ...
1409
1410
def retrieve(
1411
self,
1412
thread_id: str,
1413
run_id: str,
1414
*,
1415
extra_headers: dict[str, str] | None = None,
1416
extra_query: dict[str, object] | None = None,
1417
extra_body: dict[str, object] | None = None,
1418
timeout: float | None = None,
1419
) -> Run: ...
1420
1421
def update(
1422
self,
1423
thread_id: str,
1424
run_id: str,
1425
*,
1426
metadata: dict[str, str] | None = None,
1427
extra_headers: dict[str, str] | None = None,
1428
extra_query: dict[str, object] | None = None,
1429
extra_body: dict[str, object] | None = None,
1430
timeout: float | None = None,
1431
) -> Run: ...
1432
1433
def list(
1434
self,
1435
thread_id: str,
1436
*,
1437
after: str | None = None,
1438
before: str | None = None,
1439
limit: int | None = None,
1440
order: str | None = None,
1441
extra_headers: dict[str, str] | None = None,
1442
extra_query: dict[str, object] | None = None,
1443
extra_body: dict[str, object] | None = None,
1444
timeout: float | None = None,
1445
) -> SyncCursorPage[Run]: ...
1446
1447
def cancel(
1448
self,
1449
thread_id: str,
1450
run_id: str,
1451
*,
1452
extra_headers: dict[str, str] | None = None,
1453
extra_query: dict[str, object] | None = None,
1454
extra_body: dict[str, object] | None = None,
1455
timeout: float | None = None,
1456
) -> Run: ...
1457
1458
def submit_tool_outputs(
1459
self,
1460
thread_id: str,
1461
run_id: str,
1462
*,
1463
tool_outputs: list[dict],
1464
stream: bool | None = None,
1465
extra_headers: dict[str, str] | None = None,
1466
extra_query: dict[str, object] | None = None,
1467
extra_body: dict[str, object] | None = None,
1468
timeout: float | None = None,
1469
) -> Run: ...
1470
1471
def stream(
1472
self,
1473
thread_id: str,
1474
*,
1475
assistant_id: str,
1476
event_handler: AssistantEventHandler | None = None,
1477
extra_headers: dict[str, str] | None = None,
1478
extra_query: dict[str, object] | None = None,
1479
extra_body: dict[str, object] | None = None,
1480
timeout: float | None = None,
1481
) -> AssistantStreamManager: ...
1482
1483
# Access via client.beta.threads.runs.steps
1484
def retrieve(
1485
self,
1486
thread_id: str,
1487
run_id: str,
1488
step_id: str,
1489
*,
1490
extra_headers: dict[str, str] | None = None,
1491
extra_query: dict[str, object] | None = None,
1492
extra_body: dict[str, object] | None = None,
1493
timeout: float | None = None,
1494
) -> RunStep: ...
1495
1496
def list(
1497
self,
1498
thread_id: str,
1499
run_id: str,
1500
*,
1501
after: str | None = None,
1502
before: str | None = None,
1503
limit: int | None = None,
1504
order: str | None = None,
1505
extra_headers: dict[str, str] | None = None,
1506
extra_query: dict[str, object] | None = None,
1507
extra_body: dict[str, object] | None = None,
1508
timeout: float | None = None,
1509
) -> SyncCursorPage[RunStep]: ...
1510
```
1511
1512
[Runs](./runs.md)
1513
1514
### ChatKit (Beta)
1515
1516
Simplified, high-level interface for building chat applications with session and thread management.
1517
1518
```python { .api }
1519
def create(
1520
self,
1521
*,
1522
user: str,
1523
workflow: ChatSessionWorkflowParam,
1524
chatkit_configuration: ChatSessionChatKitConfigurationParam | Omit = omit,
1525
expires_after: ChatSessionExpiresAfterParam | Omit = omit,
1526
rate_limits: ChatSessionRateLimitsParam | Omit = omit,
1527
extra_headers: dict[str, str] | None = None,
1528
extra_query: dict[str, object] | None = None,
1529
extra_body: dict[str, object] | None = None,
1530
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1531
) -> ChatSession: ...
1532
```
1533
1534
[ChatKit](./chatkit.md)
1535
1536
### Realtime API (Beta)
1537
1538
WebSocket-based realtime communication for low-latency conversational AI experiences. Realtime client secrets and calls are managed through the `.client_secrets` and `.calls` subresources.
1539
1540
```python { .api }
1541
def connect(
1542
self,
1543
*,
1544
call_id: str | Omit = omit,
1545
model: str | Omit = omit,
1546
extra_query: dict[str, object] = {},
1547
extra_headers: dict[str, str] = {},
1548
websocket_connection_options: WebsocketConnectionOptions = {},
1549
) -> RealtimeConnectionManager: ...
1550
1551
# Access via client.realtime.client_secrets
1552
def create(
1553
self,
1554
*,
1555
extra_headers: dict[str, str] | None = None,
1556
extra_query: dict[str, object] | None = None,
1557
extra_body: dict[str, object] | None = None,
1558
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1559
) -> ClientSecret: ...
1560
1561
# Access via client.realtime.calls
1562
def create(
1563
self,
1564
*,
1565
model: str,
1566
call_config: dict | None = None,
1567
extra_headers: dict[str, str] | None = None,
1568
extra_query: dict[str, object] | None = None,
1569
extra_body: dict[str, object] | None = None,
1570
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1571
) -> Call: ...
1572
1573
def retrieve(
1574
self,
1575
call_id: str,
1576
*,
1577
extra_headers: dict[str, str] | None = None,
1578
extra_query: dict[str, object] | None = None,
1579
extra_body: dict[str, object] | None = None,
1580
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1581
) -> Call: ...
1582
1583
def update(
1584
self,
1585
call_id: str,
1586
*,
1587
call_config: dict | None = None,
1588
extra_headers: dict[str, str] | None = None,
1589
extra_query: dict[str, object] | None = None,
1590
extra_body: dict[str, object] | None = None,
1591
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1592
) -> Call: ...
1593
1594
def list(
1595
self,
1596
*,
1597
after: str | Omit = omit,
1598
limit: int | Omit = omit,
1599
order: Literal["asc", "desc"] | Omit = omit,
1600
extra_headers: dict[str, str] | None = None,
1601
extra_query: dict[str, object] | None = None,
1602
extra_body: dict[str, object] | None = None,
1603
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1604
) -> SyncCursorPage[Call]: ...
1605
```
1606
1607
[Realtime API](./realtime.md)
1608
1609
### Responses API
1610
1611
Create responses with advanced tool support including computer use, file search, and code patching. Response input items and tokens are managed through the `.input_items` and `.input_tokens` subresources.
1612
1613
```python { .api }
1614
def create(
1615
self,
1616
*,
1617
model: str,
1618
input: dict | list[dict],
1619
instructions: str | None = None,
1620
metadata: dict[str, str] | None = None,
1621
parallel_tool_calls: bool | None = None,
1622
reasoning_effort: str | None = None,
1623
store: bool | None = None,
1624
stream: bool | None = None,
1625
temperature: float | None = None,
1626
tool_choice: str | dict | None = None,
1627
tools: list[dict] | None = None,
1628
top_p: float | None = None,
1629
extra_headers: dict[str, str] | None = None,
1630
extra_query: dict[str, object] | None = None,
1631
extra_body: dict[str, object] | None = None,
1632
timeout: float | None = None,
1633
) -> Response: ...
1634
1635
def stream(
1636
self,
1637
*,
1638
model: str,
1639
input: dict | list[dict],
1640
instructions: str | None = None,
1641
metadata: dict[str, str] | None = None,
1642
parallel_tool_calls: bool | None = None,
1643
reasoning_effort: str | None = None,
1644
store: bool | None = None,
1645
temperature: float | None = None,
1646
tool_choice: str | dict | None = None,
1647
tools: list[dict] | None = None,
1648
top_p: float | None = None,
1649
extra_headers: dict[str, str] | None = None,
1650
extra_query: dict[str, object] | None = None,
1651
extra_body: dict[str, object] | None = None,
1652
timeout: float | None = None,
1653
) -> Stream[ResponseStreamEvent]: ...
1654
1655
def parse(
1656
self,
1657
*,
1658
model: str,
1659
input: dict | list[dict],
1660
response_format: Type[BaseModel],
1661
instructions: str | None = None,
1662
metadata: dict[str, str] | None = None,
1663
parallel_tool_calls: bool | None = None,
1664
reasoning_effort: str | None = None,
1665
store: bool | None = None,
1666
temperature: float | None = None,
1667
tool_choice: str | dict | None = None,
1668
tools: list[dict] | None = None,
1669
top_p: float | None = None,
1670
extra_headers: dict[str, str] | None = None,
1671
extra_query: dict[str, object] | None = None,
1672
extra_body: dict[str, object] | None = None,
1673
timeout: float | None = None,
1674
) -> ParsedResponse: ...
1675
1676
def retrieve(
1677
self,
1678
response_id: str,
1679
*,
1680
extra_headers: dict[str, str] | None = None,
1681
extra_query: dict[str, object] | None = None,
1682
extra_body: dict[str, object] | None = None,
1683
timeout: float | None = None,
1684
) -> Response: ...
1685
1686
def delete(
1687
self,
1688
response_id: str,
1689
*,
1690
extra_headers: dict[str, str] | None = None,
1691
extra_query: dict[str, object] | None = None,
1692
extra_body: dict[str, object] | None = None,
1693
timeout: float | None = None,
1694
) -> ResponseDeleted: ...
1695
1696
def cancel(
1697
self,
1698
response_id: str,
1699
*,
1700
extra_headers: dict[str, str] | None = None,
1701
extra_query: dict[str, object] | None = None,
1702
extra_body: dict[str, object] | None = None,
1703
timeout: float | None = None,
1704
) -> Response: ...
1705
1706
# Access via client.responses.input_items
1707
def create(
1708
self,
1709
response_id: str,
1710
*,
1711
type: str,
1712
content: str | list[dict] | None = None,
1713
extra_headers: dict[str, str] | None = None,
1714
extra_query: dict[str, object] | None = None,
1715
extra_body: dict[str, object] | None = None,
1716
timeout: float | None = None,
1717
) -> ResponseInputItem: ...
1718
1719
def delete(
1720
self,
1721
response_id: str,
1722
item_id: str,
1723
*,
1724
extra_headers: dict[str, str] | None = None,
1725
extra_query: dict[str, object] | None = None,
1726
extra_body: dict[str, object] | None = None,
1727
timeout: float | None = None,
1728
) -> ResponseInputItemDeleted: ...
1729
1730
# Access via client.responses.input_tokens
1731
def create(
1732
self,
1733
response_id: str,
1734
*,
1735
token: str,
1736
extra_headers: dict[str, str] | None = None,
1737
extra_query: dict[str, object] | None = None,
1738
extra_body: dict[str, object] | None = None,
1739
timeout: float | None = None,
1740
) -> ResponseInputToken: ...
1741
1742
def delete(
1743
self,
1744
response_id: str,
1745
token_id: str,
1746
*,
1747
extra_headers: dict[str, str] | None = None,
1748
extra_query: dict[str, object] | None = None,
1749
extra_body: dict[str, object] | None = None,
1750
timeout: float | None = None,
1751
) -> ResponseInputTokenDeleted: ...
1752
```
1753
1754
[Responses](./responses.md)
1755
1756
### Evaluations
1757
1758
Create and manage evaluations to test model performance with custom testing criteria. Evaluation runs are managed through the `.runs` subresource.
1759
1760
```python { .api }
1761
def create(
1762
self,
1763
*,
1764
data_source_config: dict,
1765
testing_criteria: Iterable[dict],
1766
metadata: dict[str, str] | None | Omit = omit,
1767
name: str | Omit = omit,
1768
extra_headers: dict[str, str] | None = None,
1769
extra_query: dict[str, object] | None = None,
1770
extra_body: dict[str, object] | None = None,
1771
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1772
) -> Eval: ...
1773
1774
def retrieve(
1775
self,
1776
eval_id: str,
1777
*,
1778
extra_headers: dict[str, str] | None = None,
1779
extra_query: dict[str, object] | None = None,
1780
extra_body: dict[str, object] | None = None,
1781
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1782
) -> Eval: ...
1783
1784
def update(
1785
self,
1786
eval_id: str,
1787
*,
1788
metadata: dict[str, str] | None | Omit = omit,
1789
name: str | Omit = omit,
1790
extra_headers: dict[str, str] | None = None,
1791
extra_query: dict[str, object] | None = None,
1792
extra_body: dict[str, object] | None = None,
1793
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1794
) -> Eval: ...
1795
1796
def list(
1797
self,
1798
*,
1799
after: str | Omit = omit,
1800
limit: int | Omit = omit,
1801
order: Literal["asc", "desc"] | Omit = omit,
1802
order_by: Literal["created_at", "updated_at"] | Omit = omit,
1803
extra_headers: dict[str, str] | None = None,
1804
extra_query: dict[str, object] | None = None,
1805
extra_body: dict[str, object] | None = None,
1806
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1807
) -> SyncCursorPage[Eval]: ...
1808
1809
def delete(
1810
self,
1811
eval_id: str,
1812
*,
1813
extra_headers: dict[str, str] | None = None,
1814
extra_query: dict[str, object] | None = None,
1815
extra_body: dict[str, object] | None = None,
1816
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1817
) -> EvalDeleteResponse: ...
1818
1819
# Access via client.evals.runs
1820
def create(
1821
self,
1822
eval_id: str,
1823
*,
1824
extra_headers: dict[str, str] | None = None,
1825
extra_query: dict[str, object] | None = None,
1826
extra_body: dict[str, object] | None = None,
1827
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1828
) -> EvalRun: ...
1829
1830
def retrieve(
1831
self,
1832
eval_id: str,
1833
run_id: str,
1834
*,
1835
extra_headers: dict[str, str] | None = None,
1836
extra_query: dict[str, object] | None = None,
1837
extra_body: dict[str, object] | None = None,
1838
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1839
) -> EvalRun: ...
1840
1841
def list(
1842
self,
1843
eval_id: str,
1844
*,
1845
after: str | Omit = omit,
1846
limit: int | Omit = omit,
1847
order: Literal["asc", "desc"] | Omit = omit,
1848
extra_headers: dict[str, str] | None = None,
1849
extra_query: dict[str, object] | None = None,
1850
extra_body: dict[str, object] | None = None,
1851
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1852
) -> SyncCursorPage[EvalRun]: ...
1853
```
1854
1855
[Evaluations](./evals.md)
1856
1857
### Conversations
1858
1859
Create and manage conversations for structured multi-turn interactions. Conversation items are managed through the `.items` subresource.
1860
1861
```python { .api }
1862
def create(
1863
self,
1864
*,
1865
items: Iterable[dict] | None | Omit = omit,
1866
metadata: dict[str, str] | None | Omit = omit,
1867
extra_headers: dict[str, str] | None = None,
1868
extra_query: dict[str, object] | None = None,
1869
extra_body: dict[str, object] | None = None,
1870
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1871
) -> Conversation: ...
1872
1873
def retrieve(
1874
self,
1875
conversation_id: str,
1876
*,
1877
extra_headers: dict[str, str] | None = None,
1878
extra_query: dict[str, object] | None = None,
1879
extra_body: dict[str, object] | None = None,
1880
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1881
) -> Conversation: ...
1882
1883
def update(
1884
self,
1885
conversation_id: str,
1886
*,
1887
metadata: dict[str, str] | None,
1888
extra_headers: dict[str, str] | None = None,
1889
extra_query: dict[str, object] | None = None,
1890
extra_body: dict[str, object] | None = None,
1891
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1892
) -> Conversation: ...
1893
1894
def delete(
1895
self,
1896
conversation_id: str,
1897
*,
1898
extra_headers: dict[str, str] | None = None,
1899
extra_query: dict[str, object] | None = None,
1900
extra_body: dict[str, object] | None = None,
1901
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1902
) -> ConversationDeleted: ...
1903
1904
# Access via client.conversations.items
1905
def create(
1906
self,
1907
conversation_id: str,
1908
*,
1909
type: str,
1910
content: str | list[dict] | None = None,
1911
metadata: dict[str, str] | None | Omit = omit,
1912
extra_headers: dict[str, str] | None = None,
1913
extra_query: dict[str, object] | None = None,
1914
extra_body: dict[str, object] | None = None,
1915
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1916
) -> ConversationItem: ...
1917
1918
def retrieve(
1919
self,
1920
conversation_id: str,
1921
item_id: str,
1922
*,
1923
extra_headers: dict[str, str] | None = None,
1924
extra_query: dict[str, object] | None = None,
1925
extra_body: dict[str, object] | None = None,
1926
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1927
) -> ConversationItem: ...
1928
1929
def update(
1930
self,
1931
conversation_id: str,
1932
item_id: str,
1933
*,
1934
content: str | list[dict] | None = None,
1935
metadata: dict[str, str] | None | Omit = omit,
1936
extra_headers: dict[str, str] | None = None,
1937
extra_query: dict[str, object] | None = None,
1938
extra_body: dict[str, object] | None = None,
1939
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1940
) -> ConversationItem: ...
1941
1942
def list(
1943
self,
1944
conversation_id: str,
1945
*,
1946
after: str | Omit = omit,
1947
limit: int | Omit = omit,
1948
order: Literal["asc", "desc"] | Omit = omit,
1949
extra_headers: dict[str, str] | None = None,
1950
extra_query: dict[str, object] | None = None,
1951
extra_body: dict[str, object] | None = None,
1952
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1953
) -> SyncCursorPage[ConversationItem]: ...
1954
1955
def delete(
1956
self,
1957
conversation_id: str,
1958
item_id: str,
1959
*,
1960
extra_headers: dict[str, str] | None = None,
1961
extra_query: dict[str, object] | None = None,
1962
extra_body: dict[str, object] | None = None,
1963
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1964
) -> ConversationItemDeleted: ...
1965
```
1966
1967
[Conversations](./conversations.md)
1968
1969
### Containers
1970
1971
Create and manage isolated file storage containers for organizing files. Container files are managed through the `.files` subresource.
1972
1973
```python { .api }
1974
def create(
1975
self,
1976
*,
1977
name: str,
1978
expires_after: dict | Omit = omit,
1979
file_ids: list[str] | Omit = omit,
1980
extra_headers: dict[str, str] | None = None,
1981
extra_query: dict[str, object] | None = None,
1982
extra_body: dict[str, object] | None = None,
1983
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1984
) -> Container: ...
1985
1986
def retrieve(
1987
self,
1988
container_id: str,
1989
*,
1990
extra_headers: dict[str, str] | None = None,
1991
extra_query: dict[str, object] | None = None,
1992
extra_body: dict[str, object] | None = None,
1993
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
1994
) -> Container: ...
1995
1996
def list(
1997
self,
1998
*,
1999
after: str | Omit = omit,
2000
limit: int | Omit = omit,
2001
order: Literal["asc", "desc"] | Omit = omit,
2002
extra_headers: dict[str, str] | None = None,
2003
extra_query: dict[str, object] | None = None,
2004
extra_body: dict[str, object] | None = None,
2005
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
2006
) -> SyncCursorPage[Container]: ...
2007
2008
def delete(
2009
self,
2010
container_id: str,
2011
*,
2012
extra_headers: dict[str, str] | None = None,
2013
extra_query: dict[str, object] | None = None,
2014
extra_body: dict[str, object] | None = None,
2015
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
2016
) -> None: ...
2017
2018
# Access via client.containers.files
2019
def create(
2020
self,
2021
container_id: str,
2022
*,
2023
file: FileTypes,
2024
purpose: str,
2025
extra_headers: dict[str, str] | None = None,
2026
extra_query: dict[str, object] | None = None,
2027
extra_body: dict[str, object] | None = None,
2028
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
2029
) -> ContainerFile: ...
2030
2031
def retrieve(
2032
self,
2033
container_id: str,
2034
file_id: str,
2035
*,
2036
extra_headers: dict[str, str] | None = None,
2037
extra_query: dict[str, object] | None = None,
2038
extra_body: dict[str, object] | None = None,
2039
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
2040
) -> ContainerFile: ...
2041
2042
def list(
2043
self,
2044
container_id: str,
2045
*,
2046
after: str | Omit = omit,
2047
limit: int | Omit = omit,
2048
order: Literal["asc", "desc"] | Omit = omit,
2049
extra_headers: dict[str, str] | None = None,
2050
extra_query: dict[str, object] | None = None,
2051
extra_body: dict[str, object] | None = None,
2052
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
2053
) -> SyncCursorPage[ContainerFile]: ...
2054
2055
def delete(
2056
self,
2057
container_id: str,
2058
file_id: str,
2059
*,
2060
extra_headers: dict[str, str] | None = None,
2061
extra_query: dict[str, object] | None = None,
2062
extra_body: dict[str, object] | None = None,
2063
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
2064
) -> ContainerFileDeleted: ...
2065
```
2066
2067
[Containers](./containers.md)
2068
2069
### Webhooks
2070
2071
Verify and handle webhook events from OpenAI for asynchronous notifications.
2072
2073
```python { .api }
2074
def verify_signature(
2075
payload: str | bytes,
2076
headers: dict[str, str] | list[tuple[str, str]],
2077
*,
2078
secret: str | None = None,
2079
tolerance: int = 300
2080
) -> None: ...
2081
2082
def unwrap(
2083
payload: str | bytes,
2084
headers: dict[str, str] | list[tuple[str, str]],
2085
*,
2086
secret: str | None = None
2087
) -> UnwrapWebhookEvent: ...
2088
```
2089
2090
[Webhooks](./webhooks.md)
2091
2092
## Response Wrappers
2093
2094
All resources support response wrapper patterns for accessing raw HTTP responses or streaming responses without loading them into memory.
2095
2096
### Raw Response Access
2097
2098
Access the underlying `httpx.Response` object for any API call:
2099
2100
```python
2101
from openai import OpenAI
2102
2103
client = OpenAI()
2104
2105
# Use .with_raw_response prefix
2106
response = client.with_raw_response.chat.completions.create(
2107
model="gpt-4",
2108
messages=[{"role": "user", "content": "Hello!"}]
2109
)
2110
2111
# Access parsed response
2112
completion = response.parsed
2113
2114
# Access raw HTTP response
2115
http_response = response.http_response
2116
print(f"Status: {http_response.status_code}")
2117
print(f"Headers: {http_response.headers}")
2118
print(f"Raw content: {http_response.content}")
2119
```
2120
2121
Available on all resources:
2122
2123
```python
2124
client.with_raw_response.chat.completions.create(...)
2125
client.with_raw_response.audio.transcriptions.create(...)
2126
client.with_raw_response.images.generate(...)
2127
# ... and all other resources
2128
```
2129
2130
### Streaming Response Access
2131
2132
Stream responses without loading them into memory, useful for large responses:
2133
2134
```python
2135
response = client.with_streaming_response.files.content("file-abc123")
2136
2137
# Stream chunks
2138
for chunk in response.iter_bytes():
2139
process_chunk(chunk)
2140
2141
# Or write directly to file
2142
with open("output.txt", "wb") as f:
2143
for chunk in response.iter_bytes():
2144
f.write(chunk)
2145
```
2146
2147
Available on all resources:
2148
2149
```python
2150
client.with_streaming_response.chat.completions.create(...)
2151
client.with_streaming_response.files.content(...)
2152
# ... and all other resources
2153
```
2154
2155
Both patterns work with async clients:
2156
2157
```python
2158
from openai import AsyncOpenAI
2159
2160
client = AsyncOpenAI()
2161
2162
# Raw response (async)
2163
response = await client.with_raw_response.chat.completions.create(...)
2164
2165
# Streaming response (async)
2166
response = await client.with_streaming_response.files.content("file-abc123")
2167
async for chunk in response.iter_bytes():
2168
process_chunk(chunk)
2169
```
2170
2171
## Error Handling
2172
2173
The library provides a comprehensive exception hierarchy for handling different error scenarios:
2174
2175
```python { .api }
2176
class OpenAIError(Exception):
2177
"""Base exception for all OpenAI errors."""
2178
2179
class APIError(OpenAIError):
2180
"""Base for API-related errors."""
2181
2182
class APIStatusError(APIError):
2183
"""HTTP status code errors (4xx, 5xx)."""
2184
status_code: int
2185
response: httpx.Response
2186
body: object
2187
2188
class APITimeoutError(APIError):
2189
"""Request timeout errors."""
2190
2191
class APIConnectionError(APIError):
2192
"""Connection errors."""
2193
2194
class APIResponseValidationError(APIError):
2195
"""Response validation errors."""
2196
2197
class BadRequestError(APIStatusError):
2198
"""400 Bad Request."""
2199
2200
class AuthenticationError(APIStatusError):
2201
"""401 Authentication error."""
2202
2203
class PermissionDeniedError(APIStatusError):
2204
"""403 Permission denied."""
2205
2206
class NotFoundError(APIStatusError):
2207
"""404 Not found."""
2208
2209
class ConflictError(APIStatusError):
2210
"""409 Conflict."""
2211
2212
class UnprocessableEntityError(APIStatusError):
2213
"""422 Unprocessable Entity."""
2214
2215
class RateLimitError(APIStatusError):
2216
"""429 Rate limit exceeded."""
2217
2218
class InternalServerError(APIStatusError):
2219
"""500+ Server errors."""
2220
2221
class LengthFinishReasonError(OpenAIError):
2222
"""Raised when completion stops due to reaching max tokens."""
2223
2224
class ContentFilterFinishReasonError(OpenAIError):
2225
"""Raised when completion stops due to content filtering."""
2226
2227
class InvalidWebhookSignatureError(OpenAIError):
2228
"""Raised when webhook signature verification fails."""
2229
```
2230
2231
## Common Types
2232
2233
```python { .api }
2234
# Sentinel values for omitted parameters
2235
NOT_GIVEN: Omit # Sentinel indicating parameter was not provided
2236
not_given: Omit # Alias for NOT_GIVEN (lowercase convention)
2237
2238
# Omit type for optional API parameters
2239
# Use Omit type with omit default value instead of None for optional parameters
2240
# This distinguishes between "parameter not provided" vs "parameter set to null"
2241
Omit: TypeAlias # Type for omittable parameters
2242
omit: Omit # Sentinel value for omitted parameters
2243
2244
# Type utilities
2245
NoneType: Type[None] # Used for response casting when no response expected
2246
2247
# Common type aliases
2248
# File upload types - can be specified in multiple formats:
2249
# - Raw file content (bytes, file object, etc.)
2250
# - (filename, content) tuple
2251
# - (filename, content, mime_type) tuple
2252
FileTypes = Union[
2253
FileContent, # Just the file bytes/buffer
2254
Tuple[Optional[str], FileContent], # (filename, content)
2255
Tuple[Optional[str], FileContent, Optional[str]] # (filename, content, mime_type)
2256
]
2257
2258
# Timeout can be a float (seconds) or an httpx.Timeout object for fine-grained control
2259
Timeout = Union[float, httpx.Timeout]
2260
2261
# Azure AD Token Provider
2262
# Callable that returns Azure AD tokens for authentication with Azure OpenAI
2263
# Can be sync or async function
2264
AzureADTokenProvider = Callable[[], str] | Callable[[], Awaitable[str]]
2265
2266
# Default configuration constants
2267
DEFAULT_TIMEOUT: httpx.Timeout # Default timeout: 600s total, 5s connect
2268
DEFAULT_MAX_RETRIES: int # Default maximum retries: 2
2269
DEFAULT_CONNECTION_LIMITS: httpx.Limits # Default connection limits: 1000 max connections, 100 keepalive
2270
2271
# Type aliases for specific domains
2272
VideoModel = Literal["sora-2", "sora-2-pro"]
2273
VideoSeconds = int # Duration in seconds
2274
VideoSize = str # e.g., "720x1280"
2275
2276
# Request configuration
2277
class RequestOptions(TypedDict, total=False):
2278
"""Options for individual API requests."""
2279
extra_headers: dict[str, str]
2280
extra_query: dict[str, object]
2281
extra_body: dict[str, object]
2282
timeout: float | httpx.Timeout
2283
2284
# WebSocket configuration for Realtime API
2285
class WebsocketConnectionOptions(TypedDict, total=False):
2286
"""WebSocket connection options for realtime API connections."""
2287
extensions: Sequence[ClientExtensionFactory] | None # List of supported extensions
2288
subprotocols: Sequence[Subprotocol] | None # List of supported subprotocols
2289
compression: str | None # Compression setting ("permessage-deflate" enabled by default, None to disable)
2290
max_size: int | None # Maximum size of incoming messages in bytes
2291
max_queue: int | None | tuple[int | None, int | None] # High-water mark of receive buffer
2292
write_limit: int | tuple[int, int | None] # High-water mark of write buffer in bytes
2293
2294
# Response wrappers
2295
class HttpxBinaryResponseContent:
2296
"""Binary response content for audio, images, etc."""
2297
content: bytes
2298
response: httpx.Response
2299
def read(self) -> bytes: ...
2300
def write_to_file(self, file: str | os.PathLike) -> None: ...
2301
2302
# Pagination types
2303
class SyncPage[T]:
2304
"""Standard pagination."""
2305
data: list[T]
2306
object: str
2307
def __iter__(self) -> Iterator[T]: ...
2308
def __next__(self) -> T: ...
2309
2310
class AsyncPage[T]:
2311
"""Async pagination."""
2312
data: list[T]
2313
object: str
2314
def __aiter__(self) -> AsyncIterator[T]: ...
2315
def __anext__(self) -> T: ...
2316
2317
class SyncCursorPage[T]:
2318
"""Cursor-based pagination."""
2319
data: list[T]
2320
has_more: bool
2321
def __iter__(self) -> Iterator[T]: ...
2322
def __next__(self) -> T: ...
2323
2324
class AsyncCursorPage[T]:
2325
"""Async cursor-based pagination."""
2326
data: list[T]
2327
has_more: bool
2328
def __aiter__(self) -> AsyncIterator[T]: ...
2329
def __anext__(self) -> T: ...
2330
2331
class SyncConversationCursorPage[T]:
2332
"""Conversation cursor-based pagination."""
2333
data: list[T]
2334
has_more: bool
2335
last_id: str | None
2336
def __iter__(self) -> Iterator[T]: ...
2337
def __next__(self) -> T: ...
2338
2339
class AsyncConversationCursorPage[T]:
2340
"""Async conversation cursor-based pagination."""
2341
data: list[T]
2342
has_more: bool
2343
last_id: str | None
2344
def __aiter__(self) -> AsyncIterator[T]: ...
2345
def __anext__(self) -> T: ...
2346
2347
# Streaming types
2348
class Stream[T]:
2349
"""Synchronous streaming."""
2350
def __iter__(self) -> Iterator[T]: ...
2351
def __next__(self) -> T: ...
2352
def __enter__(self) -> Stream[T]: ...
2353
def __exit__(self, *args) -> None: ...
2354
def close(self) -> None: ...
2355
2356
class AsyncStream[T]:
2357
"""Asynchronous streaming."""
2358
def __aiter__(self) -> AsyncIterator[T]: ...
2359
def __anext__(self) -> T: ...
2360
async def __aenter__(self) -> AsyncStream[T]: ...
2361
async def __aexit__(self, *args) -> None: ...
2362
async def close(self) -> None: ...
2363
```
2364
2365
## Helper Utilities
2366
2367
```python { .api }
2368
# Package Information
2369
__title__: str # Package name ("openai")
2370
VERSION: str # Library version string
2371
__version__: str # Library version (same as VERSION)
2372
2373
# Pydantic Base Model
2374
BaseModel # Base class for creating custom Pydantic models (from pydantic import BaseModel)
2375
2376
# HTTP Client Classes
2377
class DefaultHttpxClient:
2378
"""Default synchronous httpx client with connection pooling."""
2379
2380
class DefaultAsyncHttpxClient:
2381
"""Default asynchronous httpx client with connection pooling."""
2382
2383
class DefaultAioHttpClient:
2384
"""Alternative async HTTP client using aiohttp."""
2385
2386
# Additional Type Exports
2387
Transport: type # HTTP transport type (httpx.BaseTransport)
2388
ProxiesTypes: type # Proxy configuration type
2389
2390
# File and Function Utilities
2391
def file_from_path(path: str) -> FileTypes:
2392
"""
2393
Load a file from filesystem path for upload to OpenAI API.
2394
2395
Args:
2396
path: Filesystem path to the file
2397
2398
Returns:
2399
FileTypes: A (filename, content, mime_type) tuple suitable for API upload
2400
"""
2401
2402
def pydantic_function_tool(
2403
model: Type[BaseModel],
2404
*,
2405
name: str | None = None,
2406
description: str | None = None
2407
) -> ChatCompletionToolParam:
2408
"""
2409
Create a function tool definition from a Pydantic model for use with chat completions.
2410
2411
Args:
2412
model: Pydantic model class defining the function parameters schema
2413
name: Optional function name (defaults to model class name in snake_case)
2414
description: Optional function description (defaults to model docstring)
2415
2416
Returns:
2417
ChatCompletionToolParam: A tool definition dict with 'type' and 'function' keys.
2418
Type from openai.types.chat module.
2419
Can be passed to chat.completions.create(tools=[...])
2420
"""
2421
2422
class AssistantEventHandler:
2423
"""Base class for handling assistant streaming events."""
2424
def on_event(self, event) -> None: ...
2425
def on_run_step_created(self, run_step) -> None: ...
2426
def on_run_step_done(self, run_step) -> None: ...
2427
def on_tool_call_created(self, tool_call) -> None: ...
2428
def on_tool_call_done(self, tool_call) -> None: ...
2429
def on_message_created(self, message) -> None: ...
2430
def on_message_done(self, message) -> None: ...
2431
def on_text_created(self, text) -> None: ...
2432
def on_text_delta(self, delta, snapshot) -> None: ...
2433
def on_text_done(self, text) -> None: ...
2434
2435
class AsyncAssistantEventHandler:
2436
"""Base class for handling assistant streaming events asynchronously."""
2437
async def on_event(self, event) -> None: ...
2438
async def on_run_step_created(self, run_step) -> None: ...
2439
async def on_run_step_done(self, run_step) -> None: ...
2440
async def on_tool_call_created(self, tool_call) -> None: ...
2441
async def on_tool_call_done(self, tool_call) -> None: ...
2442
async def on_message_created(self, message) -> None: ...
2443
async def on_message_done(self, message) -> None: ...
2444
async def on_text_created(self, text) -> None: ...
2445
async def on_text_delta(self, delta, snapshot) -> None: ...
2446
async def on_text_done(self, text) -> None: ...
2447
2448
# Audio Recording Helper
2449
class Microphone(Generic[DType]):
2450
"""
2451
Microphone helper for recording audio input from default audio device.
2452
2453
Requires optional dependencies: numpy, sounddevice
2454
Install with: pip install openai[voice_helpers]
2455
2456
Type Parameters:
2457
DType: numpy dtype for audio data (default: np.int16)
2458
"""
2459
def __init__(
2460
self,
2461
channels: int = 1,
2462
dtype: Type[DType] = np.int16,
2463
should_record: Callable[[], bool] | None = None,
2464
timeout: float | None = None,
2465
):
2466
"""
2467
Initialize microphone for recording.
2468
2469
Args:
2470
channels: Number of audio channels (1 for mono, 2 for stereo)
2471
dtype: Numpy data type for audio samples
2472
should_record: Optional callback function that returns True while recording should continue
2473
timeout: Maximum recording duration in seconds (None for unlimited)
2474
"""
2475
2476
async def record(
2477
self,
2478
return_ndarray: bool | None = False
2479
) -> npt.NDArray[DType] | FileTypes:
2480
"""
2481
Record audio from microphone.
2482
2483
Args:
2484
return_ndarray: If True, return numpy array; if False, return WAV file tuple
2485
2486
Returns:
2487
Either a numpy array of audio samples or FileTypes tuple (filename, buffer, mime_type)
2488
suitable for passing to OpenAI API methods.
2489
"""
2490
2491
# Audio Playback Helper
2492
class LocalAudioPlayer:
2493
"""
2494
Local audio player for playing audio content through default audio device.
2495
2496
Requires optional dependencies: numpy, sounddevice
2497
Install with: pip install openai[voice_helpers]
2498
2499
The player uses a fixed sample rate of 24000 Hz, 1 channel (mono), and float32 dtype.
2500
"""
2501
def __init__(
2502
self,
2503
should_stop: Callable[[], bool] | None = None,
2504
):
2505
"""
2506
Initialize audio player.
2507
2508
Args:
2509
should_stop: Optional callback function that returns True to stop playback
2510
"""
2511
2512
async def play(
2513
self,
2514
input: npt.NDArray[np.int16] | npt.NDArray[np.float32] | HttpxBinaryResponseContent | AsyncStreamedBinaryAPIResponse | StreamedBinaryAPIResponse
2515
) -> None:
2516
"""
2517
Play audio data through local audio device.
2518
2519
Args:
2520
input: Audio data as numpy array (int16 or float32) or response content from TTS API
2521
"""
2522
2523
async def play_stream(
2524
self,
2525
buffer_stream: AsyncGenerator[npt.NDArray[np.float32] | npt.NDArray[np.int16] | None, None]
2526
) -> None:
2527
"""
2528
Stream and play audio data as it arrives.
2529
2530
Useful for playing streaming audio responses from realtime API.
2531
2532
Args:
2533
buffer_stream: Async generator yielding audio buffers (numpy arrays) or None to signal completion
2534
"""
2535
```
2536