openai 0.8.0 → 0.10.0

data/lib/openai/internal/type/hash_of.rb

@@ -77,10 +77,14 @@ module OpenAI
         #
         # @param state [Hash{Symbol=>Object}] .
         #
-        #   @option state [Boolean, :strong] :strictness
+        #   @option state [Boolean] :translate_names
+        #
+        #   @option state [Boolean] :strictness
         #
         #   @option state [Hash{Symbol=>Object}] :exactness
         #
+        #   @option state [Class<StandardError>] :error
+        #
         #   @option state [Integer] :branched
         #
         # @return [Hash{Symbol=>Object}, Object]
@@ -89,6 +93,7 @@ module OpenAI
 
           unless value.is_a?(Hash)
             exactness[:no] += 1
+            state[:error] = TypeError.new("#{value.class} can't be coerced into #{Hash}")
             return value
           end
 

data/lib/openai/internal/type/union.rb

@@ -140,14 +140,23 @@ module OpenAI
 
         # @api private
         #
+        # Tries to efficiently coerce the given value to one of the known variants.
+        #
+        # If the value cannot match any of the known variants, the coercion is considered
+        # non-viable and returns the original value.
+        #
         # @param value [Object]
         #
         # @param state [Hash{Symbol=>Object}] .
         #
-        #   @option state [Boolean, :strong] :strictness
+        #   @option state [Boolean] :translate_names
+        #
+        #   @option state [Boolean] :strictness
         #
         #   @option state [Hash{Symbol=>Object}] :exactness
         #
+        #   @option state [Class<StandardError>] :error
+        #
         #   @option state [Integer] :branched
         #
         # @return [Object]
@@ -158,7 +167,6 @@ module OpenAI
 
           strictness = state.fetch(:strictness)
           exactness = state.fetch(:exactness)
-          state[:strictness] = strictness == :strong ? true : strictness
 
           alternatives = []
           known_variants.each do |_, variant_fn|
@@ -177,13 +185,10 @@ module OpenAI
             end
           end
 
-          case alternatives.sort_by(&:first)
+          case alternatives.sort_by!(&:first)
           in []
             exactness[:no] += 1
-            if strictness == :strong
-              message = "no possible conversion of #{value.class} into a variant of #{target.inspect}"
-              raise ArgumentError.new(message)
-            end
+            state[:error] = ArgumentError.new("no matching variant for #{value.inspect}")
             value
           in [[_, exact, coerced], *]
             exact.each { exactness[_1] += _2 }

data/lib/openai/internal/type/unknown.rb

@@ -33,14 +33,20 @@ module OpenAI
         class << self
           # @api private
           #
+          # No coercion needed for Unknown type.
+          #
           # @param value [Object]
           #
           # @param state [Hash{Symbol=>Object}] .
           #
-          #   @option state [Boolean, :strong] :strictness
+          #   @option state [Boolean] :translate_names
+          #
+          #   @option state [Boolean] :strictness
           #
           #   @option state [Hash{Symbol=>Object}] :exactness
           #
+          #   @option state [Class<StandardError>] :error
+          #
           #   @option state [Integer] :branched
           #
           # @return [Object]

data/lib/openai/models/audio/speech_create_params.rb

@@ -46,12 +46,19 @@ module OpenAI
 
         # @!attribute speed
         #   The speed of the generated audio. Select a value from `0.25` to `4.0`. `1.0` is
-        #   the default. Does not work with `gpt-4o-mini-tts`.
+        #   the default.
         #
         #   @return [Float, nil]
         optional :speed, Float
 
-        # @!method initialize(input:, model:, voice:, instructions: nil, response_format: nil, speed: nil, request_options: {})
+        # @!attribute stream_format
+        #   The format to stream the audio in. Supported formats are `sse` and `audio`.
+        #   `sse` is not supported for `tts-1` or `tts-1-hd`.
+        #
+        #   @return [Symbol, OpenAI::Models::Audio::SpeechCreateParams::StreamFormat, nil]
+        optional :stream_format, enum: -> { OpenAI::Audio::SpeechCreateParams::StreamFormat }
+
+        # @!method initialize(input:, model:, voice:, instructions: nil, response_format: nil, speed: nil, stream_format: nil, request_options: {})
         #   Some parameter documentations has been truncated, see
         #   {OpenAI::Models::Audio::SpeechCreateParams} for more details.
         #
