pypi / openai
openai
What changed in openai 2 to 3, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
16 breaking6 security3 deprecations138 new APIs and options1 performance10 behavior and defaults113 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initopenai 3157 changes
Breaking changes 4
Errors raised while reading streams are normalized.
Usage APIs were updated; developers using usage endpoints may need to adjust their code.
The
httpxpackage is no longer installed automatically, so applications that need it must account for that dependency themselves.HTTPX2 is now the default HTTP client; applications using custom HTTPX clients, transports, or configuration objects must migrate to HTTPX2 equivalents or use the temporary legacy HTTPX escape hatch.
Security 4
Adds expiration controls for service account keys.
Hardens the X.509 workload identity integration.
Preserves Azure authentication boundaries across transports.
Applies consistent origin checks to WebSocket redirects.
Deprecations 2
Deprecates the MCP connector_id field.
The Sora video APIs are deprecated.
New APIs and options 67
Adds typed Live sideband events for developers using the Live API.
Adds the ultrafast service tier for Agents.
Adds support for Realtime Translation WebSocket sessions.
Image requests and responses now include safety identifiers.
Supports audio fixture playback in Live sessions.
Adds cache settings and key options to the API.
Adds support for creating voices from prompts.
Adds options for regional processing residency.
Adds response error diagnostics.
Adds browser and computer toolsets for developers to use.
Adds beta session spending limits.
Exposes image tool error and moderation details.
Adds support for image URLs and detailed safety alert explanations.
Adds support for OCI as an external-storage provider.
Adds support for updating project API key expiry.
Adds the billing_not_active session error code.
Adds metadata filters.
Adds API support for suspending and expiring agent environments.
Adds standalone Decisions support to the API.
The API adds agent turn items.
Typed function helpers now support tool search with defer_loading=true.
Local tool failures can now be observed.
The API adds usage source grouping.
Adds agent session events.
Adds custom voice creation.
Chat Completions now allow original image detail.
The API adds session traces and Realtime translations.
Agents can stage files and download turn artifacts.
Session streams can return typed answers.
Typed application actions can be exposed as agent tools.
Adds the GPT-6.1 Sol model identifier for developers to use when selecting a model.
Adds credential and session options for Agents.
Adds Cyber access programs to Responses.
Allows opting in to incremental WebSocket text and tool snapshots.
Adds support for GCP external storage.
Adds the GPT-Rosalind research model.
Adds GPT-6 Sol and Luna model identifiers for developers to use.
Adds support for using environment variable vault credentials.
Adds API support for managing external storage configurations.
Adds support for retrieving safety cases.
Adds webhook events for safety warnings and deactivation.
Adds events for session environment resets.
Adds SIP media security information to incoming call events.
Adds webhook endpoint management.
Adds model settings for agent sessions.
Adds audio-mini model choices.
Adds events for tracking compaction progress.
Adds managed Responses WebSocket sessions.
Adds the Agents API to the OpenAI Python library.
Adds aclose() to AsyncStream for standard async cleanup.
Adds the Live API.
Adds image options for developers to use.
Adds expiration fields for service-account API keys.
Adds prompt cache diagnostics for developers to inspect prompt caching.
Adds gpt-6-astra and related API features.
Adds compute_units to Responses and Chat Completions usage.
Adds an obfuscation field to ChatCompletionChunk.
Adds cost quantity units.
Adds project residency configuration.
The SDK supports named data-residency endpoints.
Adds support for using the Bedrock Runtime endpoint.
Adds new service and image types.
Adds streaming events for shell calls.
Structured MCP errors are added.
WebSocket errors are added.
WebSocket stream IDs are added to the API.
An event for an issued workload identity access token is added.
Performance 1
Avoids repeated NumPy checks for embeddings.
Behavior and default changes 7
Adds a degraded status for external storage.
Aligns beta pagination limits.
Local tools can now run during streamed session creation.
Beta Agents streams collect their final output.
Supports standard logging levels through OPENAI_LOG.
Function call output no longer requires a call ID.
WebSocket events are separated.
Fixes and other changes 72
Preserves beta Realtime byte reads when using websockets 13.
Preserves byte receives when using websockets 13.
The Decisions cache breakpoint parameter type is now shared.
Supports Decisions in Live sessions.
Adds model notices.
Declares Realtime response error messages.
Restores async HTTP/1.1 connection reuse for streaming.
Adds organization Decisions usage reporting.
Aligns beta non-null parameters.
Adds shida to the named Live voices.
Adds vault updates.
Adds prewarmed hosted environments.
Corrected the parameters for custom voice creation.
type_to_response_format_param is now publicly exported.
Prioritizes routing fields in parse helpers.
Prioritizes Python request routing fields.
Corrects the endpoint used to cancel an eval run.
File processing timeouts use a monotonic clock.
Reconnects now respect send queue limits.
Reconnects no longer replay uncertain typed sends.
WebSocket endpoint paths and query parameters are retained.
Corrected the error message shown when authentication is missing.
Fixed transformation of NotRequired typed dictionary fields.
Computer use is now available to beta agents.
Preserves base URL queries in realtime WebSocket upgrades.
Preserves caller queues and prevents uncertain WebSocket replay in live sessions.
Retains configured queues without replaying attempted sends in realtime sessions.
Avoids hangs at fractional transcript grouping deadlines in live sessions.
Retries TLS transport errors that are not mapped.
Preserves detailed WebSocket accumulator snapshots.
Keeps query parameters out of live WebSocket endpoint paths.
Preserve single files when using fallback extraction paths.
Merges HTTP headers case-insensitively.
Preserves single-pass tool iterables when using chat completions.
Tolerates older optional aiohttp installations.
Propagates __api_exclude__ through recursive asynchronous transformation.
Handles omission markers in queued WebSocket events.
Retries only requests whose content can be replayed.
Preserves model choices.
Corrects model types.
Treats null message content as empty when parsing a response.
Dropped TextFormatT parameterization in parse_response to fix a memory leak.
Unrelated API resources are no longer loaded on first use.
Preserves moderation results in chat streams.
Adds prompt-cache prewarming.
Diagnostics log only metadata, limiting the information recorded.
Retry limits are validated, and application errors are preserved.
Corrects the typo in the StreamAlreadyConsumed error message.
Structured parsing is skipped for commentary responses.
Normalizes API error codes to strings.
Includes the completion in content filter errors.
Handles null text in output_text.
Normalizes PathLike upload tuples.
Preserves response stream indexes after empty items.
Bounds vector store file polling.
Handles bare dict and list annotations without type arguments.
Preserves finalized output on null response completion.
Adds GPT Image 2.5 models for developers to use.
Corrects the fields on function argument completion events.
Refuses overflowing retry delays supplied by the server.
Accepts incomplete statuses for web search calls.
Resolves one Azure authentication mode.
Encodes Azure deployment names consistently.
Keeps Azure provider validation errors value-free.
Computes custom-code summaries from trusted workflow code.
Keeps diagnostics metadata-only.
Correctly encodes Realtime call offers and session configuration.
Decodes SSE incrementally without limiting event size.
Preserves the configured TLS hostname.
Preserves byte accounting for the WebSocket send queue during flush.
Optional networking dependencies must be patched.
An Ultrafast tier is added.
openai 2130 changes
Breaking changes 12
The package now requires Python 3.10.
Requires patched aiohttp on Python 3.10 and later.
Removes beta annotation compatibility aliases.
The legacy Python CLI was removed, so developers using it may need another way to run those commands.
Stream helpers now require bearer authentication.
Makes type required in ResponseInputMessageItem.
The WebSocket protocol now matches the HTTP protocol instead of using WSS.
The computer_use_preview tool is moved to ComputerUsePreview.
Removes the prompt_cache_key parameter from responses.
The model parameter is now required for the responses/compact endpoint.
Support for Python 3.8 was dropped.
InputAudio is removed from ResponseInputContent.
Security 2
Admin authentication no longer falls back to bearer authentication.
Sanitizes endpoint path params.
Deprecations 1
Assistants are marked as deprecated.
New APIs and options 71
Adds new model identifiers for the Responses API.
Adds gpt-5.5 to the available model types.
Adds the tool name field to Responses types.
Adds the tool namespace field to Responses types.
Added content provenance checks to the API.
The API and helper methods support the fast tier.
API requests now accept None for prompt_cache_key.
API requests now accept None for safety_identifier.
Adds support for spend_limit admin APIs.
Adds experimental runtime support for HTTPX2 clients.
Adds the owner_project_access parameter to APIKeyListParams.
Adds the service-account API keys endpoint under organization projects.
Adds admin spend alerts to the API, enabling developers to use spend alert operations through the SDK.
Adds the chat completions moderation API.
Adds the responses moderation API.
Adds support for using Responses with Amazon Bedrock.
Responses can include an additional_tools item.
The responses compact method accepts a service_tier parameter.
Adds realtime API updates identified in the notes as “realtime 2”; no endpoint or identifier details are provided.
Admin API key authentication is supported.
Support was added for Admin API Keys per endpoint.
Users now support an email parameter.
Projects now support external_key_id.
Headers can now be set via environment variables.
Users now support a metadata parameter.
Adds detail to InputFileContent, allowing developers to provide this information.
Adds the OAuthErrorCode type for working with OAuth error codes.
Adds an event handler implementation for websockets.
Adds support for reconnection in websockets.
A phase field is added to conversations messages.
The client supports sending raw data over websockets.
The client adds support for short-lived tokens.
Adds a keys field to Click, DoubleClick, Drag, Move, and Scroll computer actions.
Adds 5.4 nano and mini model slugs for use with the API.
The batches create method now supports the /v1/videos endpoint.
Adds the in operator to the ComparisonFilter type.
Adds the nin operator to the ComparisonFilter type.
Adds the defer_loading field to ToolFunction.
Adds support for custom voices.
Sora API improvements include a character API.
Sora API improvements include higher resolution exports.
Sora API improvements include video extensions and edits.
Adds a new computer tool to the API.
Adds gpt-5.4 for developers to use through the API.
Adds the tool search tool to the API.
Adds phase to the API.
Added as a model option for realtime calls.
Added as a model option for realtime calls.
WebSockets are now available for the Responses API.
Container support adds network_policy, allowing developers to configure container network policy.
Container support adds skills.
The batch API now supports images, allowing developers to include images in batch requests.
Adds API support for skills and hosted shell.
Adds context_management to responses, allowing developers to use this new Responses API capability.
Adds a custom JSON encoder to support extended types.
Adds image generation actions for responses.
Adds the name field to ResponseFunctionCallArgumentsDoneEvent.
Adds a status field to shell_call_output so developers can access the output status.
The client adds support for binary request streaming.
The Response object now includes a completed_at property.
Slugs are available for new audio models.
All model parameters now accept strings, allowing developers to pass model identifiers directly.
Adds gpt-image-1.5 to the API.
Adds support for GPT-5.2 in the API.
Adds gpt-5.1-codex-max as a supported API model.
Adds support for the responses/compact API.
GPT-5.1 is supported by the API.
Hybrid searching gains ranking options.
The Realtime API adds token_limits.
Adds responses.input_tokens.count to count input tokens.
The audio/transcriptions endpoint now supports gpt-4o-transcribe-diarize.
Behavior and default changes 3
client_id is no longer necessary when using the workload identity provider for authentication.
Allows enqueuing to websockets even when they are not connected.
The GA ComputerTool now uses the CompuerTool class.
Fixes and other changes 41
Clarifies the metadata requirements for audio uploads.
The client now honors Retry-After delays up to two minutes.
The transcription keyword overload was restored.
Transcription model updates were made to the API.
Beta resource accessors are restored, allowing developers to access beta resources again.
API updates for gpt-5.6-sol may affect how developers use the model.
Prioritizes the first auth header.
Allows Bedrock API keys to be set directly on the client.
ActionSearch.query is optional.
Workload identity is included in audit logs.
The missing f-string prefix in a file type error message is fixed.
Fixes a regression in the imagegen size enum.
The image API was updated; the notes do not specify the particular API changes.
Explicit Azure authentication headers are now allowed.
The Response model's completed_at timestamp type is corrected to int.
The Response model's created_at timestamp type is corrected to int.
Multipart file arrays now use the correct field name format.
The enum value was corrected from in-memory to in_memory.
Ensures file data are sent as only one parameter.
Hardcoded query parameters are preserved when merged with user params.
Aligns SDK response types with expanded item schemas.
The SDK no longer passes by_alias unless it is set.
The merged videos resource was repaired.
Fixes the phase enum.
Fixes a memory leak in parse methods.
Preserves method visibility for compatibility checks.
Updates the type for the find_in_page action.
Undoes a change to the web search Find action.
The patch method now uses async_to_httpx_files.
Dated slugs were added for sora-2.
The grader input list was fixed.
Pyright can now infer TypedDict types within SequenceNotStr.
The client no longer mutates a user-provided response config object.
Streams are now always closed.
Aligned the TypeScript types for input items and output items.
The signature is updated for Pydantic v1 compatibility.
The signature is updated for Pydantic v1 compatibility.
Compatibility with Python 3.14 was fixed.
Fixes the nullability of logprobs.
Uploads avoid leaking file handles.
Streams can be closed without requiring full consumption.