openai 0.85.0 → 0.87.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37f60ef5c84fcaef53fccd86fa30e1cc0988b4033abdd3e14711247e082de5d4
-  data.tar.gz: 97cd2b216e53d22574e00031f94b0d2975393a9128a9d2528ea735679bb04f8f
+  metadata.gz: e2541f0eac1ef08259b89e4baa93434e632c2c46a17b1a67e02fd25d167b77d4
+  data.tar.gz: 2d27951debe6e1fd0a42e2817cf59c02dc01d4c8ca8682070cbdd2d14d7e46db
 SHA512:
-  metadata.gz: 1493b225ac23056cda189b6af2bdd547aeb3441fef8f85c9454ae2d2d51e87e84743807cd86875f85a1d055eeb1f8c30ab684b7a11f76e46f86fbcd47c3b0995
-  data.tar.gz: 702dc478f26dff8454563e36b2d3ed4113ced5f04f104d34ab399091b290bf34ca3cccbb1ad8f44b2dae132d40053e33b9d0a86dc20f3a66316e0aed9378459d
+  metadata.gz: 94c5255cec9b29f277dabe60b6825dd4a1edb7be86ce25162e25f2c6f3bf072c38a19297b047c0177c6553e2ff8bcd06a935d8a841e4b6d2e480377fd5bf667b
+  data.tar.gz: 9a638b78473f54fa9238a46e6ad8ec419bc892e94fe1303292268174d6203566f095e778631b2bb65da61191950cfedac2c31f4c1eea287a13d46b3d632ba05f

data/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Changelog
 
