openai 0.80.0 → 0.81.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04e35fa6de9362524ec8eb2967901334c36bc49af09ac5e3b1a5ca2b7cac0a79
-  data.tar.gz: bc0d81dc930ca951a59c5470444728d9152abad4bc7ed86e22738819718d8115
+  metadata.gz: 97ce6ca6902b7dc85c97989c0555036a7fe45783129a2139186d0cee87f36cb0
+  data.tar.gz: 15132d79dd284edb8fa80e3f6d0a72a7b0345285770182b93e6d3e376218c9ae
 SHA512:
-  metadata.gz: 72ee61370ccfd94c541c06726fc17fcf3a1626234a6fd10259f1a2a1fda4b56ccaf6bc02c3dfea7f5142cd568abf073c6382fd6878c0a6185c1f27e71eaee5df
-  data.tar.gz: 9258b2d20da4c2a5bd4c509bd5f55505921a96fc1db97a421f2679f5ae2316fd33729d3f6fcf1130f0964aec1e5a8334c07db38afd2a8443ce7cd2037e45b065
+  metadata.gz: 21a457fa9fcbf0a59f7ed109acee5a0d55b47a757d9d1a0dfbc12fee70a07cf3766d0369c512a923d117f6a1f6c2179810d8f81c5edf48ba7e7de18c611c083f
+  data.tar.gz: 1d0bc3c3de8bd6180b293e14ae6b4b15cead9feb6a8fe6ae49bf65fc140c3d7f6a473fa75d7f85a1436be47ab3ec7fdaaf38b9164746a7b293c19a861482d107

data/CHANGELOG.md

@@ -1,5 +1,95 @@
 # Changelog
 
