feat(api): Support images and files for function call outputs in responses, BatchUsage

This release introduces a major version change to reflect a breaking modification in the `ResponseFunctionToolCallOutputItem` and `ResponseCustomToolCallOutput` schemas. Specifically, the `output` field, which previously accepted only a `string` value, has been expanded to support multiple structured types:

```
Before:  output: string
After:   output: string | Array<ResponseInputText | ResponseInputImage | ResponseInputFile>
```

This change allows custom tool calls to return images, files, and rich text content in addition to plain strings, aligning `ResponseCustomToolCallOutput` with the broader `ResponseInput` type system. Because this alters the type and shape of the field, it may break existing callsites that only accept strings.

BREAKING CHANGE: `ResponseFunctionToolCallOutputItem.output` and `ResponseCustomToolCallOutput.output` now return `string | Array<ResponseInputText | ResponseInputImage | ResponseInputFile>` instead of `string` only. This may break existing callsites that assume `output` is always a string.

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 118
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-410219ea680089f02bb55163c673919703f946c3d6ad7ff5d6f607121d5287d5.yml
-openapi_spec_hash: 2b3eee95d3f6796c7a61dfddf694a59a
-config_hash: 666d6bb4b564f0d9d431124b5d1a0665
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-49233088b5e73dbb96bf7af27be3d4547632e3db1c2b00f14184900613325bbc.yml
+openapi_spec_hash: b34f14b141d5019244112901c5c7c2d8
+config_hash: 94e9ba08201c3d1ca46e093e6a0138fa

lib/openai.rb

@@ -99,6 +99,7 @@
 require_relative "openai/models/batch_list_params"
 require_relative "openai/models/batch_request_counts"
 require_relative "openai/models/batch_retrieve_params"
+require_relative "openai/models/batch_usage"
 require_relative "openai/models/beta/assistant"
 require_relative "openai/models/beta/assistant_create_params"
 require_relative "openai/models/beta/assistant_deleted"
@@ -537,6 +538,8 @@
 require_relative "openai/models/responses/response_format_text_json_schema_config"
 require_relative "openai/models/responses/response_function_call_arguments_delta_event"
 require_relative "openai/models/responses/response_function_call_arguments_done_event"
+require_relative "openai/models/responses/response_function_call_output_item"
+require_relative "openai/models/responses/response_function_call_output_item_list"
 require_relative "openai/models/responses/response_function_tool_call_item"
 require_relative "openai/models/responses/response_function_tool_call_output_item"
 require_relative "openai/models/responses/response_function_web_search"
@@ -550,9 +553,12 @@
 require_relative "openai/models/responses/response_input"
 require_relative "openai/models/responses/response_input_audio"
 require_relative "openai/models/responses/response_input_content"
+require_relative "openai/models/responses/response_input_file_content"
+require_relative "openai/models/responses/response_input_image_content"
 require_relative "openai/models/responses/response_input_item"
 require_relative "openai/models/responses/response_input_message_content_list"
 require_relative "openai/models/responses/response_input_message_item"
+require_relative "openai/models/responses/response_input_text_content"
 require_relative "openai/models/responses/response_item"
 require_relative "openai/models/responses/response_item_list"
 require_relative "openai/models/responses/response_mcp_call_arguments_delta_event"

lib/openai/models.rb

@@ -63,6 +63,8 @@ module OpenAI
 
   BatchRetrieveParams = OpenAI::Models::BatchRetrieveParams
 
+  BatchUsage = OpenAI::Models::BatchUsage
+
   Beta = OpenAI::Models::Beta
 
   Chat = OpenAI::Models::Chat

lib/openai/models/batch.rb

@@ -115,6 +115,16 @@ class Batch < OpenAI::Internal::Type::BaseModel
       #   @return [Hash{Symbol=>String}, nil]
       optional :metadata, OpenAI::Internal::Type::HashOf[String], nil?: true
 
