openai

Provides a synchronous OpenAI client class that wraps the Chat Completions API with full Pydantic-based type definitions for all request parameters and response models. The SDK is generated from OpenAI's OpenAPI specification using Stainless, enabling compile-time type checking and IDE autocomplete for all parameters (model, temperature, max_tokens, tools, etc.). Requests are validated against Pydantic schemas before transmission, and responses are automatically deserialized into typed Python objects with nested model support for complex structures like tool calls and function definitions.

Provides AsyncOpenAI client with native async/await support for streaming chat completions, returning an async iterator that yields server-sent events (SSE) as they arrive. The implementation uses httpx's async HTTP client with chunked transfer encoding to stream tokens in real-time without buffering the entire response. Each streamed chunk is parsed into typed ServerSentEvent objects, and the SDK provides convenience methods to extract delta content and tool calls from the stream, enabling token-by-token processing for real-time UI updates or token counting.

Implements a sophisticated retry mechanism at the HTTP client level that automatically retries failed requests with exponential backoff, jitter, and rate-limit awareness. The SDK detects rate-limit errors (429 status), timeout errors, and transient failures (5xx), then retries with configurable max attempts and backoff strategy. Respects Retry-After headers from the API and implements jitter to prevent thundering herd problems. The retry logic is transparent to the caller — failed requests are automatically retried without explicit error handling code.

Provides automatic pagination for list endpoints (e.g., list messages, list files, list fine-tuning jobs) that return large result sets. The SDK abstracts away cursor/offset management and provides a unified iterator interface that automatically fetches the next page when needed. Supports both limit-offset and cursor-based pagination depending on the endpoint, and provides convenience methods to iterate over all results or fetch a specific page. The implementation handles page size configuration and automatically retries failed page fetches.

Provides utility functions to verify webhook signatures from OpenAI, ensuring that incoming webhook events are authentic and have not been tampered with. The SDK uses HMAC-SHA256 to verify the signature header against the webhook payload and a secret key, and provides a convenience function that validates the timestamp to prevent replay attacks. Supports both raw webhook verification and integration with web frameworks (Flask, FastAPI, etc.).

Allows users to provide custom httpx.Client or httpx.AsyncClient instances to the OpenAI client, enabling fine-grained control over HTTP behavior including proxy configuration, custom headers, SSL/TLS settings, and connection pooling. The SDK accepts a custom_client parameter that replaces the default HTTP client, allowing integration with corporate proxies, custom certificate authorities, or specialized network configurations. Supports both synchronous and asynchronous custom clients.

Provides a specialized AzureOpenAI client that integrates with Microsoft Azure's OpenAI service, handling Azure-specific authentication (API keys, managed identities, Azure AD tokens) and endpoint configuration. The SDK automatically maps OpenAI model names to Azure deployment names, manages Azure-specific headers and authentication flows, and provides the same API surface as the standard OpenAI client. Supports both key-based and token-based authentication, with automatic token refresh for managed identities.

Implements parsed responses capability that automatically validates and deserializes chat completion responses against a provided Pydantic model or JSON schema. When response_format={'type': 'json_schema', 'json_schema': {...}} is specified, the SDK enforces that the model returns valid JSON matching the schema, then automatically parses the response into the provided Python type. This enables type-safe extraction of structured data (e.g., extracting entities, classifications, or complex nested objects) with automatic validation and error handling for malformed responses.

Provides a schema-based function calling system that converts Python functions or Pydantic models into OpenAI tool definitions, handles tool call responses from the model, and provides utilities for executing called functions. The SDK automatically generates JSON schemas from function signatures and type hints, manages the tool_calls list in responses, and provides helpers to extract and invoke the called functions. Supports both function definitions (for stateless calls) and tool objects with nested schemas for complex multi-step interactions.

Provides a high-level Assistants API client that manages stateful conversations through Thread objects, automatically handling message history, run execution, and response streaming. The SDK abstracts away the complexity of creating threads, appending messages, polling run status, and retrieving results. Supports streaming assistant events (on_message_created, on_text_delta, on_tool_call_created) for real-time UI updates, and handles file uploads and retrieval for document-based assistants. The implementation uses polling with exponential backoff for run completion and provides convenience methods to extract final messages from completed runs.

Provides a fine-tuning API client that manages the full lifecycle of fine-tuning jobs: uploading training/validation files, submitting fine-tuning jobs with hyperparameter configuration, polling job status, and retrieving the resulting model ID. The SDK handles file format validation (JSONL), automatic retry on transient failures, and provides convenience methods to list jobs and check completion status. Supports both standard fine-tuning and custom hyperparameter tuning with validation set evaluation.

Provides an embeddings API client that converts text or token sequences into dense vector representations using OpenAI's embedding models. The SDK handles batching of inputs (up to 2048 per request), automatic retry on rate limits, and returns Embedding objects with vector data and usage statistics. Supports both single and batch embedding generation with configurable models (text-embedding-3-small, text-embedding-3-large) and encoding formats (float, base64).

Provides audio API clients for transcribing and translating audio files using Whisper models. The SDK handles file upload, format detection (MP3, WAV, M4A, FLAC, etc.), and returns transcription/translation results with optional timestamp granularity (segment or word-level). Supports both synchronous and asynchronous operations, with streaming transcription for real-time speech-to-text applications. The implementation uses multipart form-data for file uploads and provides convenience methods to extract text or structured results with timing information.

Provides image generation API client that creates images from text prompts using DALL-E 3 or DALL-E 2 models. The SDK handles prompt submission, configurable image sizes (256x256, 512x512, 1024x1024, 1024x1792, 1792x1024), quality settings (standard, hd), and style options (natural, vivid). Returns Image objects with URLs or base64-encoded image data, and supports batch generation of multiple variations. The implementation manages API rate limits and provides convenience methods to download or save generated images.

Provides vision capability within chat completions that allows models to analyze images and answer questions about them. The SDK accepts images as URLs or base64-encoded data within message content, automatically formats them for the API, and returns text responses analyzing the image. Supports multiple image formats (JPEG, PNG, GIF, WebP) and image detail levels (low, high, auto) for controlling token usage. Works seamlessly with chat completions — images are just another content type in the messages list.