openai 0.22.1 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 887b4188085cb58d7d08b043bb231aaf9c911e1fde2a5b6e0494c3478491e81f
-  data.tar.gz: c4e908ee7d15fac9f59e99ab3f8adb3cb0b584990292a86fcdc2b36b660b9529
+  metadata.gz: 9e3a0c23bd15f70018f2c35d6f1de5c6f85dad6c66d1b10c8ec12f2070a7cccc
+  data.tar.gz: a91b9648024379a1fcb634cc3c41562805419945680e7ff8972dfc7233d92d09
 SHA512:
-  metadata.gz: 56484dcf1283f408c0d2025ccbe87af7ecd74e4807888630759520a0676687d7c33311d3597b61807d23589b4a5343032bd87e3f5e6277e6727b9c7aa4192058
-  data.tar.gz: 7160a979ee2c76c52762487d989f9973f5302f2551951a5403768e1d38bdd8617b4796ca2c4b5e3887f30c0a4fa5ba367670327a25d49d5a7f9403d1433cec62
+  metadata.gz: aa501862f1e017ae5cd912792154066ce4ed487e850dab2a80dc171e8fc743dce7b6371258806746d7f4c126ce2d55c573d4fe85f2214038adba919a7fc5e39a
+  data.tar.gz: bc3dcc99cc106579631b269155019b392292d7fa09ff8a419fd8d76b4bf7da04e4b1bfc1bc0b8df17063d0ce99149e282075a08a2102ac68a66a416efcfe4347

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.23.0 (2025-09-08)
+
+Full Changelog: [v0.22.1...v0.23.0](https://github.com/openai/openai-ruby/compare/v0.22.1...v0.23.0)
+
+### Features
+
+* **api:** ship the RealtimeGA API shape ([6c59e2c](https://github.com/openai/openai-ruby/commit/6c59e2c78ea130b626442e2230676afcca3a906f))
+
 ## 0.22.1 (2025-09-05)
 
 Full Changelog: [v0.22.0...v0.22.1](https://github.com/openai/openai-ruby/compare/v0.22.0...v0.22.1)

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.22.1"
+gem "openai", "~> 0.23.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/openai/models/realtime/audio_transcription.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Models
+    module Realtime
+      class AudioTranscription < OpenAI::Internal::Type::BaseModel
+        # @!attribute language
+        #   The language of the input audio. Supplying the input language in
+        #   [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`)
+        #   format will improve accuracy and latency.
+        #
+        #   @return [String, nil]
+        optional :language, String
+
+        # @!attribute model
+        #   The model to use for transcription. Current options are `whisper-1`,
+        #   `gpt-4o-transcribe-latest`, `gpt-4o-mini-transcribe`, and `gpt-4o-transcribe`.
+        #
+        #   @return [Symbol, OpenAI::Models::Realtime::AudioTranscription::Model, nil]
+        optional :model, enum: -> { OpenAI::Realtime::AudioTranscription::Model }
+
+        # @!attribute prompt
+        #   An optional text to guide the model's style or continue a previous audio
+        #   segment. For `whisper-1`, the
+        #   [prompt is a list of keywords](https://platform.openai.com/docs/guides/speech-to-text#prompting).
+        #   For `gpt-4o-transcribe` models, the prompt is a free text string, for example
+        #   "expect words related to technology".
+        #
+        #   @return [String, nil]
+        optional :prompt, String
+
+        # @!method initialize(language: nil, model: nil, prompt: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {OpenAI::Models::Realtime::AudioTranscription} for more details.
+        #
+        #   @param language [String] The language of the input audio. Supplying the input language in
+        #
+        #   @param model [Symbol, OpenAI::Models::Realtime::AudioTranscription::Model] The model to use for transcription. Current options are `whisper-1`, `gpt-4o-tra
+        #
+        #   @param prompt [String] An optional text to guide the model's style or continue a previous audio
+
+        # The model to use for transcription. Current options are `whisper-1`,
+        # `gpt-4o-transcribe-latest`, `gpt-4o-mini-transcribe`, and `gpt-4o-transcribe`.
+        #
+        # @see OpenAI::Models::Realtime::AudioTranscription#model
+        module Model
+          extend OpenAI::Internal::Type::Enum
+
+          WHISPER_1 = :"whisper-1"
+          GPT_4O_TRANSCRIBE_LATEST = :"gpt-4o-transcribe-latest"
+          GPT_4O_MINI_TRANSCRIBE = :"gpt-4o-mini-transcribe"
+          GPT_4O_TRANSCRIBE = :"gpt-4o-transcribe"
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+    end
+  end
+end

data/lib/openai/models/realtime/client_secret_create_params.rb

@@ -9,7 +9,10 @@ module OpenAI
         include OpenAI::Internal::Type::RequestParameters
 
         # @!attribute expires_after
-        #   Configuration for the ephemeral token expiration.
+        #   Configuration for the client secret expiration. Expiration refers to the time
+        #   after which a client secret will no longer be valid for creating sessions. The
+        #   session itself may continue after that time once started. A secret can be used
+        #   to create multiple sessions until it expires.
         #
         #   @return [OpenAI::Models::Realtime::ClientSecretCreateParams::ExpiresAfter, nil]
         optional :expires_after, -> { OpenAI::Realtime::ClientSecretCreateParams::ExpiresAfter }
@@ -25,7 +28,7 @@ module OpenAI
         #   Some parameter documentations has been truncated, see
         #   {OpenAI::Models::Realtime::ClientSecretCreateParams} for more details.
         #
-        #   @param expires_after [OpenAI::Models::Realtime::ClientSecretCreateParams::ExpiresAfter] Configuration for the ephemeral token expiration.
+        #   @param expires_after [OpenAI::Models::Realtime::ClientSecretCreateParams::ExpiresAfter] Configuration for the client secret expiration. Expiration refers to the time af
         #
         #   @param session [OpenAI::Models::Realtime::RealtimeSessionCreateRequest, OpenAI::Models::Realtime::RealtimeTranscriptionSessionCreateRequest] Session configuration to use for the client secret. Choose either a realtime
         #
@@ -33,15 +36,17 @@ module OpenAI
 
         class ExpiresAfter < OpenAI::Internal::Type::BaseModel
           # @!attribute anchor
-          #   The anchor point for the ephemeral token expiration. Only `created_at` is
-          #   currently supported.
+          #   The anchor point for the client secret expiration, meaning that `seconds` will
+          #   be added to the `created_at` time of the client secret to produce an expiration
+          #   timestamp. Only `created_at` is currently supported.
           #
           #   @return [Symbol, OpenAI::Models::Realtime::ClientSecretCreateParams::ExpiresAfter::Anchor, nil]
           optional :anchor, enum: -> { OpenAI::Realtime::ClientSecretCreateParams::ExpiresAfter::Anchor }
 
           # @!attribute seconds
           #   The number of seconds from the anchor point to the expiration. Select a value
-          #   between `10` and `7200`.
+          #   between `10` and `7200` (2 hours). This default to 600 seconds (10 minutes) if
+          #   not specified.
           #
           #   @return [Integer, nil]
           optional :seconds, Integer
@@ -51,14 +56,18 @@ module OpenAI
           #   {OpenAI::Models::Realtime::ClientSecretCreateParams::ExpiresAfter} for more
           #   details.
           #
-          #   Configuration for the ephemeral token expiration.
+          #   Configuration for the client secret expiration. Expiration refers to the time
+          #   after which a client secret will no longer be valid for creating sessions. The
+          #   session itself may continue after that time once started. A secret can be used
+          #   to create multiple sessions until it expires.
           #
-          #   @param anchor [Symbol, OpenAI::Models::Realtime::ClientSecretCreateParams::ExpiresAfter::Anchor] The anchor point for the ephemeral token expiration. Only `created_at` is curren
+          #   @param anchor [Symbol, OpenAI::Models::Realtime::ClientSecretCreateParams::ExpiresAfter::Anchor] The anchor point for the client secret expiration, meaning that `seconds` will b
           #
           #   @param seconds [Integer] The number of seconds from the anchor point to the expiration. Select a value be
 
-          # The anchor point for the ephemeral token expiration. Only `created_at` is
-          # currently supported.
+          # The anchor point for the client secret expiration, meaning that `seconds` will
+          # be added to the `created_at` time of the client secret to produce an expiration
+          # timestamp. Only `created_at` is currently supported.
           #
           # @see OpenAI::Models::Realtime::ClientSecretCreateParams::ExpiresAfter#anchor
           module Anchor

data/lib/openai/models/realtime/client_secret_create_response.rb

@@ -14,7 +14,7 @@ module OpenAI
         # @!attribute session
         #   The session configuration for either a realtime or transcription session.
         #
-        #   @return [OpenAI::Models::Realtime::RealtimeSessionCreateResponse, OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse]
+        #   @return [OpenAI::Models::Realtime::RealtimeSessionCreateResponse, OpenAI::Models::Realtime::RealtimeTranscriptionSessionCreateResponse]
         required :session, union: -> { OpenAI::Models::Realtime::ClientSecretCreateResponse::Session }
 
         # @!attribute value
@@ -31,7 +31,7 @@ module OpenAI
         #
         #   @param expires_at [Integer] Expiration timestamp for the client secret, in seconds since epoch.
         #
-        #   @param session [OpenAI::Models::Realtime::RealtimeSessionCreateResponse, OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse] The session configuration for either a realtime or transcription session.
+        #   @param session [OpenAI::Models::Realtime::RealtimeSessionCreateResponse, OpenAI::Models::Realtime::RealtimeTranscriptionSessionCreateResponse] The session configuration for either a realtime or transcription session.
         #
         #   @param value [String] The generated client secret value.
 
@@ -41,258 +41,19 @@ module OpenAI
         module Session
           extend OpenAI::Internal::Type::Union
 
-          # A Realtime session configuration object.
+          # A new Realtime session configuration, with an ephemeral key. Default TTL
+          # for keys is one minute.
           variant -> { OpenAI::Realtime::RealtimeSessionCreateResponse }
 
-          # A Realtime transcription session configuration object.
-          variant -> { OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse }
-
-          class RealtimeTranscriptionSessionCreateResponse < OpenAI::Internal::Type::BaseModel
-            # @!attribute id
-            #   Unique identifier for the session that looks like `sess_1234567890abcdef`.
-            #
-            #   @return [String, nil]
-            optional :id, String
-
-            # @!attribute audio
-            #   Configuration for input audio for the session.
-            #
-            #   @return [OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio, nil]
-            optional :audio,
-                     -> { OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio }
-
-            # @!attribute expires_at
-            #   Expiration timestamp for the session, in seconds since epoch.
-            #
-            #   @return [Integer, nil]
-            optional :expires_at, Integer
-
-            # @!attribute include
-            #   Additional fields to include in server outputs.
-            #
-            #   - `item.input_audio_transcription.logprobs`: Include logprobs for input audio
-            #     transcription.
-            #
-            #   @return [Array<Symbol, OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Include>, nil]
-            optional :include,
-                     -> do
-                       OpenAI::Internal::Type::ArrayOf[
-                         enum: OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Include
-                       ]
-                     end
-
-            # @!attribute object
-            #   The object type. Always `realtime.transcription_session`.
-            #
-            #   @return [String, nil]
-            optional :object, String
-
-            # @!method initialize(id: nil, audio: nil, expires_at: nil, include: nil, object: nil)
-            #   Some parameter documentations has been truncated, see
-            #   {OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse}
-            #   for more details.
-            #
-            #   A Realtime transcription session configuration object.
-            #
-            #   @param id [String] Unique identifier for the session that looks like `sess_1234567890abcdef`.
-            #
-            #   @param audio [OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio] Configuration for input audio for the session.
-            #
-            #   @param expires_at [Integer] Expiration timestamp for the session, in seconds since epoch.
-            #
-            #   @param include [Array<Symbol, OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Include>] Additional fields to include in server outputs.
-            #
-            #   @param object [String] The object type. Always `realtime.transcription_session`.
-
-            # @see OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse#audio
-            class Audio < OpenAI::Internal::Type::BaseModel
-              # @!attribute input
-              #
-              #   @return [OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input, nil]
-              optional :input,
-                       -> { OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input }
-
-              # @!method initialize(input: nil)
-              #   Configuration for input audio for the session.
-              #
-              #   @param input [OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input]
-
-              # @see OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio#input
-              class Input < OpenAI::Internal::Type::BaseModel
-                # @!attribute format_
-                #   The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
-                #
-                #   @return [String, nil]
-                optional :format_, String, api_name: :format
-
-                # @!attribute noise_reduction
-                #   Configuration for input audio noise reduction.
-                #
-                #   @return [OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::NoiseReduction, nil]
-                optional :noise_reduction,
-                         -> { OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::NoiseReduction }
-
-                # @!attribute transcription
-                #   Configuration of the transcription model.
-                #
-                #   @return [OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::Transcription, nil]
-                optional :transcription,
-                         -> { OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::Transcription }
-
-                # @!attribute turn_detection
-                #   Configuration for turn detection.
-                #
-                #   @return [OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::TurnDetection, nil]
-                optional :turn_detection,
-                         -> { OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::TurnDetection }
-
-                # @!method initialize(format_: nil, noise_reduction: nil, transcription: nil, turn_detection: nil)
-                #   Some parameter documentations has been truncated, see
-                #   {OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input}
-                #   for more details.
-                #
-                #   @param format_ [String] The format of input audio. Options are `pcm16`, `g711_ulaw`, or `g711_alaw`.
-                #
-                #   @param noise_reduction [OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::NoiseReduction] Configuration for input audio noise reduction.
-                #
-                #   @param transcription [OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::Transcription] Configuration of the transcription model.
-                #
-                #   @param turn_detection [OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::TurnDetection] Configuration for turn detection.
-
-                # @see OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input#noise_reduction
-                class NoiseReduction < OpenAI::Internal::Type::BaseModel
-                  # @!attribute type
-                  #
-                  #   @return [Symbol, OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::NoiseReduction::Type, nil]
-                  optional :type,
-                           enum: -> { OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::NoiseReduction::Type }
-
-                  # @!method initialize(type: nil)
-                  #   Configuration for input audio noise reduction.
-                  #
-                  #   @param type [Symbol, OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::NoiseReduction::Type]
-
-                  # @see OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::NoiseReduction#type
-                  module Type
-                    extend OpenAI::Internal::Type::Enum
-
-                    NEAR_FIELD = :near_field
-                    FAR_FIELD = :far_field
-
-                    # @!method self.values
-                    #   @return [Array<Symbol>]
-                  end
-                end
-
-                # @see OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input#transcription
-                class Transcription < OpenAI::Internal::Type::BaseModel
-                  # @!attribute language
-                  #   The language of the input audio. Supplying the input language in
-                  #   [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`)
-                  #   format will improve accuracy and latency.
-                  #
-                  #   @return [String, nil]
-                  optional :language, String
-
-                  # @!attribute model
-                  #   The model to use for transcription. Can be `gpt-4o-transcribe`,
-                  #   `gpt-4o-mini-transcribe`, or `whisper-1`.
-                  #
-                  #   @return [Symbol, OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::Transcription::Model, nil]
-                  optional :model,
-                           enum: -> { OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::Transcription::Model }
-
-                  # @!attribute prompt
-                  #   An optional text to guide the model's style or continue a previous audio
-                  #   segment. The
-                  #   [prompt](https://platform.openai.com/docs/guides/speech-to-text#prompting)
-                  #   should match the audio language.
-                  #
-                  #   @return [String, nil]
-                  optional :prompt, String
-
-                  # @!method initialize(language: nil, model: nil, prompt: nil)
-                  #   Some parameter documentations has been truncated, see
-                  #   {OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::Transcription}
-                  #   for more details.
-                  #
-                  #   Configuration of the transcription model.
-                  #
-                  #   @param language [String] The language of the input audio. Supplying the input language in
-                  #
-                  #   @param model [Symbol, OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::Transcription::Model] The model to use for transcription. Can be `gpt-4o-transcribe`, `gpt-4o-mini-tra
-                  #
-                  #   @param prompt [String] An optional text to guide the model's style or continue a previous audio segment
-
-                  # The model to use for transcription. Can be `gpt-4o-transcribe`,
-                  # `gpt-4o-mini-transcribe`, or `whisper-1`.
-                  #
-                  # @see OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::Transcription#model
-                  module Model
-                    extend OpenAI::Internal::Type::Enum
-
-                    GPT_4O_TRANSCRIBE = :"gpt-4o-transcribe"
-                    GPT_4O_MINI_TRANSCRIBE = :"gpt-4o-mini-transcribe"
-                    WHISPER_1 = :"whisper-1"
-
-                    # @!method self.values
-                    #   @return [Array<Symbol>]
-                  end
-                end
-
-                # @see OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input#turn_detection
-                class TurnDetection < OpenAI::Internal::Type::BaseModel
-                  # @!attribute prefix_padding_ms
-                  #
-                  #   @return [Integer, nil]
-                  optional :prefix_padding_ms, Integer
-
-                  # @!attribute silence_duration_ms
-                  #
-                  #   @return [Integer, nil]
-                  optional :silence_duration_ms, Integer
-
-                  # @!attribute threshold
-                  #
-                  #   @return [Float, nil]
-                  optional :threshold, Float
-
-                  # @!attribute type
-                  #   Type of turn detection, only `server_vad` is currently supported.
-                  #
-                  #   @return [String, nil]
-                  optional :type, String
-
-                  # @!method initialize(prefix_padding_ms: nil, silence_duration_ms: nil, threshold: nil, type: nil)
-                  #   Some parameter documentations has been truncated, see
-                  #   {OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse::Audio::Input::TurnDetection}
-                  #   for more details.
-                  #
-                  #   Configuration for turn detection.
-                  #
-                  #   @param prefix_padding_ms [Integer]
-                  #
-                  #   @param silence_duration_ms [Integer]
-                  #
-                  #   @param threshold [Float]
-                  #
-                  #   @param type [String] Type of turn detection, only `server_vad` is currently supported.
-                end
-              end
-            end
-
-            module Include
-              extend OpenAI::Internal::Type::Enum
-
-              ITEM_INPUT_AUDIO_TRANSCRIPTION_LOGPROBS = :"item.input_audio_transcription.logprobs"
-
-              # @!method self.values
-              #   @return [Array<Symbol>]
-            end
-          end
+          # A new Realtime transcription session configuration.
+          #
+          # When a session is created on the server via REST API, the session object
+          # also contains an ephemeral key. Default TTL for keys is 10 minutes. This
+          # property is not present when a session is updated via the WebSocket API.
+          variant -> { OpenAI::Realtime::RealtimeTranscriptionSessionCreateResponse }
 
           # @!method self.variants
-          #   @return [Array(OpenAI::Models::Realtime::RealtimeSessionCreateResponse, OpenAI::Models::Realtime::ClientSecretCreateResponse::Session::RealtimeTranscriptionSessionCreateResponse)]
+          #   @return [Array(OpenAI::Models::Realtime::RealtimeSessionCreateResponse, OpenAI::Models::Realtime::RealtimeTranscriptionSessionCreateResponse)]
         end
       end
     end

data/lib/openai/models/realtime/conversation_item.rb

@@ -9,7 +9,7 @@ module OpenAI
 
         discriminator :type
 
-        # A system message item in a Realtime conversation.
+        # A system message in a Realtime conversation can be used to provide additional context or instructions to the model. This is similar but distinct from the instruction prompt provided at the start of a conversation, as system messages can be added at any point in the conversation. For major changes to the conversation's behavior, use instructions, but for smaller updates (e.g. "the user is now asking about a different topic"), use system messages.
         variant :message, -> { OpenAI::Realtime::RealtimeConversationItemSystemMessage }
 
         # A user message item in a Realtime conversation.

data/lib/openai/models/realtime/conversation_item_added.rb

@@ -33,7 +33,20 @@ module OpenAI
         #   Some parameter documentations has been truncated, see
         #   {OpenAI::Models::Realtime::ConversationItemAdded} for more details.
         #
-        #   Returned when a conversation item is added.
+        #   Sent by the server when an Item is added to the default Conversation. This can
+        #   happen in several cases:
+        #
+        #   - When the client sends a `conversation.item.create` event.
+        #   - When the input audio buffer is committed. In this case the item will be a user
+        #     message containing the audio from the buffer.
+        #   - When the model is generating a Response. In this case the
+        #     `conversation.item.added` event will be sent when the model starts generating
+        #     a specific Item, and thus it will not yet have any content (and `status` will
+        #     be `in_progress`).
+        #
+        #   The event will include the full content of the Item (except when model is
+        #   generating a Response) except for audio data, which can be retrieved separately
+        #   with a `conversation.item.retrieve` event if necessary.
         #
         #   @param event_id [String] The unique ID of the server event.
         #

data/lib/openai/models/realtime/conversation_item_done.rb

@@ -35,6 +35,9 @@ module OpenAI
         #
         #   Returned when a conversation item is finalized.
         #
+        #   The event will include the full content of the Item except for audio data, which
+        #   can be retrieved separately with a `conversation.item.retrieve` event if needed.
+        #
         #   @param event_id [String] The unique ID of the server event.
         #
         #   @param item [OpenAI::Models::Realtime::RealtimeConversationItemSystemMessage, OpenAI::Models::Realtime::RealtimeConversationItemUserMessage, OpenAI::Models::Realtime::RealtimeConversationItemAssistantMessage, OpenAI::Models::Realtime::RealtimeConversationItemFunctionCall, OpenAI::Models::Realtime::RealtimeConversationItemFunctionCallOutput, OpenAI::Models::Realtime::RealtimeMcpApprovalResponse, OpenAI::Models::Realtime::RealtimeMcpListTools, OpenAI::Models::Realtime::RealtimeMcpToolCall, OpenAI::Models::Realtime::RealtimeMcpApprovalRequest] A single item within a Realtime conversation.

data/lib/openai/models/realtime/conversation_item_input_audio_transcription_completed_event.rb

@@ -17,7 +17,7 @@ module OpenAI
         required :event_id, String
 
         # @!attribute item_id
-        #   The ID of the user message item containing the audio.
+        #   The ID of the item containing the audio that is being transcribed.
         #
         #   @return [String]
         required :item_id, String
@@ -35,7 +35,8 @@ module OpenAI
         required :type, const: :"conversation.item.input_audio_transcription.completed"
 
         # @!attribute usage
-        #   Usage statistics for the transcription.
+        #   Usage statistics for the transcription, this is billed according to the ASR
+        #   model's pricing rather than the realtime model's pricing.
         #
         #   @return [OpenAI::Models::Realtime::ConversationItemInputAudioTranscriptionCompletedEvent::Usage::TranscriptTextUsageTokens, OpenAI::Models::Realtime::ConversationItemInputAudioTranscriptionCompletedEvent::Usage::TranscriptTextUsageDuration]
         required :usage,
@@ -56,9 +57,9 @@ module OpenAI
         #
         #   This event is the output of audio transcription for user audio written to the
         #   user audio buffer. Transcription begins when the input audio buffer is committed
-        #   by the client or server (in `server_vad` mode). Transcription runs
-        #   asynchronously with Response creation, so this event may come before or after
-        #   the Response events.
+        #   by the client or server (when VAD is enabled). Transcription runs asynchronously
+        #   with Response creation, so this event may come before or after the Response
+        #   events.
         #
         #   Realtime API models accept audio natively, and thus input transcription is a
         #   separate process run on a separate ASR (Automatic Speech Recognition) model. The
@@ -69,17 +70,18 @@ module OpenAI
         #
         #   @param event_id [String] The unique ID of the server event.
         #
-        #   @param item_id [String] The ID of the user message item containing the audio.
+        #   @param item_id [String] The ID of the item containing the audio that is being transcribed.
         #
         #   @param transcript [String] The transcribed text.
         #
-        #   @param usage [OpenAI::Models::Realtime::ConversationItemInputAudioTranscriptionCompletedEvent::Usage::TranscriptTextUsageTokens, OpenAI::Models::Realtime::ConversationItemInputAudioTranscriptionCompletedEvent::Usage::TranscriptTextUsageDuration] Usage statistics for the transcription.
+        #   @param usage [OpenAI::Models::Realtime::ConversationItemInputAudioTranscriptionCompletedEvent::Usage::TranscriptTextUsageTokens, OpenAI::Models::Realtime::ConversationItemInputAudioTranscriptionCompletedEvent::Usage::TranscriptTextUsageDuration] Usage statistics for the transcription, this is billed according to the ASR mode
         #
         #   @param logprobs [Array<OpenAI::Models::Realtime::LogProbProperties>, nil] The log probabilities of the transcription.
         #
         #   @param type [Symbol, :"conversation.item.input_audio_transcription.completed"] The event type, must be
 
-        # Usage statistics for the transcription.
+        # Usage statistics for the transcription, this is billed according to the ASR
+        # model's pricing rather than the realtime model's pricing.
         #
         # @see OpenAI::Models::Realtime::ConversationItemInputAudioTranscriptionCompletedEvent#usage
         module Usage

data/lib/openai/models/realtime/conversation_item_input_audio_transcription_delta_event.rb

@@ -11,7 +11,7 @@ module OpenAI
         required :event_id, String
 
         # @!attribute item_id
-        #   The ID of the item.
+        #   The ID of the item containing the audio that is being transcribed.
         #
         #   @return [String]
         required :item_id, String
@@ -35,7 +35,12 @@ module OpenAI
         optional :delta, String
 
         # @!attribute logprobs
-        #   The log probabilities of the transcription.
+        #   The log probabilities of the transcription. These can be enabled by
+        #   configurating the session with
+        #   `"include": ["item.input_audio_transcription.logprobs"]`. Each entry in the
+        #   array corresponds a log probability of which token would be selected for this
+        #   chunk of transcription. This can help to identify if it was possible there were
+        #   multiple valid options for a given chunk of transcription.
         #
         #   @return [Array<OpenAI::Models::Realtime::LogProbProperties>, nil]
         optional :logprobs,
@@ -43,18 +48,22 @@ module OpenAI
                  nil?: true
 
         # @!method initialize(event_id:, item_id:, content_index: nil, delta: nil, logprobs: nil, type: :"conversation.item.input_audio_transcription.delta")
+        #   Some parameter documentations has been truncated, see
+        #   {OpenAI::Models::Realtime::ConversationItemInputAudioTranscriptionDeltaEvent}
+        #   for more details.
+        #
         #   Returned when the text value of an input audio transcription content part is
-        #   updated.
+        #   updated with incremental transcription results.
         #
         #   @param event_id [String] The unique ID of the server event.
         #
-        #   @param item_id [String] The ID of the item.
+        #   @param item_id [String] The ID of the item containing the audio that is being transcribed.
         #
         #   @param content_index [Integer] The index of the content part in the item's content array.
         #
         #   @param delta [String] The text delta.
         #
-        #   @param logprobs [Array<OpenAI::Models::Realtime::LogProbProperties>, nil] The log probabilities of the transcription.
+        #   @param logprobs [Array<OpenAI::Models::Realtime::LogProbProperties>, nil] The log probabilities of the transcription. These can be enabled by configuratin
         #
         #   @param type [Symbol, :"conversation.item.input_audio_transcription.delta"] The event type, must be `conversation.item.input_audio_transcription.delta`.
       end

data/lib/openai/models/realtime/conversation_item_truncate_event.rb

@@ -13,7 +13,7 @@ module OpenAI
         required :audio_end_ms, Integer
 
         # @!attribute content_index
-        #   The index of the content part to truncate. Set this to 0.
+        #   The index of the content part to truncate. Set this to `0`.
         #
         #   @return [Integer]
         required :content_index, Integer
@@ -55,7 +55,7 @@ module OpenAI
         #
         #   @param audio_end_ms [Integer] Inclusive duration up to which audio is truncated, in milliseconds. If
         #
-        #   @param content_index [Integer] The index of the content part to truncate. Set this to 0.
+        #   @param content_index [Integer] The index of the content part to truncate. Set this to `0`.
         #
         #   @param item_id [String] The ID of the assistant message item to truncate. Only assistant message
         #

data/lib/openai/models/realtime/input_audio_buffer_append_event.rb

@@ -28,14 +28,19 @@ module OpenAI
         #   {OpenAI::Models::Realtime::InputAudioBufferAppendEvent} for more details.
         #
         #   Send this event to append audio bytes to the input audio buffer. The audio
-        #   buffer is temporary storage you can write to and later commit. In Server VAD
-        #   mode, the audio buffer is used to detect speech and the server will decide when
-        #   to commit. When Server VAD is disabled, you must commit the audio buffer
-        #   manually.
+        #   buffer is temporary storage you can write to and later commit. A "commit" will
+        #   create a new user message item in the conversation history from the buffer
+        #   content and clear the buffer. Input audio transcription (if enabled) will be
+        #   generated when the buffer is committed.
+        #
+        #   If VAD is enabled the audio buffer is used to detect speech and the server will
+        #   decide when to commit. When Server VAD is disabled, you must commit the audio
+        #   buffer manually. Input audio noise reduction operates on writes to the audio
+        #   buffer.
         #
         #   The client may choose how much audio to place in each event up to a maximum of
         #   15 MiB, for example streaming smaller chunks from the client may allow the VAD
-        #   to be more responsive. Unlike made other client events, the server will not send
+        #   to be more responsive. Unlike most other client events, the server will not send
         #   a confirmation response to this event.
         #
         #   @param audio [String] Base64-encoded audio bytes. This must be in the format specified by the