+      # @!attribute model
+      #   Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI offers a
+      #   wide range of models with different capabilities, performance characteristics,
+      #   and price points. Refer to the
+      #   [model guide](https://platform.openai.com/docs/models) to browse and compare
+      #   available models.
+      #
+      #   @return [String, nil]
+      optional :model, String
+
       # @!attribute output_file_id
       #   The ID of the file containing the outputs of successfully executed requests.
       #
@@ -127,7 +137,15 @@ class Batch < OpenAI::Internal::Type::BaseModel
       #   @return [OpenAI::Models::BatchRequestCounts, nil]
       optional :request_counts, -> { OpenAI::BatchRequestCounts }
 
-      # @!method initialize(id:, completion_window:, created_at:, endpoint:, input_file_id:, status:, cancelled_at: nil, cancelling_at: nil, completed_at: nil, error_file_id: nil, errors: nil, expired_at: nil, expires_at: nil, failed_at: nil, finalizing_at: nil, in_progress_at: nil, metadata: nil, output_file_id: nil, request_counts: nil, object: :batch)
+      # @!attribute usage
+      #   Represents token usage details including input tokens, output tokens, a
+      #   breakdown of output tokens, and the total tokens used. Only populated on batches
+      #   created after September 7, 2025.
+      #
+      #   @return [OpenAI::Models::BatchUsage, nil]
+      optional :usage, -> { OpenAI::BatchUsage }
+
+      # @!method initialize(id:, completion_window:, created_at:, endpoint:, input_file_id:, status:, cancelled_at: nil, cancelling_at: nil, completed_at: nil, error_file_id: nil, errors: nil, expired_at: nil, expires_at: nil, failed_at: nil, finalizing_at: nil, in_progress_at: nil, metadata: nil, model: nil, output_file_id: nil, request_counts: nil, usage: nil, object: :batch)
       #   Some parameter documentations has been truncated, see {OpenAI::Models::Batch}
       #   for more details.
       #
@@ -165,10 +183,14 @@ class Batch < OpenAI::Internal::Type::BaseModel
       #
       #   @param metadata [Hash{Symbol=>String}, nil] Set of 16 key-value pairs that can be attached to an object. This can be
       #
+      #   @param model [String] Model ID used to process the batch, like `gpt-5-2025-08-07`. OpenAI
+      #
       #   @param output_file_id [String] The ID of the file containing the outputs of successfully executed requests.
       #
       #   @param request_counts [OpenAI::Models::BatchRequestCounts] The request counts for different statuses within the batch.
       #
+      #   @param usage [OpenAI::Models::BatchUsage] Represents token usage details including input tokens, output tokens, a
+      #
       #   @param object [Symbol, :batch] The object type, which is always `batch`.
 
       # The current status of the batch.