@@ -67,6 +74,8 @@ module OpenAI
         #
         #   @param speed [Float] The speed of the generated audio. Select a value from `0.25` to `4.0`. `1.0` is
         #
+        #   @param stream_format [Symbol, OpenAI::Models::Audio::SpeechCreateParams::StreamFormat] The format to stream the audio in. Supported formats are `sse` and `audio`. `sse
+        #
         #   @param request_options [OpenAI::RequestOptions, Hash{Symbol=>Object}]
 
         # One of the available [TTS models](https://platform.openai.com/docs/models#tts):
@@ -153,6 +162,18 @@ module OpenAI
           # @!method self.values
           #   @return [Array<Symbol>]
         end
+
+        # The format to stream the audio in. Supported formats are `sse` and `audio`.
+        # `sse` is not supported for `tts-1` or `tts-1-hd`.
+        module StreamFormat
+          extend OpenAI::Internal::Type::Enum
+
+          SSE = :sse
+          AUDIO = :audio
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
       end
     end
   end

data/lib/openai/models/audio/transcription.rb

@@ -18,7 +18,13 @@ module OpenAI
         #   @return [Array<OpenAI::Models::Audio::Transcription::Logprob>, nil]
         optional :logprobs, -> { OpenAI::Internal::Type::ArrayOf[OpenAI::Audio::Transcription::Logprob] }
 
-        # @!method initialize(text:, logprobs: nil)
+        # @!attribute usage
+        #   Token usage statistics for the request.
+        #
+        #   @return [OpenAI::Models::Audio::Transcription::Usage::Tokens, OpenAI::Models::Audio::Transcription::Usage::Duration, nil]
+        optional :usage, union: -> { OpenAI::Audio::Transcription::Usage }
+
+        # @!method initialize(text:, logprobs: nil, usage: nil)
         #   Some parameter documentations has been truncated, see
         #   {OpenAI::Models::Audio::Transcription} for more details.
         #
@@ -28,6 +34,8 @@ module OpenAI
         #   @param text [String] The transcribed text.
         #
         #   @param logprobs [Array<OpenAI::Models::Audio::Transcription::Logprob>] The log probabilities of the tokens in the transcription. Only returned with the
+        #
+        #   @param usage [OpenAI::Models::Audio::Transcription::Usage::Tokens, OpenAI::Models::Audio::Transcription::Usage::Duration] Token usage statistics for the request.
 
         class Logprob < OpenAI::Internal::Type::BaseModel
           # @!attribute token
@@ -55,6 +63,115 @@ module OpenAI
           #
           #   @param logprob [Float] The log probability of the token.
         end
