openai 0.86.0 → 0.87.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e2fc3cef6cd029385cb528885096cbf0640df90c238752af2ef76186c578578
-  data.tar.gz: 5ab2eac3ec679b9d43a141ec43ef70b294ed09a5e4f72f9a3c272cd407cbe3dc
+  metadata.gz: e2541f0eac1ef08259b89e4baa93434e632c2c46a17b1a67e02fd25d167b77d4
+  data.tar.gz: 2d27951debe6e1fd0a42e2817cf59c02dc01d4c8ca8682070cbdd2d14d7e46db
 SHA512:
-  metadata.gz: e80dd1fe954a867a454f08d6349689d71f731f1908add8fc5d48e25605a431202cd6f9366e0c30070ae5273195b37116e33a606f6a26de89957d23bea6dd855b
-  data.tar.gz: b87d683d9a0cbc8b59fcb6ddc31b9b1a1737455d7353bf7466736a375955018946f18ba753c79362f94fec9ef9b52f70dd90405cfd94d600e407aaf0b4d64ad5
+  metadata.gz: 94c5255cec9b29f277dabe60b6825dd4a1edb7be86ce25162e25f2c6f3bf072c38a19297b047c0177c6553e2ff8bcd06a935d8a841e4b6d2e480377fd5bf667b
+  data.tar.gz: 9a638b78473f54fa9238a46e6ad8ec419bc892e94fe1303292268174d6203566f095e778631b2bb65da61191950cfedac2c31f4c1eea287a13d46b3d632ba05f

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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)
 
 

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.86.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
@@ -112,6 +117,10 @@ 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.

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/helpers/local_audio/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module LocalAudio
+    class Error < OpenAI::Errors::Error
+    end
+
+    class DependencyError < Error
+    end
+
+    class UnsupportedPlatformError < Error
+    end
+
+    class DeviceError < Error
+    end
+
+    class PlaybackError < Error
+    end
+
+    class TimeoutError < Error
+    end
+
+    class FormatError < Error
+    end
+
+  end
+end

data/lib/openai/helpers/local_audio/process.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "io/wait"
+
+module OpenAI
+  module LocalAudio
+    # An owned media child. No credentials, shell, inherited descriptors or diagnostics.
+    # @api private
+    class MediaProcess
+      ENVIRONMENT_KEYS = %w[
+        PATH
+        HOME
+        TMPDIR
+        LANG
+        LC_ALL
+        SystemRoot
+        WINDIR
+        USERPROFILE
+        APPDATA
+        LOCALAPPDATA
+        XDG_RUNTIME_DIR
+        PULSE_SERVER
+        SDL_AUDIODRIVER
+      ]
+        .freeze
+      private_constant :ENVIRONMENT_KEYS
+
+      def self.environment = ENV.to_h.slice(*ENVIRONMENT_KEYS)
+      def self.clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def self.duration(value, name:)
+        unless value.is_a?(Numeric) && value.real? && value.finite? && value.positive?
+          raise ArgumentError, "#{name} must be a positive finite number of seconds"
+        end
+
+        result = value.to_f
+        raise ArgumentError, "#{name} is not representable" unless result.finite?
+        result
+      end
+
+      def initialize(argv, input:, output:, timeout:, capture_errors: false)
+        @deadline = self.class.clock + self.class.duration(timeout, name: :timeout) unless timeout.nil?
+        @error_reader, error_writer = IO.pipe(binmode: true) if capture_errors
+        @pid = Process.spawn(
+          self.class.environment,
+          *argv,
+          in: input,
+          out: output,
+          err: error_writer || File::NULL,
+          close_others: true,
+          unsetenv_others: true
+        )
+      rescue Errno::ENOENT
+        @error_reader&.close
+        raise DependencyError.new("Install the required FFmpeg/FFplay executable on PATH."), cause: nil
+      rescue SystemCallError
+        @error_reader&.close
+        raise DeviceError.new("Cannot start the local audio executable."), cause: nil
+      ensure
+        error_writer&.close
+      end
+
+      def check_deadline
+        raise TimeoutError, "Local audio operation timed out." if @deadline && self.class.clock >= @deadline
+        errors?
+      end
+
+      # Drain at most one chunk per polling step, retaining no diagnostic content.
+      def errors?
+        if @error_reader && !@error_reader.closed?
+          chunk = @error_reader.read_nonblock(65_536, exception: false)
+          @errors = true if chunk.is_a?(String) && !chunk.empty?
+        end
+
+        !!@errors
+      end
+
+      def read(io, stop_on_exit: false)
+        loop do
+          check_deadline
+          return io.read(65_536) if io.is_a?(StringIO)
+          result = io.read_nonblock(65_536, exception: false)
+          return result unless result == :wait_readable
+          if stop_on_exit
+            reap
+            raise PlaybackError, "Audio player exited before the input ended." if @status
+          end
+
+          io.wait_readable(0.05)
+        end
+      end
+
+      def write(io, bytes)
+        offset = 0
+        while offset < bytes.bytesize
+          check_deadline
+          result = io.write_nonblock(bytes.byteslice(offset, 65_536), exception: false)
+          if result == :wait_writable
+            io.wait_writable(0.05)
+          else
+            offset += result
+          end
+        end
+
+      rescue Errno::EPIPE
+        raise PlaybackError.new("Audio player closed before receiving the input."), cause: nil
+      end
+
+      def wait
+        until @status
+          check_deadline
+          reap
+          sleep(0.01) unless @status
+        end
+
+        @status
+      end
+
+      def close
+        return unless @pid
+        reap
+        unless @status
+          signal("TERM")
+          deadline = self.class.clock + 0.25
+          until @status || self.class.clock >= deadline
+            reap
+            sleep(0.01) unless @status
+          end
+
+          unless @status
+            signal("KILL")
+            _, @status = Process.waitpid2(@pid)
+          end
+        end
+
+      ensure
+        @pid = nil
+        @error_reader&.close unless @error_reader&.closed?
+      end
+
+      private def reap
+        return if @status
+        result = Process.waitpid2(@pid, Process::WNOHANG)
+        @status = result.last if result
+      end
+
+      private def signal(name)
+        Process.kill(name, @pid)
+      rescue Errno::EINVAL
+        # Windows rejects TERM for another process; KILL still terminates it.
+        raise unless name == "TERM"
+        signal("KILL")
+      rescue Errno::ESRCH
+        nil
+      end
+    end
+  end
+end