lib/openai/models/batch_usage.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Models
+    class BatchUsage < OpenAI::Internal::Type::BaseModel
+      # @!attribute input_tokens
+      #   The number of input tokens.
+      #
+      #   @return [Integer]
+      required :input_tokens, Integer
+
+      # @!attribute input_tokens_details
+      #   A detailed breakdown of the input tokens.
+      #
+      #   @return [OpenAI::Models::BatchUsage::InputTokensDetails]
+      required :input_tokens_details, -> { OpenAI::BatchUsage::InputTokensDetails }
+
+      # @!attribute output_tokens
+      #   The number of output tokens.
+      #
+      #   @return [Integer]
+      required :output_tokens, Integer
+
+      # @!attribute output_tokens_details
+      #   A detailed breakdown of the output tokens.
+      #
+      #   @return [OpenAI::Models::BatchUsage::OutputTokensDetails]
+      required :output_tokens_details, -> { OpenAI::BatchUsage::OutputTokensDetails }
+
+      # @!attribute total_tokens
+      #   The total number of tokens used.
+      #
+      #   @return [Integer]
+      required :total_tokens, Integer
+
+      # @!method initialize(input_tokens:, input_tokens_details:, output_tokens:, output_tokens_details:, total_tokens:)
+      #   Represents token usage details including input tokens, output tokens, a
+      #   breakdown of output tokens, and the total tokens used. Only populated on batches
+      #   created after September 7, 2025.
+      #
+      #   @param input_tokens [Integer] The number of input tokens.
+      #
+      #   @param input_tokens_details [OpenAI::Models::BatchUsage::InputTokensDetails] A detailed breakdown of the input tokens.
+      #
+      #   @param output_tokens [Integer] The number of output tokens.
+      #
+      #   @param output_tokens_details [OpenAI::Models::BatchUsage::OutputTokensDetails] A detailed breakdown of the output tokens.
+      #
+      #   @param total_tokens [Integer] The total number of tokens used.
+
+      # @see OpenAI::Models::BatchUsage#input_tokens_details
+      class InputTokensDetails < OpenAI::Internal::Type::BaseModel
+        # @!attribute cached_tokens
+        #   The number of tokens that were retrieved from the cache.
+        #   [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching).
+        #
+        #   @return [Integer]
+        required :cached_tokens, Integer
+
+        # @!method initialize(cached_tokens:)
+        #   Some parameter documentations has been truncated, see
+        #   {OpenAI::Models::BatchUsage::InputTokensDetails} for more details.
+        #
+        #   A detailed breakdown of the input tokens.
+        #
+        #   @param cached_tokens [Integer] The number of tokens that were retrieved from the cache. [More on
+      end
+
+      # @see OpenAI::Models::BatchUsage#output_tokens_details
+      class OutputTokensDetails < OpenAI::Internal::Type::BaseModel
+        # @!attribute reasoning_tokens
+        #   The number of reasoning tokens.
+        #
+        #   @return [Integer]
+        required :reasoning_tokens, Integer
+
+        # @!method initialize(reasoning_tokens:)
+        #   A detailed breakdown of the output tokens.
+        #
+        #   @param reasoning_tokens [Integer] The number of reasoning tokens.
+      end
+    end
+  end
+end

lib/openai/models/responses/response_custom_tool_call_output.rb

@@ -11,10 +11,11 @@ class ResponseCustomToolCallOutput < OpenAI::Internal::Type::BaseModel
         required :call_id, String
 
         # @!attribute output
-        #   The output from the custom tool call generated by your code.
+        #   The output from the custom tool call generated by your code. Can be a string or
+        #   an list of output content.
         #
-        #   @return [String]
-        required :output, String
+        #   @return [String, Array<OpenAI::Models::Responses::ResponseInputText, OpenAI::Models::Responses::ResponseInputImage, OpenAI::Models::Responses::ResponseInputFile>]
+        required :output, union: -> { OpenAI::Responses::ResponseCustomToolCallOutput::Output }
 
         # @!attribute type
         #   The type of the custom tool call output. Always `custom_tool_call_output`.
@@ -36,11 +37,53 @@ class ResponseCustomToolCallOutput < OpenAI::Internal::Type::BaseModel
         #
         #   @param call_id [String] The call ID, used to map this custom tool call output to a custom tool call.
         #
-        #   @param output [String] The output from the custom tool call generated by your code.
+        #   @param output [String, Array<OpenAI::Models::Responses::ResponseInputText, OpenAI::Models::Responses::ResponseInputImage, OpenAI::Models::Responses::ResponseInputFile>] The output from the custom tool call generated by your code.
         #
         #   @param id [String] The unique ID of the custom tool call output in the OpenAI platform.
         #
         #   @param type [Symbol, :custom_tool_call_output] The type of the custom tool call output. Always `custom_tool_call_output`.