+
+        # Token usage statistics for the request.
+        #
+        # @see OpenAI::Models::Audio::Transcription#usage
+        module Usage
+          extend OpenAI::Internal::Type::Union
+
+          discriminator :type
+
+          # Usage statistics for models billed by token usage.
+          variant :tokens, -> { OpenAI::Audio::Transcription::Usage::Tokens }
+
+          # Usage statistics for models billed by audio input duration.
+          variant :duration, -> { OpenAI::Audio::Transcription::Usage::Duration }
+
+          class Tokens < OpenAI::Internal::Type::BaseModel
+            # @!attribute input_tokens
+            #   Number of input tokens billed for this request.
+            #
+            #   @return [Integer]
+            required :input_tokens, Integer
+
+            # @!attribute output_tokens
+            #   Number of output tokens generated.
+            #
+            #   @return [Integer]
+            required :output_tokens, Integer
+
+            # @!attribute total_tokens
+            #   Total number of tokens used (input + output).
+            #
+            #   @return [Integer]
+            required :total_tokens, Integer
+
+            # @!attribute type
+            #   The type of the usage object. Always `tokens` for this variant.
+            #
+            #   @return [Symbol, :tokens]
+            required :type, const: :tokens
+
+            # @!attribute input_token_details
+            #   Details about the input tokens billed for this request.
+            #
+            #   @return [OpenAI::Models::Audio::Transcription::Usage::Tokens::InputTokenDetails, nil]
+            optional :input_token_details,
+                     -> {
+                       OpenAI::Audio::Transcription::Usage::Tokens::InputTokenDetails
+                     }
+
+            # @!method initialize(input_tokens:, output_tokens:, total_tokens:, input_token_details: nil, type: :tokens)
+            #   Usage statistics for models billed by token usage.
+            #
+            #   @param input_tokens [Integer] Number of input tokens billed for this request.
+            #
+            #   @param output_tokens [Integer] Number of output tokens generated.
+            #
+            #   @param total_tokens [Integer] Total number of tokens used (input + output).
+            #
+            #   @param input_token_details [OpenAI::Models::Audio::Transcription::Usage::Tokens::InputTokenDetails] Details about the input tokens billed for this request.
+            #
+            #   @param type [Symbol, :tokens] The type of the usage object. Always `tokens` for this variant.
+
+            # @see OpenAI::Models::Audio::Transcription::Usage::Tokens#input_token_details
+            class InputTokenDetails < OpenAI::Internal::Type::BaseModel
+              # @!attribute audio_tokens
+              #   Number of audio tokens billed for this request.
+              #
+              #   @return [Integer, nil]
+              optional :audio_tokens, Integer
+
+              # @!attribute text_tokens
+              #   Number of text tokens billed for this request.
+              #
+              #   @return [Integer, nil]
+              optional :text_tokens, Integer
+
+              # @!method initialize(audio_tokens: nil, text_tokens: nil)
+              #   Details about the input tokens billed for this request.
+              #
+              #   @param audio_tokens [Integer] Number of audio tokens billed for this request.
+              #
+              #   @param text_tokens [Integer] Number of text tokens billed for this request.
+            end
+          end
+
+          class Duration < OpenAI::Internal::Type::BaseModel
+            # @!attribute duration
+            #   Duration of the input audio in seconds.
+            #
+            #   @return [Float]
+            required :duration, Float
+
+            # @!attribute type
+            #   The type of the usage object. Always `duration` for this variant.
+            #
+            #   @return [Symbol, :duration]
+            required :type, const: :duration
+
+            # @!method initialize(duration:, type: :duration)
+            #   Usage statistics for models billed by audio input duration.
+            #
+            #   @param duration [Float] Duration of the input audio in seconds.
+            #
+            #   @param type [Symbol, :duration] The type of the usage object. Always `duration` for this variant.
+          end
+
+          # @!method self.variants
+          #   @return [Array(OpenAI::Models::Audio::Transcription::Usage::Tokens, OpenAI::Models::Audio::Transcription::Usage::Duration)]
+        end
       end
     end
   end

data/lib/openai/models/audio/transcription_text_done_event.rb

@@ -26,7 +26,13 @@ module OpenAI
         optional :logprobs,
                  -> { OpenAI::Internal::Type::ArrayOf[OpenAI::Audio::TranscriptionTextDoneEvent::Logprob] }
 
-        # @!method initialize(text:, logprobs: nil, type: :"transcript.text.done")
+        # @!attribute usage
+        #   Usage statistics for models billed by token usage.
+        #
+        #   @return [OpenAI::Models::Audio::TranscriptionTextDoneEvent::Usage, nil]
+        optional :usage, -> { OpenAI::Audio::TranscriptionTextDoneEvent::Usage }
+
+        # @!method initialize(text:, logprobs: nil, usage: nil, type: :"transcript.text.done")
         #   Some parameter documentations has been truncated, see
         #   {OpenAI::Models::Audio::TranscriptionTextDoneEvent} for more details.
         #