+## [0.87.0](https://github.com/openai/openai-ruby/compare/v0.86.0...v0.87.0) (2026-09-08)
+
+
+### Features
+
+* add FFmpeg local recording and playback helpers ([#685](https://github.com/openai/openai-ruby/issues/685)) ([4d05097](https://github.com/openai/openai-ruby/commit/4d05097f10408452aaf0efa48c499bada62846bb))
+* add opt-in Realtime reconnect and send queue ([#681](https://github.com/openai/openai-ruby/issues/681)) ([21b8a70](https://github.com/openai/openai-ruby/commit/21b8a70d48e2623e32aa01f95503adcf3fa2ba75))
+* **api:** add GPT Image 2.5 models and image options ([#688](https://github.com/openai/openai-ruby/issues/688)) ([02f4724](https://github.com/openai/openai-ruby/commit/02f4724eb69eebe8c46b8d51010bee364e1197ad))
+
+## [0.86.0](https://github.com/openai/openai-ruby/compare/v0.85.0...v0.86.0) (2026-09-08)
+
+
+### Features
+
+* add Responses WebSocket mode ([#562](https://github.com/openai/openai-ruby/issues/562)) ([7c910a7](https://github.com/openai/openai-ruby/commit/7c910a78ae4418dc59e766edc2467c254b814a89))
+* **api:** add cache diagnostics and fix optional RBS keys ([#604](https://github.com/openai/openai-ruby/issues/604)) ([4e4f7cd](https://github.com/openai/openai-ruby/commit/4e4f7cdda5b5e1c568badded52324af06c77378b))
+* **api:** add service-account API key expiration fields ([#625](https://github.com/openai/openai-ruby/issues/625)) ([8d3f213](https://github.com/openai/openai-ruby/commit/8d3f213da707b11ddbd913a801925b00b3e2bcc9))
+* **api:** correct function argument completion event fields (openapi-545) ([#622](https://github.com/openai/openai-ruby/issues/622)) ([06e2c91](https://github.com/openai/openai-ruby/commit/06e2c91dc349ba36d12ece05bf0b0cbf1ba0e220))
+* **api:** recognize incomplete web search call status ([#590](https://github.com/openai/openai-ruby/issues/590)) ([1560da0](https://github.com/openai/openai-ruby/commit/1560da01073061cc0a0dadc853f7dbc6e688a4d4))
+* **responses:** parse structured outputs on retrieval ([#532](https://github.com/openai/openai-ruby/issues/532)) ([41eb726](https://github.com/openai/openai-ruby/commit/41eb726b66fcb56f149553a9d681d8f1837b9b97))
+
+
+### Bug Fixes
+
+* accept documented RequestOptions extra query values ([#660](https://github.com/openai/openai-ruby/issues/660)) ([e168aa4](https://github.com/openai/openai-ruby/commit/e168aa47ee9ff81150a901c4eba1f236dea0dcf6))
+* accept string Responses structured-output tags ([#617](https://github.com/openai/openai-ruby/issues/617)) ([4322e07](https://github.com/openai/openai-ruby/commit/4322e076e57b769d619175006307763e3c630cfb))
+* **api:** expose metadata on binary responses ([#608](https://github.com/openai/openai-ruby/issues/608)) ([59e0643](https://github.com/openai/openai-ruby/commit/59e0643dbb37e95b4746b24b38c1489dd2867e33))
+* avoid retrying ambiguous non-idempotent requests ([#650](https://github.com/openai/openai-ruby/issues/650)) ([4734cba](https://github.com/openai/openai-ruby/commit/4734cba47984a53e241e224acb7f465372b34598))
+* avoid unused Responses stream snapshot copies ([#677](https://github.com/openai/openai-ruby/issues/677)) ([2996996](https://github.com/openai/openai-ruby/commit/2996996d8c68e96f5c8fb65da869a321988c5dc8))
+* close proxy after WebSocket handshake failure ([#675](https://github.com/openai/openai-ruby/issues/675)) ([aeb4cf2](https://github.com/openai/openai-ruby/commit/aeb4cf2120d6eb7f204206dd5364951ad0495103)), closes [#669](https://github.com/openai/openai-ruby/issues/669)
+* coerce Integer strings as decimal ([#667](https://github.com/openai/openai-ruby/issues/667)) ([82f8c62](https://github.com/openai/openai-ruby/commit/82f8c62f0a68236757d57cfe3fd4a501f41270f5))
+* correct Responses stream RBS contract ([#654](https://github.com/openai/openai-ruby/issues/654)) ([0d32ba4](https://github.com/openai/openai-ruby/commit/0d32ba4c555c3ea2763dade0db6618e86de84f96))
+* correct Responses text enumerator Sorbet type ([#637](https://github.com/openai/openai-ruby/issues/637)) ([49ccb69](https://github.com/openai/openai-ruby/commit/49ccb69cbe4fd0a738bbc03840b7bb117bb183f6))
+* declare built-in workload identity providers ([#659](https://github.com/openai/openai-ruby/issues/659)) ([cfbbb98](https://github.com/openai/openai-ruby/commit/cfbbb98f2a87340442c9b8ccd267cd54dbd31fbc))
+* declare Chat stream finish exception types ([#657](https://github.com/openai/openai-ruby/issues/657)) ([87fc522](https://github.com/openai/openai-ruby/commit/87fc522b00f51b1020f64bdcaa4e56573f43ab6a))
+* declare webhook signature error types ([#642](https://github.com/openai/openai-ruby/issues/642)) ([5211472](https://github.com/openai/openai-ruby/commit/52114726f0bd8780f013e95cade266e3f95677c6))
+* declare workload identity error types ([#658](https://github.com/openai/openai-ruby/issues/658)) ([e6afdeb](https://github.com/openai/openai-ruby/commit/e6afdeb10815f3b3cd5a3224abd5d55a3f2b1377))
+* deserialize diarized transcriptions correctly ([#652](https://github.com/openai/openai-ruby/issues/652)) ([5be26ce](https://github.com/openai/openai-ruby/commit/5be26ce71fa5855e668068075215c454ec7eeab8))
+* handle non-object OAuth error bodies ([#674](https://github.com/openai/openai-ruby/issues/674)) ([13aa3d6](https://github.com/openai/openai-ruby/commit/13aa3d65ee84d242407d8ad912b0f26e4c945fe8))
+* handle quoted response charsets ([#613](https://github.com/openai/openai-ruby/issues/613)) ([91d0e86](https://github.com/openai/openai-ruby/commit/91d0e86ed995f54361b329d7641af9f20163f27d)), closes [#610](https://github.com/openai/openai-ruby/issues/610)
+* honor custom idempotency headers for retries ([#673](https://github.com/openai/openai-ruby/issues/673)) ([5bd703a](https://github.com/openai/openai-ruby/commit/5bd703acb8b270d0ae37ea1a846dfada5f88b9fc)), closes [#671](https://github.com/openai/openai-ruby/issues/671)
+* honor raw StringIO request cursors ([#621](https://github.com/openai/openai-ruby/issues/621)) ([8e6abfd](https://github.com/openai/openai-ruby/commit/8e6abfd57a33ae7c7360f496f8baf15e1cf74db4))
+* isolate base URL queries between requests ([#619](https://github.com/openai/openai-ruby/issues/619)) ([347e659](https://github.com/openai/openai-ruby/commit/347e659404bd7a13de57604e325c4432c875ee60))
+* isolate structured output field metadata ([#655](https://github.com/openai/openai-ruby/issues/655)) ([7f3cec8](https://github.com/openai/openai-ruby/commit/7f3cec8663175c9ac1be12368bcf1c3717ca2466))
+* keep Realtime metadata out of nested payloads ([#653](https://github.com/openai/openai-ruby/issues/653)) ([d1fa0d3](https://github.com/openai/openai-ruby/commit/d1fa0d3026a47cd16c4c2dcd8d68e8d1ecb854db))
+* match response charset parameters case-insensitively ([#629](https://github.com/openai/openai-ruby/issues/629)) ([821d9b3](https://github.com/openai/openai-ruby/commit/821d9b3f018040a3a946f714e120f009541c9743))
+* match the multipart request content type case-insensitively ([#666](https://github.com/openai/openai-ruby/issues/666)) ([55ae013](https://github.com/openai/openai-ruby/commit/55ae0137740f05f30173e3dc73d546a500b29d2a))
+* normalize Bedrock environment bearer tokens ([#601](https://github.com/openai/openai-ruby/issues/601)) ([131e977](https://github.com/openai/openai-ruby/commit/131e97745f0cca1b167a533b852141ceed480c96))
+* normalize workload identity error headers ([#640](https://github.com/openai/openai-ruby/issues/640)) ([1cf3762](https://github.com/openai/openai-ruby/commit/1cf37629ab61b2cc9259dff52c143b08ebe6b70a))
+* parse initial streamed tool arguments ([#593](https://github.com/openai/openai-ruby/issues/593)) ([f4e2ec9](https://github.com/openai/openai-ruby/commit/f4e2ec9069d0781e376447f9f840082f00e07b81))
+* parse SSE field lines that carry no value ([#631](https://github.com/openai/openai-ruby/issues/631)) ([9109f3f](https://github.com/openai/openai-ruby/commit/9109f3f79f6db401e400ca8e4cac8586a9332760))
+* parse SSE retry metadata as decimal ([#624](https://github.com/openai/openai-ruby/issues/624)) ([9135d15](https://github.com/openai/openai-ruby/commit/9135d15c272b9e6102f41dc5d0fa64ac1a5fc2ec))
+* parse strict tools in later chat choices ([#633](https://github.com/openai/openai-ruby/issues/633)) ([b68ce90](https://github.com/openai/openai-ruby/commit/b68ce906106cdaa165cbb6ebdd5ec34b2cc7ba2b))
+* populate nested API error metadata ([#639](https://github.com/openai/openai-ruby/issues/639)) ([8dba07c](https://github.com/openai/openai-ruby/commit/8dba07cda53195755ffbf15634c516e51701ba5a))
+* preserve bare CR SSE line boundaries ([#676](https://github.com/openai/openai-ruby/issues/676)) ([98c5a53](https://github.com/openai/openai-ruby/commit/98c5a5333f5d82f25ec12e7b5a9f65ea78716a12)), closes [#670](https://github.com/openai/openai-ruby/issues/670)
+* preserve chat stream moderation results ([#616](https://github.com/openai/openai-ruby/issues/616)) ([c2c729c](https://github.com/openai/openai-ruby/commit/c2c729ce407a526a91d5f1c0607ee190956e414d))
+* preserve complete interleaved tool arguments ([#638](https://github.com/openai/openai-ruby/issues/638)) ([1f32200](https://github.com/openai/openai-ruby/commit/1f322009ccc529d03048fc1d4bee96401c58ee35))
+* preserve documented file inputs on readback ([#662](https://github.com/openai/openai-ruby/issues/662)) ([0169713](https://github.com/openai/openai-ruby/commit/016971345676ade41c57fcee11b60f3adcefe652))
+* preserve file semantics for pathless multipart IO ([#665](https://github.com/openai/openai-ruby/issues/665)) ([0fefbf6](https://github.com/openai/openai-ruby/commit/0fefbf68a804bdd080dfef9defe0ce45e18eaa6b))
+* preserve hash-form type metadata ([#651](https://github.com/openai/openai-ruby/issues/651)) ([8de6a0f](https://github.com/openai/openai-ruby/commit/8de6a0fc26ba8649d6621689ce5c342799c0a786))
+* preserve text logprobs in response streams ([#595](https://github.com/openai/openai-ruby/issues/595)) ([e8e2f39](https://github.com/openai/openai-ruby/commit/e8e2f392f6bd20d8b9ca84d8141b73be0e6b33d9))
+* preserve unknown discriminated union values ([#645](https://github.com/openai/openai-ruby/issues/645)) ([1384aa0](https://github.com/openai/openai-ruby/commit/1384aa017af5fa98a515753e1d4a9ba0bac82d63))
+* preserve UTF-8 SSE stream boundaries ([#623](https://github.com/openai/openai-ruby/issues/623)) ([6b9ee87](https://github.com/openai/openai-ruby/commit/6b9ee8729c3ac429cc93716e8b51bce603de3405))
+* rank tied union variants by declaration order ([#628](https://github.com/openai/openai-ruby/issues/628)) ([5ae6f43](https://github.com/openai/openai-ruby/commit/5ae6f43f4260a1a68984afc649bdc44e68526324))
+* redact malformed streamed JSON errors ([#643](https://github.com/openai/openai-ruby/issues/643)) ([5ab02f6](https://github.com/openai/openai-ruby/commit/5ab02f65fdcecdd007a48e7bde8679ce240c1a1c))
+* respect StringIO cursor in FilePart serialization ([#592](https://github.com/openai/openai-ruby/issues/592)) ([4115a1e](https://github.com/openai/openai-ruby/commit/4115a1e03a3111cbc80be20eb902df81567b3c76))
+* **responses:** expose stream resumption parameters ([#646](https://github.com/openai/openai-ruby/issues/646)) ([d93852f](https://github.com/openai/openai-ruby/commit/d93852f16db7307e3b0da1396b4d06ad4f74cfc2))
+* restore conflict-free exported RBIs for Tapioca ([#679](https://github.com/openai/openai-ruby/issues/679)) ([c80a253](https://github.com/openai/openai-ruby/commit/c80a25396afbf143e68c4b11a8552ebbbb6bfc3b))
+* retry only proven unsent requests ([#663](https://github.com/openai/openai-ruby/issues/663)) ([a63eda8](https://github.com/openai/openai-ruby/commit/a63eda8203aa023ef3a6917c18a2be80cb66e406))
+* stream container file uploads as multipart ([#648](https://github.com/openai/openai-ruby/issues/648)) ([b3c523b](https://github.com/openai/openai-ruby/commit/b3c523b2566a6b760d0a1a952682bf6ca9a866d0))
+* strip upload filenames without platform path rules ([#627](https://github.com/openai/openai-ruby/issues/627)) ([5f00613](https://github.com/openai/openai-ruby/commit/5f006135268ae38b81024f8c28de939c53598c90))
+* suppress Responses WebSocket exception causes ([#644](https://github.com/openai/openai-ruby/issues/644)) ([1b16a83](https://github.com/openai/openai-ruby/commit/1b16a832d74df6742b256545a24915424deaa7dd))
+* type chat completion streams for Sorbet ([#634](https://github.com/openai/openai-ruby/issues/634)) ([cca6a70](https://github.com/openai/openai-ruby/commit/cca6a7035e680fd85ea40bd728937e9c957bd81a))
+* upload pathless IO streams instead of raising ([#630](https://github.com/openai/openai-ruby/issues/630)) ([950552f](https://github.com/openai/openai-ruby/commit/950552f470951ddf01bd1f55a1569b012b6b4fd0))
+
+
+### Chores
+
+* **api:** document throttling and model overload responses — SDK-235 ([#632](https://github.com/openai/openai-ruby/issues/632)) ([2b0483d](https://github.com/openai/openai-ruby/commit/2b0483d394289aa18b792bd7a5440977d8b7a7a1))
+* **api:** Refresh SDK metadata ([#612](https://github.com/openai/openai-ruby/issues/612)) ([e93a4b5](https://github.com/openai/openai-ruby/commit/e93a4b54f9b64609b96c553ac7864d94dacc6cf1))
+* **deps-dev:** bump the development-dependencies group with 7 updates ([#668](https://github.com/openai/openai-ruby/issues/668)) ([d9a2271](https://github.com/openai/openai-ruby/commit/d9a2271531acea12bc3b46293bb90159d3975d59))
+* migrate to forked steady ([#605](https://github.com/openai/openai-ruby/issues/605)) ([5542f01](https://github.com/openai/openai-ruby/commit/5542f01a8395bc9349eae479396ba5158692385f))
+
+
+### Documentation
+
+* clarify dormant compatibility-check boundary ([#647](https://github.com/openai/openai-ruby/issues/647)) ([d6fa81c](https://github.com/openai/openai-ruby/commit/d6fa81ca012db991be4438f6f1b605a0ce12aa8e))
+* clarify Realtime transcription event boundary ([#649](https://github.com/openai/openai-ruby/issues/649)) ([94a1d77](https://github.com/openai/openai-ruby/commit/94a1d77a23c990308d6262f3ce668af6206361f4))
+
 ## [0.85.0](https://github.com/openai/openai-ruby/compare/v0.84.0...v0.85.0) (2026-09-03)
 
 

data/README.md

@@ -15,7 +15,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "openai", "~> 0.85.0"
+gem "openai", "~> 0.87.0"
 ```
 
 <!-- x-release-please-end -->
@@ -50,6 +50,11 @@ stream.each do |event|
 end
 ```
 
+### Local audio
+
+Record a clip and play generated speech with optional FFmpeg/FFplay helpers.
+See the [local audio guide](local-audio.md) for setup, device selection and examples.
+
 ### Realtime WebSockets
 
 The SDK supports block-scoped, typed Realtime WebSocket sessions for
@@ -81,6 +86,41 @@ sideband connection. See the [Realtime WebSocket guide](realtime.md) and the run
 [text, transcription, voice, and sideband examples](examples/realtime/README.md)
 for lifecycle, authentication, proxy, TLS, and custom transport details.
 
+### Responses WebSockets
+
+The Responses API also supports a persistent, block-scoped WebSocket for
+sequential and multiplexed response creation. Add the optional
+`async-websocket` gem, then send `response.create` events through
+`client.responses.connect`:
+
+```ruby
+client.responses.connect do |connection|
+  connection.response.create(
+    model: "gpt-5.2",
+    input: "Say hello.",
+    stream_id: "turn_1"
+  )
+
+  connection.each do |event|
+    print(event.delta) if event.type == :"response.output_text.delta"
+    break if event.type == :"response.completed"
+  end
+end
+```
+
+The connection is intentionally single-owner: callers serialize writes and
+use one reader (`receive` or `each`). The SDK forwards response fields and
+`stream_id` values without imposing additional client-side policy. Known
+server events are decoded into generated models on a best-effort basis, while
+newer event types remain observable as `UnknownServerEvent` values. The SDK
+does not automatically reconnect or replay an ambiguous write. When the server
+closes a connection, open a new connection and continue with
+`previous_response_id` when the response was stored.
+
+See the [Responses WebSocket guide](responses-websocket.md) and
+[runnable workflows](examples/responses/websocket_workflows.rb) for tool turns,
+multiplexing, stored continuation, stateless replay, and operation deadlines.
+
 ### Pagination
 
 List methods in the OpenAI API are paginated.
@@ -213,7 +253,11 @@ The custom HTTP client owns connection pooling and lifecycle, must enforce
 `request.timeout`, and should raise `OpenAI::Errors::APIConnectionError` or
 `OpenAI::Errors::APITimeoutError` for retryable transport failures. Other
 exceptions propagate without an SDK retry. The SDK does not close an injected
-HTTP client.
+HTTP client. Connection failures are treated as potentially post-send by
+default, so non-idempotent requests are not retried automatically. When a
+transport can prove that no request bytes were sent, it may raise either error
+with `request_may_have_been_sent: false` to allow the SDK retry policy to
+retry a replayable request safely.
 
 The default `OpenAI::NetHTTPClient` implements this contract with pooled
 `Net::HTTP` connections. It accepts an optional block for native connection
@@ -395,6 +439,10 @@ For secure, automated environments like cloud-managed Kubernetes, Azure, and GCP
 
 `client_id` remains available as an optional parameter for token exchange setups that require an explicit OAuth client ID.
 
+If `OPENAI_API_KEY` is already set in your environment, pass `api_key: nil`
+to explicitly opt out of that ambient API key when constructing a workload
+identity client.
+
 ### X.509 Workload Identity (Preview)
 
 Organizations enrolled in the X.509 workload identity preview can exchange a
@@ -503,6 +551,7 @@ workload_identity = OpenAI::Auth::WorkloadIdentity.new(
 )
 
 client = OpenAI::Client.new(
+  api_key: nil,
   workload_identity: workload_identity,
 )
 
@@ -524,6 +573,7 @@ workload_identity = OpenAI::Auth::WorkloadIdentity.new(
 )
 
 client = OpenAI::Client.new(
+  api_key: nil,
   workload_identity: workload_identity,
 )
 ```
@@ -540,6 +590,7 @@ workload_identity = OpenAI::Auth::WorkloadIdentity.new(
 )
 
 client = OpenAI::Client.new(
+  api_key: nil,
   workload_identity: workload_identity,
 )
 ```
@@ -570,6 +621,7 @@ workload_identity = OpenAI::Auth::WorkloadIdentity.new(
 )
 
 client = OpenAI::Client.new(
+  api_key: nil,
   workload_identity: workload_identity,
   organization: ENV["OPENAI_ORG_ID"],
   project: ENV["OPENAI_PROJECT_ID"]
@@ -605,9 +657,9 @@ post '/webhook' do
     event = client.webhooks.unwrap(request_body, request.env)
     
     case event.type
-    when 'response.completed'
+    when :'response.completed'
       puts "Response completed: #{event.data}"
-    when 'response.failed'
+    when :'response.failed'
       puts "Response failed: #{event.data}"
     else
       puts "Unhandled event type: #{event.type}"
@@ -711,6 +763,27 @@ response
   end
 ```
 
+For a stored or background response, pass the same structured-output model again
+when retrieving it. The model is used locally to populate `content.parsed`; it is
+not sent as a retrieval query parameter. A response that is still queued or in
+progress can be retrieved the same way, but structured output is parsed only after
+a later retrieval reports it completed when status is present. Compatible
+statusless responses parse once their hinted output is syntactically complete JSON.
+For structured function tools, pass the same model again with
+`tools: [ToolArguments]`; matching retrieved function calls expose typed arguments
+through `output.parsed`.
+
+```ruby
+pending = client.responses.create(
+  model: "gpt-5.2",
+  input: "Extract the event information.",
+  text: CalendarEvent,
+  background: true
+)
+
+response = client.responses.retrieve(pending.id, text: CalendarEvent)
+```
+
 </details>
 
 See the [examples](https://github.com/openai/openai-ruby/tree/main/examples) directory for more usage examples for helper usage.
@@ -915,8 +988,9 @@ a supplied logger are isolated and never replace an API result or API error.
 ### Response metadata and request IDs
 
 OpenAI recommends logging request IDs in production so requests can be traced
-during troubleshooting. Top-level models and pages returned by the client expose
-immutable HTTP response metadata through `last_response`:
+during troubleshooting. Top-level models, pages, streams, and binary StringIO
+values returned by the client expose immutable HTTP response metadata through
+`last_response`:
 
 ```ruby
 response = openai.responses.create(model: "gpt-5.2", input: "Say 'this is a test'.")
@@ -924,6 +998,10 @@ puts(response.last_response.status)                 # 200
 puts(response.last_response.headers["x-request-id"]) # req_123
 puts(response.last_response.request_id)             # req_123
 puts(response._request_id)                           # req_123
+
+audio = openai.audio.speech.create(input: "Hello!", model: "tts-1", voice: "alloy")
+puts(audio.last_response.headers["x-request-id"])    # req_456
+puts(audio._request_id)                               # req_456
 ```
 
 Header names and values are normalized to strings, header names are lowercase,
@@ -932,11 +1010,12 @@ HTTP response that opened the stream. Higher-level streaming helpers expose the
 same metadata as their underlying stream; models assembled from stream events
 do not.
 
-`last_response` and `_request_id` are only populated on top-level typed models
-and pages returned by the client. They are `nil` on constructed or nested models
-and are not included in `to_h`, JSON, or YAML output. Endpoints returning raw
-primitives, binary data, or `nil` do not expose this metadata. Unlike other
-properties that begin with an underscore, `_request_id` is public.
+`last_response` and `_request_id` are only populated on top-level models,
+pages, streams, and direct binary `StringIO` responses returned by the client.
+They are `nil` on constructed or nested models, unavailable on primitive or
+union-backed plain-text fallbacks, and are not included in `to_h`, JSON, or
+YAML output. Endpoints returning `nil` have no object that can carry metadata.
+Unlike other properties that begin with an underscore, `_request_id` is public.
 
 For failed HTTP requests, catch `OpenAI::Errors::APIStatusError` and use
 `request_id`:
@@ -957,7 +1036,15 @@ for more information.
 
 Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
 
-Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
+Requests are automatically retried only when their bodies are replayable. For
+those requests, after transport execution begins, connection errors (for
+example, due to a network connectivity problem) and timeouts are retried by
+default only when the transport proves that no request bytes were sent, for
+idempotent HTTP methods, or for requests carrying a non-empty
+`Idempotency-Key` header. Failures before transport execution retain the
+configured retry behavior because no request has been dispatched.
+408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors
+are retried by default regardless of the HTTP method.
 
 You can use the `max_retries` option to configure or disable this:
 
@@ -1016,7 +1103,11 @@ openai.chat.completions.create(
 
 On timeout, `OpenAI::Errors::APITimeoutError` is raised.
 
-Note that requests that time out are retried by default.
+After transport execution begins, requests with replayable bodies that time out
+are retried by default only when the transport proves that no request bytes
+were sent, for idempotent HTTP methods, or for requests carrying a non-empty
+`Idempotency-Key` header. Timeouts before transport execution retain the
+configured retry behavior.
 
 ## Advanced concepts
 

data/docs/architecture/security-model.md

@@ -126,8 +126,21 @@ Important boundaries:
 - Authenticated Realtime handshakes are a transport boundary distinct from
   event parsing. Bearer credentials, caller-selected WebSocket destinations,
   TLS, proxy credentials, and traces must remain bound to their intended
-  origin and diagnostic audience
-  (`lib/openai/helpers/realtime/client_extension.rb:167-280`,
+  origin and diagnostic audience. Bearer credentials, including ephemeral
+  client secrets passed to client apps, authenticate the handshake before any
+  typed event is sent; post-handshake transcription `session.update` events
+  carry configuration rather than a client secret. The legacy generated
+  `TranscriptionSessionUpdatedEvent` model requires a `client_secret` even
+  though its own documentation says WebSocket updates omit it, but that model
+  is not in the helper's active server-event union: the parser treats its
+  `transcription_session.updated` discriminator as unknown, while current
+  transcription updates use `session.updated`
+  (`lib/openai/helpers/websocket/client_request.rb:89-113`,
+  `lib/openai/helpers/realtime/connection_resources.rb:25-31`,
+  `lib/openai/resources/realtime/client_secrets.rb:10-45`,
+  `lib/openai/models/realtime/transcription_session_updated_event.rb:13-49`,
+  `lib/openai/models/realtime/realtime_server_event.rb:192-199`,
+  `lib/openai/helpers/realtime/connection.rb:32-49`,
   `lib/openai/helpers/realtime/transports/async_websocket.rb:185-224`,
   `lib/openai/helpers/realtime/transports/async_websocket.rb:294-378`).
 - Multipart upload serialization is a file-path and header-integrity boundary.
@@ -206,6 +219,19 @@ PR CI. A contributor who can modify those tracked files does not gain a new
 privilege merely because CI executes them. Do not report that execution alone
 as a security finding.
 
+Dormant developer helpers are not security controls merely because their names
+suggest compatibility or safety verification. At this revision,
+`scripts/detect-breaking-changes` is not invoked by any tracked workflow or
+tracked required job; when a contributor explicitly runs it, it replaces
+selected tests with historical versions and invokes lint rather than runtime
+assertions.
+That can affect contributor confidence or release-quality review, but without a
+privileged workflow invocation or an independent lower-trust path to a sensitive
+sink, it is not a repository security boundary. Reassess this classification if
+the helper becomes a required or privileged workflow control; otherwise treat
+ordinary compatibility regressions as product/release-quality issues unless they
+independently violate a runtime security invariant.
+
 That rule does not suppress a real finding when independently mutable
 lower-trust input crosses a parser/evaluator boundary, untrusted runtime/API/
 network data reaches a sensitive sink, candidate code can reach sensitive

data/examples/audio/record_and_play.rb

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# typed: strict
+
+require "openai"
+require "openai/helpers/local_audio"
+
+# Running this example explicitly records five seconds from the selected local
+# microphone and sends that recording to OpenAI. FFmpeg and FFplay are required.
+TRANSCRIPTION_MODEL = "gpt-transcribe"
+SPEECH_MODEL = "gpt-4o-mini-tts"
+VOICE = "marin"
+
+client = OpenAI::Client.new
+clip = OpenAI::LocalAudio.record(duration: 5, timeout: 10)
+transcription = client.audio.transcriptions.create(model: TRANSCRIPTION_MODEL, file: clip)
+puts(transcription.text)
+speech = client.audio.speech.create(model: SPEECH_MODEL, voice: VOICE, input: "Recording complete.")
+OpenAI::LocalAudio.play(speech, timeout: 30)

data/examples/responses/websocket_workflows.rb

@@ -0,0 +1,159 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "async"
+
+require_relative "../../lib/openai"
+
+module OpenAI
+  module Examples
+    module ResponsesWebSocketWorkflows
+      module_function
+
+      # One reader drains all requested lanes. This example fails the entire
+      # operation on an error; applications can instead isolate lane-scoped errors.
+      def completed_responses(connection, lanes: [nil])
+        pending = lanes.dup
+        responses = {}
+        connection.each do |event|
+          case event.type.to_s
+          when "response.completed"
+            next unless pending.include?(event.stream_id)
+
+            responses[event.stream_id] = event.response
+            pending.delete(event.stream_id)
+            break if pending.empty?
+          when "response.failed", "response.incomplete", "error"
+            raise "Responses WebSocket operation did not complete."
+          end
+        end
+
+        raise "Responses WebSocket closed with unfinished work." unless pending.empty?
+
+        responses
+      end
+
+      def tools(client:, model:)
+        client.responses.connect do |connection|
+          connection.response.create(
+            model: model,
+            input: "What day will my example delivery arrive?",
+            tools: [
+              {
+                type: :function,
+                name: "get_delivery_day",
+                description: "Return the day of the example delivery.",
+                parameters: {type: :object, properties: {}, required: [], additionalProperties: false},
+                strict: true
+              }
+            ],
+            tool_choice: {type: :function, name: "get_delivery_day"},
+            parallel_tool_calls: false,
+            store: false
+          )
+          first = completed_responses(connection).fetch(nil)
+          calls = first.output.select { |item| item.type.to_s == "function_call" }
+          unless calls.length == 1 && calls.first.name == "get_delivery_day"
+            raise "Expected the example delivery tool call."
+          end
+
+          # Execute only this application's known tool. Never eval model output.
+          connection.response.create(
+            model: model,
+            previous_response_id: first.id,
+            input: [{type: :function_call_output, call_id: calls.first.call_id, output: "Tuesday"}],
+            store: false
+          )
+          completed_responses(connection)
+        end
+      end
+
+      def multiplex(client:, model:)
+        client.responses.connect do |connection|
+          %w[planner critic].each do |lane|
+            connection.response.create(
+              model: model,
+              input: "Say hello as the #{lane}.",
+              stream_id: lane,
+              store: false
+            )
+          end
+
+          completed_responses(connection, lanes: %w[planner critic])
+        end
+      end
+
+      # Deliberately rotate a healthy connection after a completed turn. This does
+      # not retry a failed write or assume an unfinished response was accepted.
+      def reconnect(client:, model:, store:)
+        input = [{role: :user, content: "Remember the example delivery day: Tuesday."}]
+        first = client.responses.connect do |connection|
+          connection.response.create(
+            model: model,
+            input: input,
+            store: store,
+            include: ["reasoning.encrypted_content"]
+          )
+          completed_responses(connection).fetch(nil)
+        end
+
+        follow_up = {role: :user, content: "What is the example delivery day?"}
+        client.responses.connect do |connection|
+          if store
+            connection.response.create(
+              model: model,
+              input: [follow_up],
+              previous_response_id: first.id,
+              store: true
+            )
+          else
+            # Preserve every output item, including encrypted reasoning. The new
+            # connection cannot use the old connection's store=false cache.
+            connection.response.create(
+              model: model,
+              input: input + first.output + [follow_up],
+              store: false
+            )
+          end
+
+          completed_responses(connection)
+        end
+      end
+
+      def run(client:, model:, workflow:, timeout: 60, output: $stdout)
+        Sync do |task|
+          task.with_timeout(timeout) do
+            case workflow
+            when "tools"
+              tools(client: client, model: model)
+            when "multiplex"
+              multiplex(client: client, model: model)
+            when "stored"
+              reconnect(client: client, model: model, store: true)
+            when "stateless"
+              reconnect(client: client, model: model, store: false)
+            else
+              raise ArgumentError, "Choose tools, multiplex, stored, or stateless."
+            end
+          end
+        end
+
+        output.puts("Responses WebSocket workflow completed.")
+      end
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    OpenAI::Examples::ResponsesWebSocketWorkflows.run(
+      client: OpenAI::Client.new,
+      model: ENV.fetch("OPENAI_RESPONSES_MODEL", "gpt-5.2"),
+      workflow: ARGV.fetch(0, "multiplex"),
+      timeout: Float(ENV.fetch("OPENAI_RESPONSES_TIMEOUT", "60"))
+    )
+  rescue StandardError
+    warn("Responses WebSocket workflow failed; no request or response contents were logged.")
+    exit(1)
+  end
+end

data/lib/openai/auth/workload_identity_auth.rb

@@ -355,7 +355,7 @@ module OpenAI
             OpenAI::Errors::OAuthError.new(
               status: response.code.to_i,
               body: body,
-              headers: response.to_hash
+              headers: response.each_header.to_h
             )
           )
         in Net::HTTPSuccess
@@ -368,7 +368,7 @@ module OpenAI
             OpenAI::Errors::APIError.new(
               url: @token_exchange_url,
               status: response.code.to_i,
-              headers: response.to_hash,
+              headers: response.each_header.to_h,
               body: body,
               message: "Token exchange failed with status #{response.code}"
             )

data/lib/openai/auth/x509_token_exchange.rb

@@ -74,7 +74,13 @@ module OpenAI
 
         raise_error(response, body)
       rescue OpenAI::Errors::APIConnectionError => error
-        raise error.class.new(url: URI(TOKEN_URL)), cause: nil
+        raise(
+          error.class.new(
+            url: URI(TOKEN_URL),
+            request_may_have_been_sent: error.request_may_have_been_sent?
+          ),
+          cause: nil
+        )
       end
 
       private def remaining_timeout(deadline)

data/lib/openai/auth/x509_transport.rb

@@ -116,21 +116,39 @@ module OpenAI
           native_response
 
         rescue OpenAI::Errors::APIConnectionError => error
-          raise error.class.new(url: sanitized_url(url)), cause: nil
+          raise(
+            error.class.new(
+              url: sanitized_url(url),
+              request_may_have_been_sent: error.request_may_have_been_sent?
+            ),
+            cause: nil
+          )
         end
 
         stream = Enumerator.new do |chunks|
           response.body.each { |chunk| chunks << chunk }
 
         rescue OpenAI::Errors::APIConnectionError => error
-          raise error.class.new(url: sanitized_url(url)), cause: nil
+          raise(
+            error.class.new(
+              url: sanitized_url(url),
+              request_may_have_been_sent: error.request_may_have_been_sent?
+            ),
+            cause: nil
+          )
         end
 
         body = OpenAI::Internal::Util.fused_enum(stream) do
           OpenAI::Internal::Util.close_fused!(response.body)
 
         rescue OpenAI::Errors::APIConnectionError => error
-          raise error.class.new(url: sanitized_url(url)), cause: nil
+          raise(
+            error.class.new(
+              url: sanitized_url(url),
+              request_may_have_been_sent: error.request_may_have_been_sent?
+            ),
+            cause: nil
+          )
         end
 
         OpenAI::HTTPClient::Response.new(status: response.status, headers: response.headers, body: body)