data/lib/openai/helpers/local_audio.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require_relative "../../openai"
+require_relative "local_audio/errors"
+require_relative "local_audio/process"
+
+module OpenAI
+  # Optional local microphone and speaker helpers. Loading this file opens no devices.
+  module LocalAudio
+    class << self
+      # Record a finite mono 24 kHz WAV, ready for a multipart audio upload.
+      # @return [OpenAI::FilePart]
+      def record(duration:, device: nil, timeout: nil)
+        seconds = MediaProcess.duration(duration, name: :duration)
+        MediaProcess.duration(timeout, name: :timeout) unless timeout.nil?
+        format, source = capture_device(device)
+        reader, writer = IO.pipe(binmode: true)
+        child = nil
+        begin
+          child = MediaProcess.new(
+            [
+              "ffmpeg",
+              "-nostdin",
+              "-hide_banner",
+              "-loglevel",
+              "quiet",
+              "-f",
+              format,
+              "-i",
+              source,
+              "-t",
+              seconds.to_s,
+              "-ar",
+              "24000",
+              "-ac",
+              "1",
+              "-acodec",
+              "pcm_s16le",
+              "-f",
+              "s16le",
+              "pipe:1"
+            ],
+            input: File::NULL,
+            output: writer,
+            timeout: timeout
+          )
+          writer.close
+          pcm = +"".b
+          while (chunk = child.read(reader))
+            pcm << chunk
+          end
+
+          raise DeviceError, "Microphone capture failed." unless child.wait.success?
+          raise DeviceError, "Microphone returned no complete audio samples." if pcm.empty? || pcm.bytesize.odd?
+          audio = StringIO.new(wav_header(pcm.bytesize) << pcm)
+          OpenAI::FilePart.new(audio, filename: "audio.wav", content_type: "audio/wav")
+        ensure
+          reader.close unless reader.closed?
+          writer.close unless writer.closed?
+          child&.close
+        end
+      end
+
+      # Play encoded audio, or explicitly selected mono 24 kHz raw PCM16.
+      # The source is consumed from its current position and remains caller-owned.
+      # @return [nil]
+      def play(source, format: :auto, timeout: nil)
+        raise ArgumentError, "format must be :auto or :pcm" unless [:auto, :pcm].include?(format)
+        MediaProcess.duration(timeout, name: :timeout) unless timeout.nil?
+        io = playback_source(source)
+        reader, writer = IO.pipe(binmode: true)
+        child = nil
+        begin
+          # FFplay can exit zero on decoder/device failure. Its owner drains
+          # error output while feeding input, retaining only a boolean.
+          args = ["ffplay", "-autoexit", "-nodisp", "-nostats", "-loglevel", "error", "-protocol_whitelist", "pipe"]
+          args.concat(
+            format == :pcm ? ["-f", "s16le", "-ar", "24000", "-ch_layout", "mono"] : [
+              "-format_whitelist",
+              "wav,mp3,ogg,aac,flac"
+            ]
+          )
+          child = MediaProcess.new(
+            args + ["-i", "pipe:0"],
+            input: reader,
+            output: File::NULL,
+            capture_errors: true,
+            timeout: timeout
+          )
+          reader.close
+          bytes = 0
+          while (chunk = child.read(io, stop_on_exit: true))
+            break if chunk.empty?
+            bytes += chunk.bytesize
+            child.write(writer, chunk)
+          end
+
+          raise PlaybackError, "Audio input is empty." if bytes.zero?
+          raise FormatError, "PCM input ends with an incomplete sample." if format == :pcm && bytes.odd?
+          writer.close
+          status = child.wait
+          raise PlaybackError, "Audio playback failed." unless status.success? && !child.errors?
+          nil
+        ensure
+          reader.close unless reader.closed?
+          writer.close unless writer.closed?
+          child&.close
+        end
+      end
+
+      # @api private
+      def playback_source(source)
+        content = source.is_a?(OpenAI::FilePart) ? source.content : source
+        return content if content.is_a?(IO) || content.is_a?(StringIO)
+        return StringIO.new(content) if source.is_a?(OpenAI::FilePart) && content.is_a?(String)
+        raise ArgumentError, "source must be IO, StringIO, or a FilePart containing IO or bytes"
+      end
+
+      # @api private
+      def capture_device(device, platform: RUBY_PLATFORM)
+        unless device.nil? || device.is_a?(String) || (device.is_a?(Integer) && device >= 0)
+          raise ArgumentError, "device must be a device name or nonnegative index"
+        end
+
+        raise ArgumentError, "invalid device identifier" if device.to_s.include?("\0") || device == ""
+        case platform
+        when /darwin/
+          ["avfoundation", "none:#{device || "default"}"]
+        when /linux/
+          ["alsa", device.is_a?(Integer) ? "hw:#{device}" : (device || "default")]
+        when /mswin|mingw|cygwin/
+          raise ArgumentError, "Windows capture requires an explicit audio device name" unless device.is_a?(String)
+          ["dshow", "audio=#{device}"]
+        else
+          raise UnsupportedPlatformError, "Local capture is not supported on this platform."
+        end
+      end
+
+      # @api private
+      def wav_header(bytes)
+        format = "fmt " + [16, 1, 1, 24_000, 48_000, 2, 16].pack("VvvVVvv")
+        if bytes <= 0xFFFFFFFF - 36
+          "RIFF" + [bytes + 36].pack("V") + "WAVE" + format + "data" + [bytes].pack("V")
+        else
+          "RF64" +
+            [0xFFFFFFFF].pack("V") +
+            "WAVEds64" +
+            [28].pack("V") +
+            [bytes + 72, bytes, bytes / 2, 0].pack("Q<Q<Q<V") +
+            format +
+            "data" +
+            [0xFFFFFFFF].pack("V")
+        end
+      end
+    end
+  end
+end