@@ -39,6 +45,8 @@ module OpenAI
         #
         #   @param logprobs [Array<OpenAI::Models::Audio::TranscriptionTextDoneEvent::Logprob>] The log probabilities of the individual tokens in the transcription. Only includ
         #
+        #   @param usage [OpenAI::Models::Audio::TranscriptionTextDoneEvent::Usage] Usage statistics for models billed by token usage.
+        #
         #   @param type [Symbol, :"transcript.text.done"] The type of the event. Always `transcript.text.done`.
 
         class Logprob < OpenAI::Internal::Type::BaseModel
@@ -70,6 +78,77 @@ module OpenAI
           #
           #   @param logprob [Float] The log probability of the token.
         end
+
+        # @see OpenAI::Models::Audio::TranscriptionTextDoneEvent#usage
+        class Usage < OpenAI::Internal::Type::BaseModel
+          # @!attribute input_tokens
+          #   Number of input tokens billed for this request.
+          #
+          #   @return [Integer]
+          required :input_tokens, Integer
+
+          # @!attribute output_tokens
+          #   Number of output tokens generated.
+          #
+          #   @return [Integer]
+          required :output_tokens, Integer
+
+          # @!attribute total_tokens
+          #   Total number of tokens used (input + output).
+          #
+          #   @return [Integer]
+          required :total_tokens, Integer
+
+          # @!attribute type
+          #   The type of the usage object. Always `tokens` for this variant.
+          #
+          #   @return [Symbol, :tokens]
+          required :type, const: :tokens
+
+          # @!attribute input_token_details
+          #   Details about the input tokens billed for this request.
+          #
+          #   @return [OpenAI::Models::Audio::TranscriptionTextDoneEvent::Usage::InputTokenDetails, nil]
+          optional :input_token_details,
+                   -> {
+                     OpenAI::Audio::TranscriptionTextDoneEvent::Usage::InputTokenDetails
+                   }
+
+          # @!method initialize(input_tokens:, output_tokens:, total_tokens:, input_token_details: nil, type: :tokens)
+          #   Usage statistics for models billed by token usage.
+          #
+          #   @param input_tokens [Integer] Number of input tokens billed for this request.
+          #
+          #   @param output_tokens [Integer] Number of output tokens generated.
+          #
+          #   @param total_tokens [Integer] Total number of tokens used (input + output).
+          #
+          #   @param input_token_details [OpenAI::Models::Audio::TranscriptionTextDoneEvent::Usage::InputTokenDetails] Details about the input tokens billed for this request.
+          #
+          #   @param type [Symbol, :tokens] The type of the usage object. Always `tokens` for this variant.
+
+          # @see OpenAI::Models::Audio::TranscriptionTextDoneEvent::Usage#input_token_details
+          class InputTokenDetails < OpenAI::Internal::Type::BaseModel
+            # @!attribute audio_tokens
+            #   Number of audio tokens billed for this request.
+            #
+            #   @return [Integer, nil]
+            optional :audio_tokens, Integer
+
+            # @!attribute text_tokens
+            #   Number of text tokens billed for this request.
+            #
+            #   @return [Integer, nil]
+            optional :text_tokens, Integer
+
+            # @!method initialize(audio_tokens: nil, text_tokens: nil)
+            #   Details about the input tokens billed for this request.
+            #
+            #   @param audio_tokens [Integer] Number of audio tokens billed for this request.
+            #
+            #   @param text_tokens [Integer] Number of text tokens billed for this request.
+          end
+        end
       end
     end
   end

data/lib/openai/models/audio/transcription_verbose.rb

@@ -28,13 +28,19 @@ module OpenAI
         #   @return [Array<OpenAI::Models::Audio::TranscriptionSegment>, nil]
         optional :segments, -> { OpenAI::Internal::Type::ArrayOf[OpenAI::Audio::TranscriptionSegment] }
 