+
+        # The output from the custom tool call generated by your code. Can be a string or
+        # an list of output content.
+        #
+        # @see OpenAI::Models::Responses::ResponseCustomToolCallOutput#output
+        module Output
+          extend OpenAI::Internal::Type::Union
+
+          # A string of the output of the custom tool call.
+          variant String
+
+          # Text, image, or file output of the custom tool call.
+          variant -> { OpenAI::Models::Responses::ResponseCustomToolCallOutput::Output::OutputContentListArray }
+
+          # A text input to the model.
+          module OutputContentList
+            extend OpenAI::Internal::Type::Union
+
+            discriminator :type
+
+            # A text input to the model.
+            variant :input_text, -> { OpenAI::Responses::ResponseInputText }
+
+            # An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision).
+            variant :input_image, -> { OpenAI::Responses::ResponseInputImage }
+
+            # A file input to the model.
+            variant :input_file, -> { OpenAI::Responses::ResponseInputFile }
+
+            # @!method self.variants
+            #   @return [Array(OpenAI::Models::Responses::ResponseInputText, OpenAI::Models::Responses::ResponseInputImage, OpenAI::Models::Responses::ResponseInputFile)]
+          end
+
+          # @!method self.variants
+          #   @return [Array(String, Array<OpenAI::Models::Responses::ResponseInputText, OpenAI::Models::Responses::ResponseInputImage, OpenAI::Models::Responses::ResponseInputFile>)]
+
+          # @type [OpenAI::Internal::Type::Converter]
+          OutputContentListArray =
+            OpenAI::Internal::Type::ArrayOf[union: -> {
+              OpenAI::Responses::ResponseCustomToolCallOutput::Output::OutputContentList
+            }]
+        end
       end
     end
   end

lib/openai/models/responses/response_function_call_arguments_done_event.rb

@@ -16,6 +16,12 @@ class ResponseFunctionCallArgumentsDoneEvent < OpenAI::Internal::Type::BaseModel
         #   @return [String]
         required :item_id, String
 
+        # @!attribute name
+        #   The name of the function that was called.
+        #
+        #   @return [String]
+        required :name, String
+
         # @!attribute output_index
         #   The index of the output item.
         #
@@ -33,13 +39,15 @@ class ResponseFunctionCallArgumentsDoneEvent < OpenAI::Internal::Type::BaseModel
         #   @return [Symbol, :"response.function_call_arguments.done"]
         required :type, const: :"response.function_call_arguments.done"
 
-        # @!method initialize(arguments:, item_id:, output_index:, sequence_number:, type: :"response.function_call_arguments.done")
+        # @!method initialize(arguments:, item_id:, name:, output_index:, sequence_number:, type: :"response.function_call_arguments.done")
         #   Emitted when function-call arguments are finalized.
         #
         #   @param arguments [String] The function-call arguments.
         #
         #   @param item_id [String] The ID of the item.
         #
+        #   @param name [String] The name of the function that was called.
+        #
         #   @param output_index [Integer] The index of the output item.
         #
         #   @param sequence_number [Integer] The sequence number of this event.

lib/openai/models/responses/response_function_call_output_item.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Models
+    module Responses
+      # A text input to the model.
+      module ResponseFunctionCallOutputItem
+        extend OpenAI::Internal::Type::Union
+
+        discriminator :type
+
+        # A text input to the model.
+        variant :input_text, -> { OpenAI::Responses::ResponseInputTextContent }
+
+        # An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision)
+        variant :input_image, -> { OpenAI::Responses::ResponseInputImageContent }
+
+        # A file input to the model.
+        variant :input_file, -> { OpenAI::Responses::ResponseInputFileContent }
+
+        # @!method self.variants
+        #   @return [Array(OpenAI::Models::Responses::ResponseInputTextContent, OpenAI::Models::Responses::ResponseInputImageContent, OpenAI::Models::Responses::ResponseInputFileContent)]
+      end
+    end
+  end
+end

