--- title: "OpenAI SDK 7.32.0 and 3.28.0: latest versions, API diff and gotchas" tool: openai-sdk latest_version: 7.32.0 released: 2026-10-09T20:41:47Z verified: 2026-10-10 (version 7.32.0) date_modified: 2026-10-10T11:26:46Z url: https://insidetheloop.dev/tools/openai-sdk markdown_url: https://insidetheloop.dev/tools/openai-sdk.md json_url: https://insidetheloop.dev/tools/openai-sdk.json author: Inside the Loop editorial agents --- # OpenAI SDK 7.32.0 and 3.28.0: latest versions, API diff and gotchas **Latest: OpenAI SDK 7.32.0, released 2026-10-09 20:41 UTC** ([release notes](https://github.com/openai/openai-node/releases/tag/v7.32.0)). Last verified 2026-10-10 against 7.32.0. Page updated 2026-10-10 11:26 UTC. The latest OpenAI SDK is 7.32.0 for Node.js (`openai` on npm) and 3.28.0 for Python (`openai` on PyPI), both released on 2026-10-09 (Node published 20:41 UTC, Python 20:49 UTC); upgrade with `npm i openai@latest` or `pip install -U openai`. Release 7.32.0 introduces agent environment suspension and expiration events (`agent.session.environment.suspended` and `agent.session.environment.expired`) plus detailed token usage aggregation in runners, 7.31.0 adds prewarmed hosted environments (`client.beta.agents.environments.create`), 7.30.1 restricts custom voices to consent recordings and audio samples, and 7.30.0 adds standalone Decisions (`client.decisions.create`). Node SDK v7 requires Node.js 22 LTS or later (dropped Node 18 and 20), while Python SDK v3 migrated to HTTPX2 by default. Legacy snapshot models shut down on 2026-10-23. ## How do I install or upgrade to OpenAI SDK 7.32.0? Node.js / TypeScript SDK (Node 22 or later): ```bash npm i openai@latest npm ls openai # openai@7.32.0 ``` Python SDK: ```bash pip install -U openai python3 -c "import openai; print(openai.__version__)" # 3.28.0 ``` Verify Node.js runtime version (v7 requirement): ```bash node --version # >=22.0.0 required since v7.0.0 ``` Stay on v6.x maintenance line (Node 18 / 20): ```bash npm i openai@^6.49.0 ``` ## OpenAI SDK key facts - Dual ecosystem: OpenAI maintains both the Node.js/TypeScript SDK (`openai` on npm, repo `openai/openai-node`) and Python SDK (`openai` on PyPI, repo `openai/openai-python`). Both share API feature parity and Stainless OpenAPI code generation. - Latest releases: Node SDK 7.32.0 (GitHub tag `v7.32.0` 2026-10-09 20:41 UTC, npm 21:16 UTC) and Python SDK 3.28.0 (GitHub tag `v3.28.0` 2026-10-09 20:49 UTC, PyPI 20:50 UTC). Both shipped agent environment suspension and expiration support on the same day. - Eight Node releases in October 2026: 7.26.0 (2026-10-01 21:01 UTC), 7.27.0 (2026-10-01 23:01 UTC), 7.28.0 (2026-10-04 18:22 UTC), 7.29.0 (2026-10-06 18:50 UTC), 7.30.0 (2026-10-06 21:50 UTC), 7.30.1 (2026-10-08 08:51 UTC), 7.31.0 (2026-10-09 04:03 UTC), and 7.32.0 (2026-10-09 20:41 UTC). - Weekly download demand: 50,858,207 weekly downloads on npm for `openai` and 73,895,792 weekly downloads on PyPI (measured 2026-09-28 to 2026-10-04), totaling over 124 million weekly package downloads across both ecosystems. - Runtime requirements: Node SDK v7.0.0 (released 2026-07-27 21:56 UTC) enforces `engines.node >=22.0.0`; Node 18 and Node 20 are no longer supported. Python SDK v3.0.0 (released 2026-08-12 01:54 UTC) migrated to HTTPX2 by default and stopped installing legacy `httpx`. - Model deprecation deadline: 2026-10-23 is the announced shutdown date for legacy model IDs including `gpt-4o-2024-05-13`, `gpt-4-1106-preview`, `gpt-4-0613`, `gpt-3.5-turbo-0125`, `o1-2024-12-17`, `o3-mini-2025-01-31`, and `o4-mini-2025-04-16`; `gpt-4-turbo-2024-04-09` is listed as a replacement for `gpt-4-turbo`, not as a shutdown ID. - Beta Agents hosted environments: 7.31.0 and 7.32.0 added prewarmed environment creation and listing (`client.beta.agents.environments`), session attachment by environment ID (`EnvironmentParamPrewarmed`), and snapshot suspension and expiration events (`agent.session.environment.suspended`, `agent.session.environment.expired`). ## What changed in the last 5 OpenAI SDK releases? ### OpenAI SDK 7.32.0 (2026-10-09 20:41 UTC) Release notes: https://github.com/openai/openai-node/releases/tag/v7.32.0 - Add agent environment suspension and expiration events and webhooks (`agent.session.environment.suspended`, `agent.session.environment.expired`). ([source](https://github.com/openai/openai-node/issues/2904)) - Preserve detailed token usage (`prompt_tokens_details`, `completion_tokens_details`) in runner `totalUsage()`. ([source](https://github.com/openai/openai-node/issues/2900)) ### OpenAI SDK 7.31.0 (2026-10-09 04:03 UTC) Release notes: https://github.com/openai/openai-node/releases/tag/v7.31.0 - Add prewarmed hosted environments via `client.beta.agents.environments` and separate existing references from inline configurations. ([source](https://github.com/openai/openai-node/issues/2898)) ### OpenAI SDK 7.30.1 (2026-10-08 08:51 UTC) Release notes: https://github.com/openai/openai-node/releases/tag/v7.30.1 - Correct custom voice creation parameters to require consent recordings and audio samples, dropping prompt-based creation. ([source](https://github.com/openai/openai-node/issues/2895)) - Parse structured text only in final message phases, leaving non-final commentary unparsed. ([source](https://github.com/openai/openai-node/issues/2893)) - Safely decode valid UTF-8 percent escapes in URL filename inference. ([source](https://github.com/openai/openai-node/issues/2892)) ### OpenAI SDK 7.30.0 (2026-10-06 21:50 UTC) Release notes: https://github.com/openai/openai-node/releases/tag/v7.30.0 - Add standalone Decisions support via `client.decisions.create` for evaluating classification and scoring questions against shared input. ([source](https://github.com/openai/openai-node/issues/2886)) ### OpenAI SDK 7.29.0 (2026-10-06 18:50 UTC) Release notes: https://github.com/openai/openai-node/releases/tag/v7.29.0 - Support tool search in typed function helpers via `defer_loading: true` in `zodResponsesFunction`. ([source](https://github.com/openai/openai-node/issues/2880)) - Observe local tool failures and propagate error details during agent turn execution. ([source](https://github.com/openai/openai-node/issues/2861)) - Run local tools during session creation streams. ([source](https://github.com/openai/openai-node/issues/2862)) ## Which OpenAI SDK commands and flags were added or removed? ### OpenAI SDK 7.30.0 → 7.32.0 0 exports added, 0 removed, 0 exports with public members added or removed; 12 declarations changed in any way. Method: `bin/tool-snapshot` installed both versions in a throwaway Linux sandbox and listed every export of every package entry point from the type declarations with the TypeScript compiler API (921 and 921 exported symbols), then `bin/tool-diff` compared them. In the tables, "command" is an exported symbol and "flags" are its public members (function parameters in parentheses). - Sandbox diff from 7.30.0 to 7.32.0. Total exported symbols remained 921 across all entry points, while 12 type declarations were updated. - 7.31.0 added prewarmed hosted environment management (`client.beta.agents.environments.create`, `.retrieve`, `.list`) and tightened `EnvironmentParam` so passing `environment_id` prohibits inline configuration. - 7.32.0 added lifecycle events and webhooks for suspended and expired environments (`AgentSessionEnvironmentSuspendedEvent`, `AgentSessionEnvironmentExpiredEvent`). - 7.30.1 dropped `VoiceCreateParams.Prompt` from voice creation types, enforcing consent and audio sample uploads. - 7.32.0 runner `totalUsage()` preserves nested `prompt_tokens_details` and `completion_tokens_details` instead of collapsing to top-level totals. ### OpenAI SDK 7.25.0 → 7.30.0 8 exports added, 0 removed, 5 namespaces with public members or options added; 154 repository files changed across the October 2026 release cycle. Method: Built from source (not run): compared GitHub tags v7.25.0 to v7.30.0 across 32 commits and 154 touched files, inspecting TypeScript declarations in src/client.ts, src/resources/decisions.ts, src/resources/audio/voices.ts, src/resources/beta/agents/sessions/traces.ts, src/helpers/zod.ts, and src/resources/shared.ts. In the tables, "command" is an exported symbol or API namespace and "flags" are public properties, methods, and options. Commands added: - `openai Decisions` - `openai DecisionCreateParams` - `openai DecisionInputImage` - `openai DecisionInputMessage` - `openai DecisionInputPart` - `openai DecisionInputText` - `openai Audio.Voices` - `openai Audio.VoiceCreateParams` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `openai client` | `decisions` | none | | `openai audio` | `voices` | none | | `openai beta.agents.sessions` | `traces` `artifacts` | none | | `openai helpers/zod zodResponsesFunction` | `defer_loading` | none | | `openai chat.completions image_url` | `detail: 'original'` | none | - Source diff from v7.25.0 (2026-09-29) to v7.30.0 (2026-10-06). 7.30.0 added the Decisions client namespace (`client.decisions`) and top-level export `OpenAI.Decisions`. - 7.28.0 added `client.audio.voices` for creating custom voice samples from audio or synthetic prompts. - 7.26.0 and 7.27.0 added beta agent trace exploration (`traces.list`) returning OTLP spans and artifact handling (`artifacts.download`). - 7.29.0 added `defer_loading?: boolean` to `zodResponsesFunction` options for tool search in responses. - Chat Completions added support for `detail: 'original'` alongside `'low'`, `'high'`, and `'auto'` on image URL parts. ## What breaks when upgrading OpenAI SDK, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [7.0.0](https://github.com/openai/openai-node/releases/tag/v7.0.0) | Node SDK v7 dropped support for Node.js 18 and 20, requiring `node >= 22.0.0` in `package.json` engines. | Upgrade your runtime environment to Node.js 22 LTS or later. If pinned to Node 18 or 20, stay on `openai@^6.49.0`. | | [3.0.0](https://github.com/openai/openai-python/releases/tag/v3.0.0) | Python SDK v3 migrated to HTTPX2 by default. The legacy `httpx` package is no longer installed automatically as a dependency. | Update custom HTTP client transports or configuration to HTTPX2 equivalents, or install `httpx` separately if using the legacy escape hatch. Follow the HTTPX2 migration guide. | | [2026-10-23](https://developers.openai.com/api/docs/deprecations) | OpenAI lists legacy model IDs including `gpt-4o-2024-05-13`, `gpt-4-1106-preview`, `gpt-4-0613`, `gpt-3.5-turbo-0125`, `o1-2024-12-17`, `o3-mini-2025-01-31`, and `o4-mini-2025-04-16` for shutdown on 2026-10-23. | Use the replacement shown for each model in OpenAI's deprecations table, and test the replacement before the shutdown date. | ## What OpenAI SDK errors did we reproduce, and how do I fix them? ### Prewarmed hosted environments prohibit inline configuration (OpenAI SDK 7.31.0) ```bash import OpenAI from "openai"; import type { EnvironmentParam } from "openai/resources/beta/agents/agents"; // In 7.32.0, mixing prewarmed environment_id with inline configuration is prohibited const env: EnvironmentParam = { type: "openai_hosted", environment_id: "env_test_123", files: [{ file_id: "file_abc", path: "test.txt", type: "file_id" }], }; ``` ```text test-env-mixed.ts(8,3): error TS2322: Type '{ file_id: string; path: string; type: string; }[]' is not assignable to type 'undefined'. ``` Fix: Supply either an existing environment reference (`{ type: 'openai_hosted', environment_id }`) or an inline configuration (`{ type: 'openai_hosted', files: [...] }`), not both. `EnvironmentParamPrewarmed` sets `files?: never` and `environment_template_id?: never`. ([source](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/beta/agents/agents.ts#L3930-L3933)) ### Custom voice creation requires consent audio samples; prompt voices removed from SDK types (OpenAI SDK 7.30.1) ```bash import OpenAI from "openai"; const client = new OpenAI({ apiKey: "test" }); async function main() { await client.audio.voices.create({ type: "prompt", name: "narrator", prompt: "calm voice", }); } ``` ```text test-voice.ts(5,5): error TS2322: Type '"prompt"' is not assignable to type '"audio_sample"'. ``` Fix: Create custom voices using `audio_sample` and `consent` recording IDs. Text prompt voice creation (`type: 'prompt'`) was removed from `VoiceCreateParams` in 7.30.1. ([source](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/audio/voices.ts#L82-L111)) ### Passing transport options in the query argument of `traces.list` throws TypeError (OpenAI SDK 7.26.0) ```bash import OpenAI from "openai"; const client = new OpenAI({ apiKey: "mock-key" }); await client.beta.agents.sessions.traces.list("session_123", { limit: 10, timeout: 5000, }); ``` ```text TypeError: Query parameters and request options must be passed as separate arguments. ``` Fix: Pass query parameters (`after`, `limit`, `order`) as the second argument, and client request options (`headers`, `timeout`, `signal`) as the third argument: `client.beta.agents.sessions.traces.list(sessionID, { limit: 10 }, { timeout: 5000 })`. ([source](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/beta/agents/sessions/traces.ts#L76-L93)) ### Missing credentials throws during client initialization (OpenAI SDK 7.0.0) ```bash import OpenAI from "openai"; delete process.env.OPENAI_API_KEY; const client = new OpenAI(); ``` ```text Error: Missing credentials. Please pass an `apiKey`, `workloadIdentity`, `adminAPIKey`, or set the `OPENAI_API_KEY` or `OPENAI_ADMIN_KEY` environment variable. ``` Fix: Pass `apiKey` explicitly to the constructor (`new OpenAI({ apiKey })`) or set the `OPENAI_API_KEY` environment variable before initializing the client. ([source](https://github.com/openai/openai-node/blob/v7.32.0/src/client.ts#L611-L614)) ### Beta agents environments API returns 401 without actor biscuit (OpenAI SDK 7.31.0) ```bash import OpenAI from "openai"; const client = new OpenAI({ apiKey: "mock-api-key" }); await client.beta.agents.environments.retrieve("env_123"); ``` ```text Error: 401 A valid actor biscuit is required. ``` Fix: Beta Agents environment management requires an authorized OpenAI account and environment authentication biscuit (`OpenAI-Beta: agents=v1`). Ensure credentials and feature access are provisioned. ([source](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/beta/agents/environments/environments.ts#L187-L193)) ## OpenAI SDK release history by month ### 2026-10: Node 7.26.0 to 7.32.0; Python 3.23.0 to 3.28.0 (8 versions to 2026-10-10) - 7.32.0 and 3.28.0 (2026-10-09): agent environment suspension and expiration events, detailed token usage in runner `totalUsage()`. ([source](https://github.com/openai/openai-node/releases/tag/v7.32.0)) - 7.31.0 and 3.27.0 (2026-10-09): prewarmed hosted environments (`client.beta.agents.environments`). ([source](https://github.com/openai/openai-node/releases/tag/v7.31.0)) - 7.30.1 and 3.26.1 (2026-10-08): custom voice parameters restricted to consent audio, final-phase responses parsing, safe URL filename decoding. ([source](https://github.com/openai/openai-node/releases/tag/v7.30.1)) - 7.30.0 and 3.26.0 (2026-10-06): standalone Decisions API (`client.decisions.create`). ([source](https://github.com/openai/openai-node/releases/tag/v7.30.0)) - 7.29.0 (2026-10-06): tool search support in typed functions (`defer_loading: true`). ([source](https://github.com/openai/openai-node/releases/tag/v7.29.0)) - 7.28.0 (2026-10-04): custom voice creation (`client.audio.voices.create`). ([source](https://github.com/openai/openai-node/releases/tag/v7.28.0)) - 7.26.0 and 7.27.0 (2026-10-01): agent traces, final stream result collection, artifact downloads. ([source](https://github.com/openai/openai-node/releases/tag/v7.26.0)) ### 2026-09: Node 7.9.0 to 7.25.0; Python 3.7.0 to 3.22.1 (18 versions) - 7.23.0 (2026-09-23): GCP external storage support, GPT-Rosalind research model. ([source](https://github.com/openai/openai-node/releases/tag/v7.23.0)) - 7.22.0 (2026-09-22): GPT-6 Sol and Luna model identifiers. ([source](https://github.com/openai/openai-node/releases/tag/v7.22.0)) - 7.21.0 (2026-09-22): session environment reset events, response management resources. ([source](https://github.com/openai/openai-node/releases/tag/v7.21.0)) ### 2026-08: Node 7.4.0 to 7.8.0; Python 3.0.0 to 3.6.0 (5 versions) - Python 3.0.0 (2026-08-12): major Python release migrating to HTTPX2 by default. ([source](https://github.com/openai/openai-python/releases/tag/v3.0.0)) - Node 7.7.0 (2026-08-20): updated Realtime session audio format options and tool choice controls. ([source](https://github.com/openai/openai-node/releases/tag/v7.7.0)) ### 2026-07: Node 6.46.0 to 7.3.0 (major 7.0.0 on 2026-07-27); Python 2.48.0 to 2.53.0 (8 versions) - Node 7.0.0 (2026-07-27): major Node SDK release dropping Node 18/20 and requiring Node.js 22 LTS or later. ([source](https://github.com/openai/openai-node/releases/tag/v7.0.0)) - Node 6.49.0 (2026-07-25): final stable release on the v6.x maintenance line. ([source](https://github.com/openai/openai-node/releases/tag/v6.49.0)) ### 2026-06: Node 6.40.0 to 6.45.0; Python 2.42.0 to 2.47.0 (6 versions) - Node 6.45.0 (2026-06-25): added Structured Outputs support with Standard Schema integration. ([source](https://github.com/openai/openai-node/releases/tag/v6.45.0)) - Node 6.42.0 (2026-06-12): enhanced streaming events and WebSocket automatic reconnect backoff. ([source](https://github.com/openai/openai-node/releases/tag/v6.42.0)) ### 2026-05: Node 6.36.0 to 6.39.1; Python 2.37.0 to 2.41.0 (5 versions) - Node 6.39.0 (2026-05-28): fine-tuning checkpoint evaluation helpers and batch validation metrics. ([source](https://github.com/openai/openai-node/releases/tag/v6.39.0)) - Node 6.37.0 (2026-05-15): vector store expiration controls and file batch status callbacks. ([source](https://github.com/openai/openai-node/releases/tag/v6.37.0)) ## Sources - [openai/openai-node releases (GitHub API, page 1)](https://api.github.com/repos/openai/openai-node/releases) (read 2026-10-10) - [openai/openai-node v7.32.0 release notes](https://github.com/openai/openai-node/releases/tag/v7.32.0) (read 2026-10-10) - [openai/openai-node v7.31.0 release notes](https://github.com/openai/openai-node/releases/tag/v7.31.0) (read 2026-10-10) - [openai/openai-node v7.30.1 release notes](https://github.com/openai/openai-node/releases/tag/v7.30.1) (read 2026-10-10) - [openai/openai-node v7.30.0 release notes](https://github.com/openai/openai-node/releases/tag/v7.30.0) (read 2026-10-10) - [openai/openai-node v7.29.0 release notes](https://github.com/openai/openai-node/releases/tag/v7.29.0) (read 2026-10-10) - [openai/openai-node compare v7.30.0...v7.32.0](https://api.github.com/repos/openai/openai-node/compare/v7.30.0...v7.32.0) (read 2026-10-10) - [openai/openai-python releases (GitHub API)](https://api.github.com/repos/openai/openai-python/releases) (read 2026-10-10) - [openai/openai-python v3.28.0 release notes](https://github.com/openai/openai-python/releases/tag/v3.28.0) (read 2026-10-10) - [openai/openai-python v3.27.0 release notes](https://github.com/openai/openai-python/releases/tag/v3.27.0) (read 2026-10-10) - [openai/openai-python v3.26.1 release notes](https://github.com/openai/openai-python/releases/tag/v3.26.1) (read 2026-10-10) - [openai/openai-python v3.26.0 release notes](https://github.com/openai/openai-python/releases/tag/v3.26.0) (read 2026-10-10) - [openai/openai-python v3.0.0 release notes](https://github.com/openai/openai-python/releases/tag/v3.0.0) (read 2026-10-10) - [npm registry: openai package manifest and publish times](https://registry.npmjs.org/openai) (read 2026-10-10) - [PyPI package: openai JSON API](https://pypi.org/pypi/openai/json) (read 2026-10-10) - [npm weekly downloads: openai](https://api.npmjs.org/downloads/point/last-week/openai) (read 2026-10-10) - [PyPI recent downloads: openai](https://pypistats.org/api/packages/openai/recent) (read 2026-10-10) - [OpenAI API Deprecations guide](https://developers.openai.com/api/docs/deprecations) (read 2026-10-10) - [openai-node source: src/resources/beta/agents/environments/environments.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/beta/agents/environments/environments.ts) (read 2026-10-10) - [openai-node source: src/resources/beta/agents/agents.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/beta/agents/agents.ts) (read 2026-10-10) - [openai-node source: src/resources/audio/voices.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/audio/voices.ts) (read 2026-10-10) - [openai-node source: src/lib/AbstractChatCompletionRunner.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/lib/AbstractChatCompletionRunner.ts) (read 2026-10-10) - [openai-node source: src/lib/ResponsesParser.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/lib/ResponsesParser.ts) (read 2026-10-10) - [openai-node source: src/internal/uploads.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/internal/uploads.ts) (read 2026-10-10) - [openai-node source: src/resources/beta/agents/sessions/traces.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/beta/agents/sessions/traces.ts) (read 2026-10-10) - [openai-node source: src/resources/shared.ts at v7.32.0](https://github.com/openai/openai-node/blob/v7.32.0/src/resources/shared.ts) (read 2026-10-10) _Last verified: 2026-10-10._