+        # @!attribute usage
+        #   Usage statistics for models billed by audio input duration.
+        #
+        #   @return [OpenAI::Models::Audio::TranscriptionVerbose::Usage, nil]
+        optional :usage, -> { OpenAI::Audio::TranscriptionVerbose::Usage }
+
         # @!attribute words
         #   Extracted words and their corresponding timestamps.
         #
         #   @return [Array<OpenAI::Models::Audio::TranscriptionWord>, nil]
         optional :words, -> { OpenAI::Internal::Type::ArrayOf[OpenAI::Audio::TranscriptionWord] }
 
-        # @!method initialize(duration:, language:, text:, segments: nil, words: nil)
+        # @!method initialize(duration:, language:, text:, segments: nil, usage: nil, words: nil)
         #   Represents a verbose json transcription response returned by model, based on the
         #   provided input.
         #
@@ -46,7 +52,31 @@ module OpenAI
         #
         #   @param segments [Array<OpenAI::Models::Audio::TranscriptionSegment>] Segments of the transcribed text and their corresponding details.
         #
+        #   @param usage [OpenAI::Models::Audio::TranscriptionVerbose::Usage] Usage statistics for models billed by audio input duration.
+        #
         #   @param words [Array<OpenAI::Models::Audio::TranscriptionWord>] Extracted words and their corresponding timestamps.
+
+        # @see OpenAI::Models::Audio::TranscriptionVerbose#usage
+        class Usage < OpenAI::Internal::Type::BaseModel
+          # @!attribute duration
+          #   Duration of the input audio in seconds.
+          #
+          #   @return [Float]
+          required :duration, Float
+
+          # @!attribute type
+          #   The type of the usage object. Always `duration` for this variant.
+          #
+          #   @return [Symbol, :duration]
+          required :type, const: :duration
+
+          # @!method initialize(duration:, type: :duration)
+          #   Usage statistics for models billed by audio input duration.
+          #
+          #   @param duration [Float] Duration of the input audio in seconds.
+          #
+          #   @param type [Symbol, :duration] The type of the usage object. Always `duration` for this variant.
+        end
       end
     end
   end

data/lib/openai/models/chat/chat_completion.rb

@@ -213,6 +213,7 @@ module OpenAI
           AUTO = :auto
           DEFAULT = :default
           FLEX = :flex
+          SCALE = :scale
 
           # @!method self.values
           #   @return [Array<Symbol>]

data/lib/openai/models/chat/chat_completion_chunk.rb

@@ -396,6 +396,7 @@ module OpenAI
           AUTO = :auto
           DEFAULT = :default
           FLEX = :flex
+          SCALE = :scale
 
           # @!method self.values
           #   @return [Array<Symbol>]

data/lib/openai/models/chat/completion_create_params.rb

@@ -569,6 +569,7 @@ module OpenAI
           AUTO = :auto
           DEFAULT = :default
           FLEX = :flex
+          SCALE = :scale
 
           # @!method self.values
           #   @return [Array<Symbol>]

data/lib/openai/models/fine_tuning/job_create_params.rb

@@ -31,7 +31,8 @@ module OpenAI
         #   [preference](https://platform.openai.com/docs/api-reference/fine-tuning/preference-input)
         #   format.
         #
-        #   See the [fine-tuning guide](https://platform.openai.com/docs/guides/fine-tuning)
+        #   See the
+        #   [fine-tuning guide](https://platform.openai.com/docs/guides/model-optimization)
         #   for more details.
         #
         #   @return [String]
@@ -100,7 +101,8 @@ module OpenAI
         #   Your dataset must be formatted as a JSONL file. You must upload your file with
         #   the purpose `fine-tune`.
         #
-        #   See the [fine-tuning guide](https://platform.openai.com/docs/guides/fine-tuning)
+        #   See the
+        #   [fine-tuning guide](https://platform.openai.com/docs/guides/model-optimization)
         #   for more details.
         #
         #   @return [String, nil]

data/lib/openai/models/image_edit_params.rb

@@ -61,6 +61,22 @@ module OpenAI
       #   @return [Integer, nil]
       optional :n, Integer, nil?: true
 