lib/openai/models/responses/response_function_call_output_item_list.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module OpenAI
+  module Models
+    module Responses
+      # @type [OpenAI::Internal::Type::Converter]
+      ResponseFunctionCallOutputItemList =
+        OpenAI::Internal::Type::ArrayOf[union: -> { OpenAI::Responses::ResponseFunctionCallOutputItem }]
+    end
+  end
+end

lib/openai/models/responses/response_function_tool_call_output_item.rb

@@ -17,10 +17,11 @@ class ResponseFunctionToolCallOutputItem < OpenAI::Internal::Type::BaseModel
         required :call_id, String
 
         # @!attribute output
-        #   A JSON string of the output of the function tool call.
+        #   The output from the function call generated by your code. Can be a string or an
+        #   list of output content.
         #
-        #   @return [String]
-        required :output, String
+        #   @return [String, Array<OpenAI::Models::Responses::ResponseInputText, OpenAI::Models::Responses::ResponseInputImage, OpenAI::Models::Responses::ResponseInputFile>]
+        required :output, union: -> { OpenAI::Responses::ResponseFunctionToolCallOutputItem::Output }
 
         # @!attribute type
         #   The type of the function tool call output. Always `function_call_output`.
@@ -44,12 +45,54 @@ class ResponseFunctionToolCallOutputItem < OpenAI::Internal::Type::BaseModel
         #
         #   @param call_id [String] The unique ID of the function tool call generated by the model.
         #
-        #   @param output [String] A JSON string of the output of the function tool call.
+        #   @param output [String, Array<OpenAI::Models::Responses::ResponseInputText, OpenAI::Models::Responses::ResponseInputImage, OpenAI::Models::Responses::ResponseInputFile>] The output from the function call generated by your code.
         #
         #   @param status [Symbol, OpenAI::Models::Responses::ResponseFunctionToolCallOutputItem::Status] The status of the item. One of `in_progress`, `completed`, or
         #
         #   @param type [Symbol, :function_call_output] The type of the function tool call output. Always `function_call_output`.
 
+        # The output from the function call generated by your code. Can be a string or an
+        # list of output content.
+        #
+        # @see OpenAI::Models::Responses::ResponseFunctionToolCallOutputItem#output
+        module Output
+          extend OpenAI::Internal::Type::Union
+
+          # A string of the output of the function call.
+          variant String
+
+          # Text, image, or file output of the function call.
+          variant -> { OpenAI::Models::Responses::ResponseFunctionToolCallOutputItem::Output::OutputContentListArray }
+
+          # A text input to the model.
+          module OutputContentList
+            extend OpenAI::Internal::Type::Union
+
+            discriminator :type
+
+            # A text input to the model.
+            variant :input_text, -> { OpenAI::Responses::ResponseInputText }
+
+            # An image input to the model. Learn about [image inputs](https://platform.openai.com/docs/guides/vision).
+            variant :input_image, -> { OpenAI::Responses::ResponseInputImage }
+
+            # A file input to the model.
+            variant :input_file, -> { OpenAI::Responses::ResponseInputFile }
+
+            # @!method self.variants
+            #   @return [Array(OpenAI::Models::Responses::ResponseInputText, OpenAI::Models::Responses::ResponseInputImage, OpenAI::Models::Responses::ResponseInputFile)]
+          end
+
+          # @!method self.variants
+          #   @return [Array(String, Array<OpenAI::Models::Responses::ResponseInputText, OpenAI::Models::Responses::ResponseInputImage, OpenAI::Models::Responses::ResponseInputFile>)]
+
+          # @type [OpenAI::Internal::Type::Converter]
+          OutputContentListArray =
+            OpenAI::Internal::Type::ArrayOf[union: -> {
+              OpenAI::Responses::ResponseFunctionToolCallOutputItem::Output::OutputContentList
+            }]
+        end
+
         # The status of the item. One of `in_progress`, `completed`, or `incomplete`.
         # Populated when items are returned via API.
         #