+## [0.81.0](https://github.com/openai/openai-ruby/compare/v0.80.0...v0.81.0) (2026-08-26)
+
+
+### Features
+
+* Add client.with_options support ([#438](https://github.com/openai/openai-ruby/issues/438)) ([72b0927](https://github.com/openai/openai-ruby/commit/72b0927f77f5393ed7c2afa07e31043f8f6717b4))
+* add Realtime transcription over WebSockets ([#445](https://github.com/openai/openai-ruby/issues/445)) ([e9f45c4](https://github.com/openai/openai-ruby/commit/e9f45c4a766705833c54ff8c58949ce5c5256618))
+* add Realtime WebSocket core ([#443](https://github.com/openai/openai-ruby/issues/443)) ([aba0f05](https://github.com/openai/openai-ruby/commit/aba0f05c9c603a286cd3c29a36aedb2bbd51c270))
+* **api:** add file and vector store polling helpers ([#421](https://github.com/openai/openai-ruby/issues/421)) ([2cad0f7](https://github.com/openai/openai-ruby/commit/2cad0f773d954c719afdfd0cc42316fe79e5fc65))
+* **api:** Add obfuscation field to ChatCompletionChunk ([#484](https://github.com/openai/openai-ruby/issues/484)) ([5065a37](https://github.com/openai/openai-ruby/commit/5065a37880e50d5c77cc2e64e610e60df8d102b6))
+* **api:** add project residency and cost quantity units ([#522](https://github.com/openai/openai-ruby/issues/522)) ([b0abe2b](https://github.com/openai/openai-ruby/commit/b0abe2bd1e30eda6acb4d5e4603001b830074be2))
+* **api:** support backend-mediated Realtime WebRTC calls ([#531](https://github.com/openai/openai-ruby/issues/531)) ([6ec6c7a](https://github.com/openai/openai-ruby/commit/6ec6c7a696081ca007cf5a325430a674870b00bc))
+* **auth:** add caller-attested X.509 transport capability ([#523](https://github.com/openai/openai-ruby/issues/523)) ([712f3c8](https://github.com/openai/openai-ruby/commit/712f3c84453006583dae5850008ea18101d01756))
+* **auth:** simplify and harden X.509 workload identity ([#535](https://github.com/openai/openai-ruby/issues/535)) ([5b32861](https://github.com/openai/openai-ruby/commit/5b32861466af5d08679cfb2329e53b17f77a4af7))
+* **realtime:** add sideband WebSocket call control ([#530](https://github.com/openai/openai-ruby/issues/530)) ([2fea73b](https://github.com/openai/openai-ruby/commit/2fea73b26b15c571d60d8f6c789a03547a025e1a))
+* update streaming models and regional endpoint selection ([#442](https://github.com/openai/openai-ruby/issues/442)) ([f2e94ab](https://github.com/openai/openai-ruby/commit/f2e94abf63d13fd651df1eea42a43859675bd87d))
+
+
+### Bug Fixes
+
+* align nullable collection matchers ([#497](https://github.com/openai/openai-ruby/issues/497)) ([ee922b3](https://github.com/openai/openai-ruby/commit/ee922b36ec6e646b8e25988866feb26bcd3845b1)), closes [#376](https://github.com/openai/openai-ruby/issues/376)
+* **api:** integrate Realtime WebRTC calls with sideband control ([#533](https://github.com/openai/openai-ruby/issues/533)) ([fd220ef](https://github.com/openai/openai-ruby/commit/fd220ef63d5f5d21c1975ec686a529df5d3d3ef3))
+* attach partial completion to streaming length errors ([#432](https://github.com/openai/openai-ruby/issues/432)) ([2dd3eab](https://github.com/openai/openai-ruby/commit/2dd3eab167eb44800eafddd687f073c14c5f6227))
+* **auth:** harden X.509 refresh and diagnostic boundaries ([#529](https://github.com/openai/openai-ruby/issues/529)) ([dd0a37c](https://github.com/openai/openai-ruby/commit/dd0a37cb1783adc7282603d8d2c9a8f11319b205))
+* **ci:** require fail-closed CodeQL checks for Ruby and GitHub Actions ([#480](https://github.com/openai/openai-ruby/issues/480)) ([8d716b6](https://github.com/openai/openai-ruby/commit/8d716b657973ac759e2fe8e56e3158698b7f6451))
+* **ci:** update Bedrock lockfile during releases ([#509](https://github.com/openai/openai-ruby/issues/509)) ([ccabba8](https://github.com/openai/openai-ruby/commit/ccabba8890c877e5206424a3fce34b9d3d460037))
+* fix Page#next_page to raise when unavailable ([#487](https://github.com/openai/openai-ruby/issues/487)) ([4d7bb33](https://github.com/openai/openai-ruby/commit/4d7bb338c7aebdd95581de9bc92084a6019cac83))
+* ignore response stream keepalive events ([#422](https://github.com/openai/openai-ruby/issues/422)) ([0182edd](https://github.com/openai/openai-ruby/commit/0182edd4ef84ec17d3f03757c04418cec2e228b9)), closes [#287](https://github.com/openai/openai-ruby/issues/287)
+* improve API status error diagnostics ([#472](https://github.com/openai/openai-ruby/issues/472)) ([eab2b2a](https://github.com/openai/openai-ruby/commit/eab2b2a0a42af10d1b83fd75bb3ef2c04ad4a137))
+* isolate union coercion state ([#446](https://github.com/openai/openai-ruby/issues/446)) ([5a7752a](https://github.com/openai/openai-ruby/commit/5a7752a14dcb932a85d760aff7d0665c8f6a615d))
+* keep authenticated requests on the configured origin ([#470](https://github.com/openai/openai-ruby/issues/470)) ([3978736](https://github.com/openai/openai-ruby/commit/3978736b0e5b7fb9bae3d1a851d917ddf9589080))
+* keep CodeQL action updates atomic ([#473](https://github.com/openai/openai-ruby/issues/473)) ([1dc83e5](https://github.com/openai/openai-ruby/commit/1dc83e58e4a00c128db7f5249de15cbe3e65988a))
+* normalize filenames inferred from file handles ([#468](https://github.com/openai/openai-ruby/issues/468)) ([d8cba3f](https://github.com/openai/openai-ruby/commit/d8cba3f770414323f313b0eddb2be1e74ee308eb))
+* omit URL fragments from diagnostic logs ([#466](https://github.com/openai/openai-ruby/issues/466)) ([7bfb7c4](https://github.com/openai/openai-ruby/commit/7bfb7c48b14eb065e598e1a5d3c37b59a83e912e))
+* preserve derived pagination cursors ([#489](https://github.com/openai/openai-ruby/issues/489)) ([e6346e3](https://github.com/openai/openai-ruby/commit/e6346e39f40112c700ade380ee87b930c000efb7))
+* preserve generic request authentication precedence ([#476](https://github.com/openai/openai-ruby/issues/476)) ([14695dc](https://github.com/openai/openai-ruby/commit/14695dc24b9929aa22b19b458b9a02e9bf5332f6))
+* preserve nullable nil values ([#450](https://github.com/openai/openai-ruby/issues/450)) ([79cc156](https://github.com/openai/openai-ruby/commit/79cc15696bdb4255396a165b9a687e177c26f26c))
+* preserve request boundaries across redirects ([#471](https://github.com/openai/openai-ruby/issues/471)) ([48be3b5](https://github.com/openai/openai-ruby/commit/48be3b5084eff7fe88db3022c154bb2fe8c929c5))
+* redact credentials from client inspect ([#488](https://github.com/openai/openai-ruby/issues/488)) ([b78194a](https://github.com/openai/openai-ruby/commit/b78194ab19e3a3de8ea594778dd17c5635e9c767))
+* remove runtime base64 dependency ([#454](https://github.com/openai/openai-ruby/issues/454)) ([d4415dd](https://github.com/openai/openai-ruby/commit/d4415dd4b2b1ab8f252e8b42bf732c17f0435012))
+* require authority when validating request origins ([#483](https://github.com/openai/openai-ruby/issues/483)) ([35acd86](https://github.com/openai/openai-ruby/commit/35acd86f5f0d402bfe29167efd89bd49fc65c926))
+* retain collection conversion errors ([#495](https://github.com/openai/openai-ruby/issues/495)) ([851f534](https://github.com/openai/openai-ruby/commit/851f53438f5afc7f32e3ccbe866fd03bbade576a))
+* **streaming:** keep indexed snapshots compact ([#490](https://github.com/openai/openai-ruby/issues/490)) ([0491bb7](https://github.com/openai/openai-ruby/commit/0491bb7ae7dd465c48aa1b84496b2e6d7e3597ea))
+* Validate multipart file content types ([#467](https://github.com/openai/openai-ruby/issues/467)) ([313f3a3](https://github.com/openai/openai-ruby/commit/313f3a3aca66cc4b3095f1b3e1b88980c49535a4))
+
+
+### Chores
+
+* **api:** Clarify image background and realtime audio-delta docs ([#499](https://github.com/openai/openai-ruby/issues/499)) ([d873fcf](https://github.com/openai/openai-ruby/commit/d873fcf645347ab771b5f92ec8598fb3f83a0c7f))
+* **api:** enforce signature formatting and canonicalize generated Ruby ([#451](https://github.com/openai/openai-ruby/issues/451)) ([38440f2](https://github.com/openai/openai-ruby/commit/38440f215f9c89a1f3290377f1e708b1ca9b0c34))
+* **api:** refresh image model docs and generated lint policy ([#486](https://github.com/openai/openai-ruby/issues/486)) ([589d384](https://github.com/openai/openai-ruby/commit/589d38401fd3f88f4381e52a47914d65730660f9))
+* **api:** refresh SDK generation metadata ([#512](https://github.com/openai/openai-ruby/issues/512)) ([3ddbc77](https://github.com/openai/openai-ruby/commit/3ddbc77f24da7d57b840ea9819a0fe0e7709b789))
+* **ci:** upgrade actions/checkout to v7.0.1 ([#475](https://github.com/openai/openai-ruby/issues/475)) ([4fecd5b](https://github.com/openai/openai-ruby/commit/4fecd5b996f21b5ba52e6ca0be99a8d1782c08dd))
+* **deps-dev:** bump sorbet-runtime from 0.6.13421 to 0.6.13425 ([#493](https://github.com/openai/openai-ruby/issues/493)) ([a099412](https://github.com/openai/openai-ruby/commit/a0994122d2e19d3f1deae03b2b5f7ae5d2bf22cd))
+* **deps-dev:** bump syntax_tree-rbs from `f94bc30` to `2478329` ([#462](https://github.com/openai/openai-ruby/issues/462)) ([3a95231](https://github.com/openai/openai-ruby/commit/3a95231b3e75d11253acd0c82e07891cf8aaf510))
+* **deps-dev:** bump the development-dependencies group with 2 updates ([#520](https://github.com/openai/openai-ruby/issues/520)) ([c3fe427](https://github.com/openai/openai-ruby/commit/c3fe427c6e9d9fad78acd23118b897ab0d6c5611))
+* **deps-dev:** safely update development dependencies ([#478](https://github.com/openai/openai-ruby/issues/478)) ([69d62eb](https://github.com/openai/openai-ruby/commit/69d62eb8cc3a9c2111870ec65c885e1fb1dc574c))
+* **deps-dev:** upgrade Steep with compatible RBS diagnostics ([#474](https://github.com/openai/openai-ruby/issues/474)) ([85686e9](https://github.com/openai/openai-ruby/commit/85686e99e70973545124bedc7f7e38089593cfbb))
+* **deps:** bump actions/github-script from 7.1.0 to 9.0.0 ([#485](https://github.com/openai/openai-ruby/issues/485)) ([f55d45d](https://github.com/openai/openai-ruby/commit/f55d45de5717ee655425a101d7b1d7fe1259c22c))
+* **deps:** bump rubygems/release-gem from 1.2.0 to 1.4.1 ([#460](https://github.com/openai/openai-ruby/issues/460)) ([9faee6a](https://github.com/openai/openai-ruby/commit/9faee6ac56e15e339cfc3070983a2eb6e335639f))
+* **deps:** bump the codeql group with 2 updates ([#521](https://github.com/openai/openai-ruby/issues/521)) ([bc5f12c](https://github.com/openai/openai-ruby/commit/bc5f12c8790b5e69692115df5e5e8a7461935b63))
+* **deps:** configure Ruby and GitHub Actions Dependabot ([#439](https://github.com/openai/openai-ruby/issues/439)) ([4f57b71](https://github.com/openai/openai-ruby/commit/4f57b71ccad5cd177f017eda7fc4e7cbdabd46cd))
+* enforce outer local variable shadowing ([#433](https://github.com/openai/openai-ruby/issues/433)) ([d644765](https://github.com/openai/openai-ruby/commit/d644765d158bf33ce367f8cc43b330836d12d1e8))
+* enforce redundant enable directives ([#436](https://github.com/openai/openai-ruby/issues/436)) ([aeb8cde](https://github.com/openai/openai-ruby/commit/aeb8cde4074e2006108d271f78748846a254ee42))
+* enforce top-level return arguments ([#435](https://github.com/openai/openai-ruby/issues/435)) ([8a022a6](https://github.com/openai/openai-ruby/commit/8a022a6eda507c32b6a9c75bb3ed8b0f6e0af5d8))
+* isolate documentation dependencies ([#482](https://github.com/openai/openai-ruby/issues/482)) ([3130e59](https://github.com/openai/openai-ruby/commit/3130e59f537af05b9c2ce3be7a44c1cd7751f3ef))
+* preserve flexibly spaced RBS aliases ([#515](https://github.com/openai/openai-ruby/issues/515)) ([45e3193](https://github.com/openai/openai-ruby/commit/45e3193eb462d4edf6defef054b6c79b05795756))
+* prevent intermittent RBS formatting failures ([#528](https://github.com/openai/openai-ruby/issues/528)) ([8057a05](https://github.com/openai/openai-ruby/commit/8057a053dca400ab0796f8da6ae814a57689e396))
+* remove Tapioca development dependency ([#452](https://github.com/openai/openai-ruby/issues/452)) ([0965227](https://github.com/openai/openai-ruby/commit/09652279b7b398e68d330383c138461e1b7ea3bf))
+* restore generated webhook signature comments ([#502](https://github.com/openai/openai-ruby/issues/502)) ([a64c3bd](https://github.com/openai/openai-ruby/commit/a64c3bd8c73a74b9f2fc619770de2142e301969d))
+* set a 4,000-line custom-code budget ([#510](https://github.com/openai/openai-ruby/issues/510)) ([0706a29](https://github.com/openai/openai-ruby/commit/0706a29b26a35709df90aed86c9a9c663a7b130e))
+* **skills:** prioritize customer-impacting Ruby SDK defects ([#519](https://github.com/openai/openai-ruby/issues/519)) ([d638c57](https://github.com/openai/openai-ruby/commit/d638c57853bcd2d1afb44fdf5fc1f79e891c138e))
+* synchronize generated response signatures and tests ([#444](https://github.com/openai/openai-ruby/issues/444)) ([4effc6a](https://github.com/openai/openai-ruby/commit/4effc6a9286d6579504f0e11513f766c97d70067))
+
+
+### Documentation
+
+* add Realtime voice turn example ([#449](https://github.com/openai/openai-ruby/issues/449)) ([b18e4c7](https://github.com/openai/openai-ruby/commit/b18e4c7c293ce60a9b4fbe67b4ba36ec1821a007))
+* add recurring repository improvement skill ([#491](https://github.com/openai/openai-ruby/issues/491)) ([8977731](https://github.com/openai/openai-ruby/commit/8977731a59da0bddf7098a5c62e1916c40bc4a7c))
+* **realtime:** add standard WebSocket workflows ([#500](https://github.com/openai/openai-ruby/issues/500)) ([e0dbef7](https://github.com/openai/openai-ruby/commit/e0dbef709a2419385f44d6187d12831981b9dda3))
+* **security:** standardize Ruby vulnerability reporting ([#440](https://github.com/openai/openai-ruby/issues/440)) ([2c16022](https://github.com/openai/openai-ruby/commit/2c1602281e049b55f7ae983f73af050b5d48ba6a))
+* strengthen Ruby SDK security guidance ([#437](https://github.com/openai/openai-ruby/issues/437)) ([68b5c92](https://github.com/openai/openai-ruby/commit/68b5c92e1b75da424fa521d1b612cf094f1830fe))
+
+
+### Refactors
+
+* isolate Chat Completions structured-output parsing ([#501](https://github.com/openai/openai-ruby/issues/501)) ([e0e6e42](https://github.com/openai/openai-ruby/commit/e0e6e42b7c0e39fe01f414ef844a99ab399bca19))
+* isolate file polling status loops ([#496](https://github.com/openai/openai-ruby/issues/496)) ([7ab65d8](https://github.com/openai/openai-ruby/commit/7ab65d8b6583aff4163dd527b4919368cacaf028))
+* isolate Responses structured-output parsing ([#498](https://github.com/openai/openai-ruby/issues/498)) ([2c4abe5](https://github.com/openai/openai-ruby/commit/2c4abe5e321053be32916d0df823a20f621a8d4c))
+
 ## [0.80.0](https://github.com/openai/openai-ruby/compare/v0.79.0...v0.80.0) (2026-08-17)
 
 

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.80.0"
+gem "openai", "~> 0.81.0"
 ```
 
 <!-- x-release-please-end -->
@@ -50,6 +50,37 @@ stream.each do |event|
 end
 ```
 
+### Realtime WebSockets
+
+The SDK supports block-scoped, typed Realtime WebSocket sessions for
+server-side text, committed-turn transcription, one-turn voice, WebRTC call
+creation, and sideband control of existing WebRTC or SIP calls. Add the
+optional `async-websocket` gem for WebSocket connections, then use
+`client.realtime.connect`:
+
+```ruby
+client.realtime.connect(model: "gpt-realtime-2.1") do |connection|
+  connection.session.update(type: :realtime, output_modalities: [:text])
+  connection.conversation.items.create(
+    type: :message,
+    role: :user,
+    content: [{type: :input_text, text: "Hello"}]
+  )
+  connection.response.create
+
+  connection.each do |event|
+    print(event.delta) if event.is_a?(OpenAI::Realtime::ResponseTextDeltaEvent)
+    break if event.is_a?(OpenAI::Realtime::ResponseDoneEvent)
+  end
+end
+```
+
+WebRTC calls can be created with `client.realtime.calls.create`; its HTTP
+response preserves the SDP answer and the `Location` header needed to attach a
+sideband connection. See the [Realtime WebSocket guide](realtime.md) and the runnable
+[text, transcription, voice, and sideband examples](examples/realtime/README.md)
+for lifecycle, authentication, proxy, TLS, and custom transport details.
+
 ### Pagination
 
 List methods in the OpenAI API are paginated.
@@ -112,7 +143,7 @@ puts(transcription.text)
 image = OpenAI::FilePart.new(Pathname("dog.jpg"), content_type: "image/jpeg")
 edited = openai.images.edit(
   prompt: "make this image look like a painting",
-  model: "gpt-image-1",
+  model: "gpt-image-2",
   size: "1024x1024",
   image: image
 )
@@ -122,6 +153,51 @@ puts(edited.data.first)
 
 Note that you can also pass a raw `IO` descriptor, but this disables retries, as the library can't be sure if the descriptor is a file or pipe (which cannot be rewound).
 
+#### Polling and vector store ingestion
+
+Polling helpers wait for file processing and return the final resource. Durations are
+expressed in seconds. By default, the helpers honor the API's recommended polling
+interval, fall back to 5 seconds, and stop after 30 minutes. Pass `timeout: nil` to
+wait indefinitely.
+
+To keep a finite overall deadline strict, each polling retrieval includes
+authentication and request replay time and does not perform transport-level retries.
+Pass `timeout: nil` to retain the client's configured retry behavior.
+
+```ruby
+file = openai.files.wait_for_processing(
+  file_object.id,
+  poll_interval: 2,
+  timeout: 10 * 60
+)
+
+vector_file = openai.vector_stores.files.upload_and_poll(
+  vector_store.id,
+  file: Pathname("handbook.pdf"),
+  attributes: {department: "engineering"}
+)
+
+batch = openai.vector_stores.file_batches.upload_and_poll(
+  vector_store.id,
+  files: [Pathname("one.pdf"), Pathname("two.pdf")],
+  file_ids: [file_object.id],
+  max_concurrency: 3
+)
+```
+
+The vector store helpers return terminal `failed` and `cancelled` resources instead
+of raising, so inspect `status`, `last_error`, or `file_counts` as appropriate. An
+overall polling timeout raises `OpenAI::Errors::PollingTimeoutError`; its `resource`
+attribute contains the last object returned by the API, or `nil` if the deadline
+elapsed before the first response.
+
+Batch inputs are enumerated before requests begin so the 2,000-file API limit can be
+checked without orphaning uploads. IO streams yielded by an enumerable must remain
+open until the helper returns; use paths for block-scoped lazy enumeration. Batch
+uploads are concurrent but not transactional. If one upload fails, the helper stops
+starting queued uploads and raises that error; files uploaded successfully before the
+failure remain available through the Files API.
+
 ### Custom HTTP clients
 
 `OpenAI::Client` accepts an `http_client` for advanced transport requirements.
@@ -319,6 +395,99 @@ 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.
 
+### X.509 Workload Identity (Preview)
+
+Organizations enrolled in the X.509 workload identity preview can exchange a
+client certificate for a short-lived OpenAI bearer credential. Both the token
+exchange and subsequent API request use the same caller-attested mTLS transport.
+The bearer is not cryptographically bound to the certificate; the API separately
+requires an accepted client certificate.
+
+```ruby
+require "openai"
+
+certificates = OpenSSL::X509::Certificate.load(
+  File.binread(ENV.fetch("OPENAI_CLIENT_CERTIFICATE_CHAIN"))
+)
+raise "Expected an enrolled client certificate" if certificates.empty?
+
+client_certificate, *intermediate_certificates = certificates
+client_private_key = OpenSSL::PKey.read(
+  File.binread(ENV.fetch("OPENAI_CLIENT_KEY")),
+  ENV["OPENAI_CLIENT_KEY_PASSPHRASE"]
+)
+unless client_certificate.check_private_key(client_private_key)
+  raise "The enrolled certificate and private key do not match"
+end
+
+api_origin = ENV.fetch("OPENAI_X509_API_ORIGIN", "https://mtls.api.openai.com")
+api_host = URI(api_origin).host&.downcase
+approved_hosts = ["mtls.auth.openai.com", api_host].freeze
+native_http_client = OpenAI::NetHTTPClient.new do |connection|
+  unless connection.use_ssl? && connection.port == 443 && approved_hosts.include?(connection.address.downcase)
+    raise "Refusing to present the enrolled certificate to an unexpected destination"
+  end
+
+  connection.cert = client_certificate
+  connection.extra_chain_cert = intermediate_certificates
+  connection.key = client_private_key
+end
+
+identity = OpenAI::Auth::X509WorkloadIdentity.new(
+  identity_provider_id: ENV.fetch("IDENTITY_PROVIDER_ID"),
+  service_account_id: ENV.fetch("SERVICE_ACCOUNT_ID"),
+  http_client: native_http_client,
+  api_origin: api_origin
+)
+
+client = OpenAI::Client.new(
+  api_key: nil,
+  workload_identity: identity
+)
+
+model = client.models.list.data.first
+```
+
+The identity creates its guarded transport internally and selects the matching
+mTLS API endpoint automatically. The application still owns its certificate,
+key, trust settings, and native HTTP client. Keep the selected certificate
+identity static, configure only the approved issuer and API destinations, and
+create a fresh native client and identity when rotating credentials. Clients
+derived with `with_options` share the original identity's cached token when
+their transport is unchanged.
+
+The supported X.509 API regions are global, US, and EU. Set `api_origin:` to
+`https://mtls.api.openai.com`, `https://mtls-us.api.openai.com`, or
+`https://mtls-eu.api.openai.com`; an optional `data_residency:` on the client
+must match. Direct mode rejects ambient proxies; pass `proxy: :http_connect` to
+the identity only when an HTTP CONNECT proxy is configured. HTTPS proxies are
+rejected before proxy credentials can be transmitted. Arbitrary custom
+transports, Azure/Bedrock providers, and Realtime WebSockets are not supported.
+The normal client or per-request timeout covers both token exchange and the API
+request; `timeout: nil` disables both deadlines. Preview access must be enabled
+for the organization, and mTLS can be configured for the enrolled organization
+or project.
+
+See the complete [X.509 workload identity live smoke
+example](examples/x509_workload_identity.rb). It performs a real token exchange
+and API request only when an enrolled certificate, private key, identity-provider
+ID, and mapped service-account ID are explicitly supplied.
+
+Keep these values in a private environment file outside your checkout or in a
+secret manager, then run the example without an API key:
+
+```sh
+export OPENAI_CLIENT_CERTIFICATE_CHAIN=/secure/path/client-chain.pem
+export OPENAI_CLIENT_KEY=/secure/path/client-key.pem
+export IDENTITY_PROVIDER_ID=idp_example
+export SERVICE_ACCOUNT_ID=svc_acct_example
+
+ruby examples/x509_workload_identity.rb
+```
+
+Set `OPENAI_X509_PROXY_MODE=http_connect` only when an approved HTTP CONNECT
+proxy is configured. Encrypted keys can use `OPENAI_CLIENT_KEY_PASSPHRASE`.
+
 ### Kubernetes Service Account
 
 ```ruby
@@ -627,6 +796,7 @@ Error codes are as follows:
 | HTTP >= 500      | `InternalServerError`      |
 | Other HTTP error | `APIStatusError`           |
 | Timeout          | `APITimeoutError`          |
+| Polling timeout  | `PollingTimeoutError`      |
 | Network error    | `APIConnectionError`       |
 
 ### Request logging
@@ -865,6 +1035,11 @@ response = client.request(
 )
 ```
 
+Generic requests use the ordinary API key when one is configured, even if an
+admin API key is also available. A client configured with only an admin API key
+uses that key. To explicitly use an admin API key when both credentials are
+configured, pass `security: {admin_api_key_auth: true}` to `client.request`.
+
 ### Concurrency & connection pooling
 
 `OpenAI::Client` instances using the default `OpenAI::NetHTTPClient` are threadsafe, but are only fork-safe when there are no in-flight HTTP requests. Injected HTTP clients are responsible for documenting and enforcing their own concurrency guarantees.

data/SECURITY.md

@@ -1,13 +1,42 @@
 # Security Policy
 
-## Reporting Security Issues
+## Reporting a vulnerability
 
 Please report potential security vulnerabilities through OpenAI's
 [coordinated vulnerability disclosure process](https://openai.com/policies/coordinated-vulnerability-disclosure-policy).
 For questions about that process, contact disclosure@openai.com.
 
-## Responsible Disclosure
+Do not report security vulnerabilities through public GitHub issues, pull requests, or discussions.
 
-Please allow OpenAI a reasonable amount of time to investigate and address the
-issue before making information public. Thank you for helping us keep this SDK
-and the systems it interacts with secure.
+## What to include
+
+When reporting a vulnerability, include:
+
+- The affected package or product and version, or the relevant source commit.
+- A clear description of the potential impact.
+- Sanitized reproduction steps or a minimal proof of concept.
+- Any relevant environment details or known mitigations.
+
+Do not include live credentials, API keys, customer data, or unredacted sensitive logs.
+
+For this repository, identify the `openai` gem version or relevant source
+commit, Ruby version, operating system, and any relevant provider or transport.
+When relevant, include the installation method (RubyGems, Git, or a local
+path), without sharing private registry URLs or local filesystem paths. Redact
+authorization headers, access tokens, private keys, signed URLs, prompts, model
+responses, uploaded files, and sensitive request/response bodies from logs,
+error reports, and shared diagnostics.
+
+Load API keys from environment variables or an approved secrets manager; never
+commit them to source code, examples, tests, fixtures, or generated artifacts.
+
+This policy applies to the source code in this repository and official releases
+of the `openai` Ruby gem. See [VERSIONING.md](VERSIONING.md) for supported Ruby
+versions and release policy. Older release lines remain available without
+guaranteed security fixes or backports.
+
+## Coordinated disclosure
+
+Please give the maintainers a reasonable opportunity to investigate and address the issue before public disclosure.
+
+Thank you for helping us keep this SDK and the systems it interacts with secure.

data/bedrock.md

@@ -187,6 +187,7 @@ Real AWS requests are disabled in the test suite unless `BEDROCK_LIVE_TEST=1` is
 
 ```sh
 AWS_REGION=us-east-1 BEDROCK_LIVE_TEST=1 \
+  BUNDLE_GEMFILE=gemfiles/bedrock.gemfile \
   bundle exec ruby test/openai/providers/bedrock_live_test.rb
 ```
 

data/examples/realtime/README.md

@@ -0,0 +1,220 @@
+# Realtime WebSocket examples
+
+This directory contains runnable examples for the Realtime WebSocket surface:
+
+- `websocket_text.rb` creates a typed text session, sends one user message,
+  streams assistant text, verifies a completed response, and exits.
+- `websocket_transcription.rb` uploads raw 24 kHz mono PCM16 audio, explicitly
+  commits one input turn, streams transcription deltas, verifies the matching
+  completed transcript, and exits.
+- `websocket_voice_turn.rb` uploads one raw 24 kHz mono PCM16 turn, explicitly
+  commits it, streams the assistant's PCM response to standard output, returns
+  its transcript to embedded callers, verifies a completed response, and exits.
+- `sideband.rb` attaches to an existing, application-authorized WebRTC or SIP
+  call, updates its session policy, verifies the typed update event, and exits.
+- `function_calling.rb` forces one local function call, validates and executes
+  it, submits a generic `function_call_output` item, and requires completed
+  tool and final-text responses.
+- `image_input.rb` submits one application-validated PNG or JPEG data URI with
+  a text prompt and requires completed text.
+- `mcp_approval.rb` correlates MCP discovery events, selects one advertised
+  tool, submits an approval response, waits for tool completion, and requires
+  completed follow-up text.
+
+Add the optional transport dependency and set an API key:
+
+```sh
+bundle add async-websocket
+export OPENAI_API_KEY="your-key"
+```
+
+Run the text example from the repository root:
+
+```sh
+bundle exec ruby examples/realtime/websocket_text.rb
+```
+
+A successful run prints `session.created`, `session.updated`, streamed
+assistant text, `response.done status=completed`, and finally
+`[realtime] smoke test passed`. Early connection closure, a non-completed
+response, or a completed response without text is treated as a failure.
+
+Optional environment variables:
+
+- `OPENAI_REALTIME_MODEL` — defaults to `gpt-realtime-2.1`.
+- `OPENAI_REALTIME_PROMPT` — defaults to `Say hello from Ruby.` and is not
+  echoed to diagnostic output.
+- `OPENAI_REALTIME_TIMEOUT` — overall example deadline in seconds; defaults to
+  `30`.
+
+## Call one deterministic local function
+
+```sh
+bundle exec ruby examples/realtime/function_calling.rb
+```
+
+The example configures exactly one forced function with parallel calls
+disabled. It validates the function name and the complete JSON argument shape,
+executes deterministic local code, and submits the result through
+`conversation.items.create(type: :function_call_output, ...)`. The second
+response disables tools and must finish with non-empty text. Prompts, arguments,
+tool output, and model text are not written to diagnostics.
+
+Optional environment variables:
+
+- `OPENAI_REALTIME_MODEL` — defaults to `gpt-realtime-2.1`.
+- `OPENAI_REALTIME_PROMPT` — defaults to a weather question.
+- `OPENAI_REALTIME_TIMEOUT` — overall example deadline in seconds; defaults to
+  `30`.
+
+## Send one application-validated image
+
+```sh
+OPENAI_REALTIME_IMAGE_URL='data:image/png;base64,...' \
+  bundle exec ruby examples/realtime/image_input.rb
+```
+
+The example accepts an application-validated PNG or JPEG base64 data URI and
+passes it to the Realtime API unchanged. The calling application owns image
+fetching, decoding, media-type checks, size limits, and data-URI creation; this
+SDK example deliberately does not implement an image decoder. The response text
+is returned to embedded callers, and executable diagnostics report only
+lifecycle metadata.
+
+Optional environment variables:
+
+- `OPENAI_REALTIME_IMAGE_URL` — required application-validated PNG or JPEG
+  base64 data URI.
+- `OPENAI_REALTIME_MODEL` — defaults to `gpt-realtime-2.1`.
+- `OPENAI_REALTIME_PROMPT` — defaults to a concise image-description request.
+- `OPENAI_REALTIME_TIMEOUT` — overall example deadline in seconds; defaults to
+  `30`.
+
+## Approve one discovered MCP tool
+
+Choose and operate a remote MCP server appropriate for your application; the
+SDK example deliberately does not prescribe a public endpoint.
+
+```sh
+MCP_SERVER_URL=https://your-mcp-server.example/mcp \
+MCP_APPROVED_TOOL=lookup \
+MCP_APPROVED_ARGUMENTS='{"query":"Ruby"}' \
+  bundle exec ruby examples/realtime/mcp_approval.rb
+```
+
+Tool discovery emits two independently ordered signals. The example waits for
+both `mcp_list_tools.completed` and the matching finalized
+`mcp_list_tools` conversation item before selecting the first advertised tool.
+It then validates the approval request and consults a caller-provided approval
+policy before submitting a generic `mcp_approval_response` item. The executable
+uses an exact tool-name and argument-string allowlist from the environment.
+Embedded applications can pass their own `approval_policy` callable, which
+receives `server_label:`, `tool_name:`, and `arguments:`. Missing policies and
+every result other than literal `true` deny the request. Before sending an
+approval, the example also requires the approval-request arguments to match the
+completed generated arguments; the finalized call must retain that exact
+argument string. It then correlates approved tool completion and requests a
+final response with tools disabled. Every response must complete, and the final
+`response.done` must contain non-empty text.
+
+Optional environment variables:
+
+- `MCP_SERVER_URL` — required URL for a caller-selected MCP server.
+- `MCP_APPROVED_TOOL` — required exact tool name independently allowed by the
+  application.
+- `MCP_APPROVED_ARGUMENTS` — required exact JSON argument string independently
+  allowed by the application.
+- `OPENAI_REALTIME_MODEL` — defaults to `gpt-realtime-2.1`.
+- `OPENAI_REALTIME_PROMPT` — defaults to a generic request to use the server.
+- `OPENAI_REALTIME_TIMEOUT` — overall example deadline in seconds; defaults to
+  `60`.
+
+## Control an existing WebRTC or SIP call
+
+Create a WebRTC call with `client.realtime.calls.create`, read its SDP answer
+from `response.body`, and extract its application-authorized call ID from
+`response.headers.fetch("location")`; alternatively, obtain the call ID from a
+verified `realtime.call.incoming` webhook. Then attach the Ruby control plane:
+
+```sh
+OPENAI_REALTIME_CALL_ID=rtc_example \
+  bundle exec ruby examples/realtime/sideband.rb
+```
+
+The example opens `client.realtime.connect_to_call`, updates the existing
+session instructions, requires a typed `session.updated` event confirming those
+instructions, and exits.
+Diagnostics include only lifecycle metadata, never the call ID, instructions,
+event payloads, or service error details. The existing call remains active when
+the sideband WebSocket closes; its owner must explicitly hang up when needed.
+
+Optional environment variables:
+
+- `OPENAI_REALTIME_INSTRUCTIONS` — server-side session policy; defaults to a
+  concise business-rules instruction.
+- `OPENAI_REALTIME_TIMEOUT` — overall example deadline in seconds; defaults to
+  `30`.
+
+## Transcribe one committed audio turn
+
+Convert an audio file to the input format required by the Realtime API, then
+run the transcription example:
+
+```sh
+ffmpeg -i input.wav -f s16le -acodec pcm_s16le -ac 1 -ar 24000 speech.pcm
+bundle exec ruby examples/realtime/websocket_transcription.rb speech.pcm
+```
+
+The example defaults to `gpt-transcribe`, which is intended for an explicitly
+committed audio turn over a Realtime WebSocket. It correlates transcription
+events using `item_id` and treats an early close, failed transcription, empty
+completion, or completion for the wrong item as a failure.
+
+Optional environment variables:
+
+- `OPENAI_REALTIME_TRANSCRIPTION_MODEL` — defaults to `gpt-transcribe`.
+- `OPENAI_REALTIME_TIMEOUT` — overall example deadline in seconds; defaults to
+  `60`.
+
+This example intentionally reads a file and drains its result after commit. It
+does not claim continuous microphone captioning or concurrent reader/writer
+support; those require a separately reviewed lifecycle boundary.
+
+## Send one voice turn and play the response
+
+Convert an audio file to 24 kHz mono PCM16, stream it through the voice-turn
+example, and play the response as it arrives:
+
+```sh
+ffmpeg -v error -i input.wav -f s16le -acodec pcm_s16le -ac 1 -ar 24000 - \
+  | bundle exec ruby examples/realtime/websocket_voice_turn.rb \
+  | ffplay -v error -f s16le -ar 24000 -ac 1 -
+```
+
+The executable reads raw PCM from standard input, writes only response PCM to
+standard output, and sends metadata-only diagnostics to standard error.
+`WebSocketVoiceTurn.run_with_timeout` returns the assistant transcript to
+embedded callers without printing it. Its single deadline covers the initial
+input read, network turn, and response stream. The boundary also suppresses
+path details from operating-system I/O errors and payload-bearing parser causes
+from malformed protocol events. A successful run writes non-empty response
+audio, observes `response.done status=completed`, and then prints
+`[realtime] voice turn smoke test passed` to standard error.
+
+The example intentionally does not own output filenames, overwrite policy, or
+filesystem durability. If you redirect its standard output to a file, those
+semantics belong to your shell or application.
+
+Optional environment variables:
+
+- `OPENAI_REALTIME_MODEL` — defaults to `gpt-realtime-2.1`.
+- `OPENAI_REALTIME_VOICE` — defaults to `marin`.
+- `OPENAI_REALTIME_TIMEOUT` — overall example deadline in seconds; defaults to
+  `60`.
+
+This is an explicit, committed file turn. It does not capture a microphone,
+play audio while it arrives, or claim full-duplex conversation support; those
+require a separately reviewed concurrency and device-lifecycle boundary.
+
+See the repository's [Realtime WebSocket guide](../../realtime.md) for the
+public connection API, custom transports, proxy behavior, and TLS setup.