+      # @!attribute output_compression
+      #   The compression level (0-100%) for the generated images. This parameter is only
+      #   supported for `gpt-image-1` with the `webp` or `jpeg` output formats, and
+      #   defaults to 100.
+      #
+      #   @return [Integer, nil]
+      optional :output_compression, Integer, nil?: true
+
+      # @!attribute output_format
+      #   The format in which the generated images are returned. This parameter is only
+      #   supported for `gpt-image-1`. Must be one of `png`, `jpeg`, or `webp`. The
+      #   default value is `png`.
+      #
+      #   @return [Symbol, OpenAI::Models::ImageEditParams::OutputFormat, nil]
+      optional :output_format, enum: -> { OpenAI::ImageEditParams::OutputFormat }, nil?: true
+
       # @!attribute quality
       #   The quality of the image that will be generated. `high`, `medium` and `low` are
       #   only supported for `gpt-image-1`. `dall-e-2` only supports `standard` quality.
@@ -94,7 +110,7 @@ module OpenAI
       #   @return [String, nil]
       optional :user, String
 
-      # @!method initialize(image:, prompt:, background: nil, mask: nil, model: nil, n: nil, quality: nil, response_format: nil, size: nil, user: nil, request_options: {})
+      # @!method initialize(image:, prompt:, background: nil, mask: nil, model: nil, n: nil, output_compression: nil, output_format: nil, quality: nil, response_format: nil, size: nil, user: nil, request_options: {})
       #   Some parameter documentations has been truncated, see
       #   {OpenAI::Models::ImageEditParams} for more details.
       #
@@ -110,6 +126,10 @@ module OpenAI
       #
       #   @param n [Integer, nil] The number of images to generate. Must be between 1 and 10.
       #
+      #   @param output_compression [Integer, nil] The compression level (0-100%) for the generated images. This parameter
+      #
+      #   @param output_format [Symbol, OpenAI::Models::ImageEditParams::OutputFormat, nil] The format in which the generated images are returned. This parameter is
+      #
       #   @param quality [Symbol, OpenAI::Models::ImageEditParams::Quality, nil] The quality of the image that will be generated. `high`, `medium` and `low` are
       #
       #   @param response_format [Symbol, OpenAI::Models::ImageEditParams::ResponseFormat, nil] The format in which the generated images are returned. Must be one of `url` or `
@@ -174,6 +194,20 @@ module OpenAI
         #   @return [Array(String, Symbol, OpenAI::Models::ImageModel)]
       end
 
+      # The format in which the generated images are returned. This parameter is only
+      # supported for `gpt-image-1`. Must be one of `png`, `jpeg`, or `webp`. The
+      # default value is `png`.
+      module OutputFormat
+        extend OpenAI::Internal::Type::Enum
+
+        PNG = :png
+        JPEG = :jpeg
+        WEBP = :webp
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+
       # The quality of the image that will be generated. `high`, `medium` and `low` are
       # only supported for `gpt-image-1`. `dall-e-2` only supports `standard` quality.
       # Defaults to `auto`.

data/lib/openai/models/responses/response.rb

@@ -32,15 +32,14 @@ module OpenAI
         required :incomplete_details, -> { OpenAI::Responses::Response::IncompleteDetails }, nil?: true
 
         # @!attribute instructions
-        #   Inserts a system (or developer) message as the first item in the model's
-        #   context.
+        #   A system (or developer) message inserted into the model's context.
         #
         #   When using along with `previous_response_id`, the instructions from a previous
         #   response will not be carried over to the next response. This makes it simple to
         #   swap out system (or developer) messages in new responses.
         #
