type-safe synchronous chat completions with ide autocomplete
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.
Unique: Generated from OpenAPI spec using Stainless, ensuring 100% API coverage and automatic sync with OpenAI API changes; Pydantic v1/v2 compatibility layer allows seamless upgrades without breaking existing code
vs alternatives: More type-safe and IDE-friendly than raw httpx or requests-based clients; automatically stays in sync with OpenAI API changes via spec-driven generation
asynchronous streaming chat completions with event iteration
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.
Unique: Uses httpx's native async streaming with automatic SSE parsing; provides delta reassembly helpers for tool calls that arrive fragmented across multiple stream events
vs alternatives: True async/await support without callback hell; automatic event parsing vs manual SSE line-by-line parsing in raw httpx
automatic retry with exponential backoff and rate-limit handling
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.
Unique: Exponential backoff with jitter and Retry-After header respect; transparent to caller — retries happen automatically without explicit error handling
vs alternatives: More sophisticated than simple retry loops; automatic rate-limit detection vs manual status code checking
pagination with automatic cursor management for list endpoints
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.
Unique: Unified iterator interface for both cursor-based and limit-offset pagination; automatic page fetching on iteration
vs alternatives: Simpler than manual pagination loops; automatic cursor management vs tracking offsets manually
webhook signature verification for event authenticity
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.).
Unique: HMAC-SHA256 verification with automatic timestamp validation; convenience functions for common web frameworks
vs alternatives: More secure than manual signature checking; built-in replay attack prevention vs implementing timestamp validation manually
custom http client and proxy configuration for network control
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.
Unique: Accepts custom httpx client for full HTTP control; supports both sync and async clients with same interface
vs alternatives: More flexible than hardcoded proxy support; allows any httpx customization vs limited built-in proxy options
azure openai client with managed identity and endpoint configuration
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.
Unique: Automatic model-to-deployment mapping; supports both API key and managed identity authentication with automatic token refresh
vs alternatives: Simpler than raw Azure API calls; unified interface with standard OpenAI client vs separate Azure SDK
structured output parsing with json schema validation
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.
Unique: Integrates Pydantic schema generation with OpenAI's json_schema mode; provides automatic type coercion and field validation using PropertyInfo metadata for fine-grained control over serialization
vs alternatives: More reliable than post-hoc JSON parsing with regex or manual validation; schema-driven approach ensures LLM compliance at generation time vs catching errors after the fact
+7 more capabilities