data/lib/openai/helpers/realtime/connection.rb

@@ -19,8 +19,9 @@ module OpenAI
       attr_reader :input_audio_buffer
 
       # @api private
-      def initialize(socket:, url:)
-        super
+      def initialize(socket:, url:, recovery: nil)
+        super(socket: socket, url: url)
+        @recovery = recovery
         @server_event_names = discriminator_values(OpenAI::Realtime::RealtimeServerEvent)
         @client_event_names = discriminator_values(OpenAI::Realtime::RealtimeClientEvent)
         @session = OpenAI::Realtime::ConnectionResources::Session.new(self)
@@ -60,6 +61,23 @@ module OpenAI
         send_raw(encode_client_event(event))
       end
 
+      # Whether automatic recovery is opening or preparing a replacement socket.
+      def reconnecting? = @recovery ? @recovery.reconnecting? : false
+
+      # Snapshot of retained events, including the current event during a flush.
+      # These may contain sensitive application data. Normal connections return [].
+      def pending_messages = @recovery ? @recovery.pending_messages : []
+
+      # Remove and return retained events without sending them.
+      def take_pending_messages = @recovery ? @recovery.take_pending_messages : []
+
+      # Explicitly send retained events in order on the current session. Restore
+      # any required session state first. Does not retry uncertain failed writes.
+      def flush_pending
+        @recovery&.flush_pending
+        nil
+      end
+
       private def encode_client_event(event)
         if event.is_a?(Hash)
           validate_discriminator!(event, @client_event_names, kind: "client")

data/lib/openai/helpers/realtime/errors.rb

@@ -2,6 +2,24 @@
 
 module OpenAI
   module Errors
+    # A disconnected send could not be retained within the caller's byte budget.
+    class RealtimeQueueFullError < OpenAI::Errors::Error
+      def initialize = super("Realtime send queue is full; event was not accepted.")
+    end
+
+    # Terminal recovery failure. Payloads are available only through explicit
+    # accessors, never included in the message or default exception rendering.
+    class RealtimeReconnectError < OpenAI::Errors::Error
+      attr_reader :unsent_messages, :uncertain_message
+
+      # @api private
+      def initialize(message:, unsent_messages: [], uncertain_message: nil)
+        @unsent_messages = unsent_messages.dup.freeze
+        @uncertain_message = uncertain_message
+        super(message)
+      end
+    end
+
     # Raised when a Realtime WebSocket cannot be opened or used.
     class RealtimeConnectionError < OpenAI::Errors::WebSocketConnectionError
       private def default_message = "Realtime WebSocket connection error."