-        #   @return [String, nil]
-        required :instructions, String, nil?: true
+        #   @return [String, Array<OpenAI::Models::Responses::EasyInputMessage, OpenAI::Models::Responses::ResponseInputItem::Message, OpenAI::Models::Responses::ResponseOutputMessage, OpenAI::Models::Responses::ResponseFileSearchToolCall, OpenAI::Models::Responses::ResponseComputerToolCall, OpenAI::Models::Responses::ResponseInputItem::ComputerCallOutput, OpenAI::Models::Responses::ResponseFunctionWebSearch, OpenAI::Models::Responses::ResponseFunctionToolCall, OpenAI::Models::Responses::ResponseInputItem::FunctionCallOutput, OpenAI::Models::Responses::ResponseReasoningItem, OpenAI::Models::Responses::ResponseInputItem::ImageGenerationCall, OpenAI::Models::Responses::ResponseCodeInterpreterToolCall, OpenAI::Models::Responses::ResponseInputItem::LocalShellCall, OpenAI::Models::Responses::ResponseInputItem::LocalShellCallOutput, OpenAI::Models::Responses::ResponseInputItem::McpListTools, OpenAI::Models::Responses::ResponseInputItem::McpApprovalRequest, OpenAI::Models::Responses::ResponseInputItem::McpApprovalResponse, OpenAI::Models::Responses::ResponseInputItem::McpCall, OpenAI::Models::Responses::ResponseInputItem::ItemReference>, nil]
+        required :instructions, union: -> { OpenAI::Responses::Response::Instructions }, nil?: true
 
         # @!attribute metadata
         #   Set of 16 key-value pairs that can be attached to an object. This can be useful
@@ -156,6 +155,13 @@ module OpenAI
         #   @return [String, nil]
         optional :previous_response_id, String, nil?: true
 
+        # @!attribute prompt
+        #   Reference to a prompt template and its variables.
+        #   [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts).
+        #
+        #   @return [OpenAI::Models::Responses::ResponsePrompt, nil]
+        optional :prompt, -> { OpenAI::Responses::ResponsePrompt }, nil?: true
+
         # @!attribute reasoning
         #   **o-series models only**
         #
@@ -231,7 +237,7 @@ module OpenAI
         #   @return [String, nil]
         optional :user, String
 
-        # @!method initialize(id:, created_at:, error:, incomplete_details:, instructions:, metadata:, model:, output:, parallel_tool_calls:, temperature:, tool_choice:, tools:, top_p:, background: nil, max_output_tokens: nil, previous_response_id: nil, reasoning: nil, service_tier: nil, status: nil, text: nil, truncation: nil, usage: nil, user: nil, object: :response)
+        # @!method initialize(id:, created_at:, error:, incomplete_details:, instructions:, metadata:, model:, output:, parallel_tool_calls:, temperature:, tool_choice:, tools:, top_p:, background: nil, max_output_tokens: nil, previous_response_id: nil, prompt: nil, reasoning: nil, service_tier: nil, status: nil, text: nil, truncation: nil, usage: nil, user: nil, object: :response)
         #   Some parameter documentations has been truncated, see
         #   {OpenAI::Models::Responses::Response} for more details.
         #
@@ -243,7 +249,7 @@ module OpenAI
         #
         #   @param incomplete_details [OpenAI::Models::Responses::Response::IncompleteDetails, nil] Details about why the response is incomplete.
         #
-        #   @param instructions [String, nil] Inserts a system (or developer) message as the first item in the model's context
+        #   @param instructions [String, Array<OpenAI::Models::Responses::EasyInputMessage, OpenAI::Models::Responses::ResponseInputItem::Message, OpenAI::Models::Responses::ResponseOutputMessage, OpenAI::Models::Responses::ResponseFileSearchToolCall, OpenAI::Models::Responses::ResponseComputerToolCall, OpenAI::Models::Responses::ResponseInputItem::ComputerCallOutput, OpenAI::Models::Responses::ResponseFunctionWebSearch, OpenAI::Models::Responses::ResponseFunctionToolCall, OpenAI::Models::Responses::ResponseInputItem::FunctionCallOutput, OpenAI::Models::Responses::ResponseReasoningItem, OpenAI::Models::Responses::ResponseInputItem::ImageGenerationCall, OpenAI::Models::Responses::ResponseCodeInterpreterToolCall, OpenAI::Models::Responses::ResponseInputItem::LocalShellCall, OpenAI::Models::Responses::ResponseInputItem::LocalShellCallOutput, OpenAI::Models::Responses::ResponseInputItem::McpListTools, OpenAI::Models::Responses::ResponseInputItem::McpApprovalRequest, OpenAI::Models::Responses::ResponseInputItem::McpApprovalResponse, OpenAI::Models::Responses::ResponseInputItem::McpCall, OpenAI::Models::Responses::ResponseInputItem::ItemReference>, nil] A system (or developer) message inserted into the model's context.
         #
         #   @param metadata [Hash{Symbol=>String}, nil] Set of 16 key-value pairs that can be attached to an object. This can be
         #
@@ -267,6 +273,8 @@ module OpenAI
         #
         #   @param previous_response_id [String, nil] The unique ID of the previous response to the model. Use this to
         #
+        #   @param prompt [OpenAI::Models::Responses::ResponsePrompt, nil] Reference to a prompt template and its variables.
+        #
         #   @param reasoning [OpenAI::Models::Reasoning, nil] **o-series models only**
         #
         #   @param service_tier [Symbol, OpenAI::Models::Responses::Response::ServiceTier, nil] Specifies the latency tier to use for processing the request. This parameter is
@@ -310,6 +318,32 @@ module OpenAI
           end
         end
 
+        # A system (or developer) message inserted into the model's context.
+        #
+        # When using along with `previous_response_id`, the instructions from a previous
+        # response will not be carried over to the next response. This makes it simple to
+        # swap out system (or developer) messages in new responses.
+        #
+        # @see OpenAI::Models::Responses::Response#instructions
+        module Instructions
+          extend OpenAI::Internal::Type::Union
+
+          # A text input to the model, equivalent to a text input with the
+          # `developer` role.
+          variant String
+
+          # A list of one or many input items to the model, containing
+          # different content types.
+          variant -> { OpenAI::Models::Responses::Response::Instructions::ResponseInputItemArray }
+
+          # @!method self.variants
+          #   @return [Array(String, Array<OpenAI::Models::Responses::EasyInputMessage, OpenAI::Models::Responses::ResponseInputItem::Message, OpenAI::Models::Responses::ResponseOutputMessage, OpenAI::Models::Responses::ResponseFileSearchToolCall, OpenAI::Models::Responses::ResponseComputerToolCall, OpenAI::Models::Responses::ResponseInputItem::ComputerCallOutput, OpenAI::Models::Responses::ResponseFunctionWebSearch, OpenAI::Models::Responses::ResponseFunctionToolCall, OpenAI::Models::Responses::ResponseInputItem::FunctionCallOutput, OpenAI::Models::Responses::ResponseReasoningItem, OpenAI::Models::Responses::ResponseInputItem::ImageGenerationCall, OpenAI::Models::Responses::ResponseCodeInterpreterToolCall, OpenAI::Models::Responses::ResponseInputItem::LocalShellCall, OpenAI::Models::Responses::ResponseInputItem::LocalShellCallOutput, OpenAI::Models::Responses::ResponseInputItem::McpListTools, OpenAI::Models::Responses::ResponseInputItem::McpApprovalRequest, OpenAI::Models::Responses::ResponseInputItem::McpApprovalResponse, OpenAI::Models::Responses::ResponseInputItem::McpCall, OpenAI::Models::Responses::ResponseInputItem::ItemReference>)]
+
+          # @type [OpenAI::Internal::Type::Converter]
+          ResponseInputItemArray =
+            OpenAI::Internal::Type::ArrayOf[union: -> { OpenAI::Responses::ResponseInputItem }]
+        end
+
         # How the model should select which tool (or tools) to use when generating a
         # response. See the `tools` parameter to see how to specify which tools the model
         # can call.
@@ -364,6 +398,7 @@ module OpenAI
           AUTO = :auto
           DEFAULT = :default
           FLEX = :flex
+          SCALE = :scale
 
           # @!method self.values
           #   @return [Array<Symbol>]